From Assistants API to Responses API: Migration Guide & Best Practices

OpenAI shut down the Assistants API on August 26, 2026, so apps that still call it no longer work. The replacement is the Responses API, with the Conversations API for long-lived conversation state. To migrate, move your assistant instructions and tools into your own code, rebuild each turn as a responses.create call, recreate conversations from the messages you stored, switch to built-in tools, and test multi-turn flows before you roll out.

• Status: OpenAI announced the deprecation on August 26, 2025, and removed the Assistants API on August 26, 2026. Old threads can no longer be retrieved through the API.
• Also retiring: reusable prompt objects (the v1/prompts API) and Agent Builder are scheduled to shut down on November 30, 2026. Keep prompt text in your application code.
• What's better: one request per turn replaces the assistant, thread, and run flow; built-in tools run inside that request; OpenAI reports 40–80% better cache utilization than Chat Completions in its internal tests.
• What to watch: the instructions parameter isn't carried between calls, previous_response_id history expires after 30 days, and built-in tools like file search are billed per call.

Assistants API sunset: where things stand

Date	What happens	What it means for you
August 26, 2025	OpenAI announced the Assistants API deprecation	One year's notice to migrate
June 3, 2026	OpenAI announced the retirement of reusable prompts and Agent Builder	Prompt objects are no longer a safe target for migrated assistants
August 26, 2026	The Assistants API was removed	Calls fail, and threads can't be retrieved
November 30, 2026 (scheduled)	v1/prompts, reusable prompt objects, and Agent Builder are scheduled to shut down	Requests that reference prompt IDs will stop working

The official sources are OpenAI's deprecations page, its migration guide, and the Assistants migration notes.

If your support bot still depended on the Assistants API, it stopped answering on August 26. The fastest fix is to rebuild the conversation flow on the Responses API, using the conversation history you kept in your own database. OpenAI's migration guide describes only a manual copy of messages into conversations.

sbb-itb-97114f1

What the Responses API is and why it matters

The Responses API is OpenAI's interface for building agents. The Assistants API needed several objects and calls for one exchange: an assistant, a thread, messages, and a run you had to poll. The Responses API handles each turn in one request that includes the model, instructions, input, and tools.

This video gives a walkthrough of the Responses API:

Here's how the old objects map to the new ones:

Assistants API	Responses API	Note
Assistant (model, instructions, tools)	Instructions and tools sent with each request from your code	OpenAI's prompt objects retire on November 30, 2026, so don't move assistants there
Thread	Conversation (Conversations API)	Copy messages manually from your stored records
Run	Response	Returned directly, no polling
Run steps	Items	Items include messages, tool calls, and tool outputs

A simpler development process

One request replaces creating an assistant, creating a thread, adding messages, starting a run, and polling its status. There's less boilerplate code and fewer places for errors to hide.

Your own function tools still run in a loop: the model returns a function call, your code runs it, and you send the output back in a follow-up request. Built-in tools are the ones OpenAI runs inside a single request.

That matters most for small teams. You can build and maintain an AI customer service agent without managing a multi-object API structure.

Built-in tools and conversation state

The Responses API includes tools that used to need custom integrations:

• Web search (web_search) for current information.
• File search (file_search) over your documents, with metadata filters.
• Code interpreter (code_interpreter) for calculations and code execution.
• Computer use for interacting with applications.
• Remote MCP servers for connecting other tools through the Model Context Protocol.

The model can call several tools in one request, which OpenAI calls the agentic loop.

For conversation state, you have two options. Pass previous_response_id to continue from the last response, or attach the request to a conversation through the Conversations API. You can't combine the two in one request. OpenAI's conversation state guide covers both. Responses are stored by default (store: true); set store: false to opt out. Stored responses used with previous_response_id are kept for 30 days, while conversations aren't subject to that limit.

The Responses API also accepts text and images natively, so an agent can help with questions that include a screenshot.

Performance and cost

In OpenAI's internal tests, the Responses API showed 40–80% better cache utilization than Chat Completions. Better caching means fewer full-price input tokens on repeated context, which lowers cost for high-volume support.

Some costs work differently, though. When you continue with previous_response_id, earlier turns count as input tokens. Built-in tools are billed per use. At the time of writing, OpenAI's pricing lists file search at $2.50 per 1,000 calls plus $0.10 per GB per day of storage after the first free GB, and web search at $10 per 1,000 calls plus the search content tokens at model rates.

Feature	Assistants API (removed)	Responses API
Architecture	Multi-step: assistant, thread, run, polling	One request per turn; your own function calls need a follow-up request with the output
Tools	File search and code interpreter on the assistant; others custom	Built-in web search, file search, code interpreter, computer use, MCP
Conversation state	Server-side threads	previous_response_id (30 days) or Conversations API
Instructions	Stored on the assistant	Sent with each request

Common pain points with the Assistants API

Developers who ran support bots on the Assistants API reported a few recurring pain points, many of them in OpenAI's community forum. They explain why the new design looks the way it does:

• Polling delays. Apps that didn't stream had to poll a run's status, so the first words could take several seconds.
• Thread locks. While a run was active, you couldn't add messages to its thread. A customer's follow-up had to wait until the run finished.
• Stuck runs. Under load, some runs stayed in "running" status, and cancelling them could hang, forcing a new thread.
• Scattered debugging data. Threads stored messages, while tool calls lived in separate run steps. Rebuilding why the AI gave an answer meant pulling data from several objects.
• Configuration in OpenAI's system. Tools and instructions lived on assistant objects stored with OpenAI, which made versioning and A/B tests awkward.
• Vector store drift. Some developers reported files in vector stores falling out of sync with their own records, which showed up as wrong answers.

The Responses API changes the shape of most of these: the result comes from the request itself, and tool calls are items next to messages. Configuration now lives in your code, and vector stores still need regular checks.

Step-by-step migration guide: Assistants API to Responses API

Step 1: Inventory your current setup

List every assistant you used, with its model, instructions, tools, and vector stores. Find every place your code creates threads, adds messages, starts runs, or polls status. Note any custom tools and outside systems your assistants called.

Then check where your conversation history lives. Since threads can no longer be retrieved, the messages you stored in your own database are now the only source for past conversations.

Step 2: Rebuild your API calls and state handling

Replace the thread, message, and run sequence with a responses.create call per turn that includes the model, instructions, input, and tools. Remove polling loops: responses return directly, and long tasks can run in background mode.

Send the instructions parameter with every request: it isn't carried over when you continue with previous_response_id. (A developer message passed in the input does stay in the chain.) Keep instructions in your code, under version control, instead of in OpenAI's prompt objects.

Choose a state strategy. Use previous_response_id for short exchanges, and the Conversations API when you need history that lasts longer than 30 days.

Step 3: Recreate conversations

OpenAI's guide describes only a manual copy of messages. Recreate the conversations you still need from your stored messages, starting with active ones, then older history if you need it. For new chats, start directly on the Responses API.

Step 4: Switch to built-in tools

Replace custom integrations with built-in tools where they fit:

• Swap a custom web search for the web_search tool.
• Move document retrieval to file_search with metadata filters.
• Run calculations with code_interpreter instead of an outside server.

List the tools in the request and let the model call them in one loop. Test each replacement on its own to confirm it matches the old behavior, and check the per-call cost against your volume.

Step 5: Test and validate

Test the cases that break most often:

• Multi-turn conversations that keep context through previous_response_id or a conversation.
• Tool chaining, where the model calls several tools in one request.
• Stateful and stateless behavior when you switch between store: true and store: false.
• Long conversations, where token usage grows with every turn.

Use realistic support scenarios, including technical questions, sarcasm, and upset customers. Combine automated scripts for routine flows with manual tests for edge cases.

Step 6: Deploy and monitor

Roll out in stages. Start in a staging environment, send new chats to the Responses API first, compare outputs with your previous system where you still can, and keep a rollback plan.

Track metrics per conversation instead of per thread or run: response time, error rate, token usage, tool call success, and cost. A dashboard with these numbers makes regressions visible early. Ask your support team for feedback, since they'll notice changes in the AI's answers first.

What most people get wrong during migration

Common mistake	What happens	The fix
Keeping polling loops and thread code	Dead code and needless delays	Use direct responses, previous_response_id, or conversations
Forgetting instructions	The AI loses its persona after the first turn	Send the instructions parameter with every request
Relying on previous_response_id for long-term history	Context disappears after 30 days	Use the Conversations API for durable history
Ignoring token and tool costs	Long conversations and frequent file searches raise the bill	Set token alerts, trim or summarize old turns, limit unnecessary tool calls
Moving assistants into prompt objects	Requests fail after November 30, 2026	Keep prompts in your application code
Incomplete testing	Context loss and broken tool chains in production	Test multi-turn flows, tool chaining, and long conversations

Missing state management changes

Some teams keep loops like while (runStatus.status !== 'completed') even though the Responses API returns results directly. Others pass only text when continuing a conversation. Items include tool calls and their outputs, and if you drop them, the agent loses track of what it did and why.

Forgetting instructions and long-term history

The instructions parameter applies only to the request it's sent with. If you send it once and then continue with previous_response_id, later turns run without your system prompt. And because responses used this way expire after 30 days, support conversations that customers reopen weeks later need the Conversations API.

Not watching tool and token costs

Every earlier turn you carry forward counts as input tokens, so long conversations get more expensive with each message. The truncation setting is off by default, so a request that overflows the context window fails. Setting it to "auto" drops the oldest items instead. That avoids the error but can drop context the answer needs, so treat it as a safety net. To control cost, trim or summarize old turns yourself. Built-in tools add per-call charges, so a support bot that runs file search on every message can cost more than you expect. Set alerts on token use per conversation and trigger file search only when it's needed.

Not using built-in tools

Teams sometimes keep a separate scraping service, vector database, or code server out of habit. Built-in tools let the model call several tools within one request, while outside services force you to orchestrate each call yourself. Compare quality and cost before you decide, and use built-ins where they do the job.

Skipping full testing

Many teams test only single-turn exchanges. Problems show up in longer conversations: lost context, broken tool chains, or different behavior with store: false. Test those paths before customers find them.

Practices that make migration easier

A few practices save time when you migrate:

• Run old and new systems in parallel. Route a small share of traffic to the new code first and compare answers. For anyone still migrating after the shutdown, compare against saved transcripts instead.
• Use typed SDKs. TypeScript type definitions in OpenAI's Node SDK (now version 7) catch structural changes during refactoring.
• Handle streaming carefully. Build wrappers for server-sent events and timeouts on long reasoning tasks, and handle error events explicitly.
• Reconcile vector stores. Run regular checks that compare the files in your vector stores with your own records, and fix drift automatically.
• Re-tune prompts for new models. Newer models behave differently from older ones, so check prompts and validation rules after each model change. Models retire on a schedule too: at the time of writing, OpenAI's deprecations page lists o4-mini for shutdown on October 23, 2026, and GPT-4o and GPT-4.1 on January 14, 2027.
• Keep the stack flexible. OpenAI's open-source Agents SDK uses the Responses API by default for OpenAI models and also works with other model providers, which keeps your options open.

What this means for customer support teams

For support teams, the Responses API makes it easier to build agents that keep context across a conversation, search your documents, and call tools in one step. It also means owning more of the plumbing yourself: instructions, conversation storage, tool costs, and model changes.

If you'd rather not maintain that integration, a support-specific platform handles it for you. CoSupport AI is one example: CoSupport AI Agent connects to helpdesks like Zendesk and Freshdesk, answers from your knowledge base and business systems, and hands off what it can't resolve. Shelterluv, for example, runs it on Zendesk. For a broader look at how these agents work, see our guide to AI agents in customer support.

Key takeaways

• The Assistants API was removed on August 26, 2026. Migrate to the Responses API and the Conversations API.
• Keep instructions and prompts in your own code. Prompt objects and Agent Builder are scheduled to retire on November 30, 2026.
• Recreate conversations from your stored messages, since threads can't be retrieved.
• Use built-in tools, but watch per-call costs and token growth in long conversations.
• Test multi-turn flows and tool chains before customers do.