# Assistants migration guide
We're moving from the Assistants API to the new [Responses API](https://developers.openai.com/api/docs/guides/responses-vs-chat-completions) for a simpler and more flexible mental model. Responses are simpler—send input items and get output items back. With the Responses API, you also get better performance and new features like [deep research](https://developers.openai.com/api/docs/guides/deep-research), [MCP](https://developers.openai.com/api/docs/guides/tools-remote-mcp), and [computer use](https://developers.openai.com/api/docs/guides/tools-computer-use). This change also lets you manage conversations instead of passing back `previous_response_id`. ### What's changed?
Before Now Why?
`Assistants` `Prompts` Prompts hold configuration (model, tools, instructions) and are easier to version and update
`Threads` `Conversations` Streams of items instead of just messages
`Runs` `Responses` Responses send input items or use a conversation object and receive output items; tool call loops are explicitly managed
`Run steps` `Items` Generalized objects—can be messages, tool calls, outputs, and more
## From assistants to prompts Assistants were persistent API objects that bundled model choice, instructions, and tool declarations—created and managed entirely through the API. Their replacement, prompts, can only be created in the dashboard, where you can version them as you develop your product. ### Why this is helpful - **Portability and versioning**: You can snapshot, review, diff, and roll back prompt specs. You can also version a prompt, so your code can just point the latest version. - **Separation of concerns**: Your application code now handles orchestration (history pruning, tool loop, retries) while your prompt focuses on high‑level behavior and constraints (system guidance, tool availability, structured output schema, temperature defaults). - **Realtime compatibility**: The same prompt configuration can be reused when you connect through the Realtime API, giving you a single definition of behavior across chat, streaming, and low‑latency interactive sessions. - **Tool and output consistency**: Using prompts, every Responses or Realtime session you start inherits a consistent contract because prompts encapsulate tool schemas and structured output expectations. ### Practical migration steps 1. Identify each existing Assistant’s _instruction + tool_ bundle. 2. In the dashboard, recreate that bundle as a named prompt. 3. Store the prompt ID (or its exported spec) in source control so application code can refer to a stable identifier. 4. During rollout, run A/B tests by swapping prompt IDs—no need to create or delete assistant objects programmatically. Think of a prompt as a **versioned behavioral profile** to plug into either Responses or Realtime API. --- ## From threads to conversations A thread was a collection of messages stored server-side. Threads could _only_ store messages. Conversations store items, which can include messages, tool calls, tool outputs, and other data. ### Request example ### Response example --- ## From runs to responses Runs were asynchronous processes that executed against threads. See the example below. Responses are simpler: provide a set of input items to execute, and get a list of output items back. Responses are designed to be used alone, but you can also use them with prompt and conversation objects for storing context and configuration. ### Request example ### Response example **“If you can dodge a wrench, you can dodge a ball!”**\n\nThese 5 Ds are not official competitive rules, but have become a fun and memorable pop culture reference for the sport of dodgeball.", "type": "output_text", "logprobs": [] } ], "role": "assistant", "status": "completed", "type": "message" } ], "parallel_tool_calls": true, "temperature": 1.0, "tool_choice": "auto", "tools": [], "top_p": 1.0, "background": false, "max_output_tokens": null, "previous_response_id": null, "reasoning": { "effort": null, "generate_summary": null, "summary": null }, "service_tier": "scale", "status": "completed", "text": { "format": { "type": "text" } }, "truncation": "disabled", "usage": { "input_tokens": 17, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 150, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 167 }, "user": null, "max_tool_calls": null, "store": true, "top_logprobs": 0 } `, title: "Response object", }, ]} /> --- ## Migrating your integration Follow the migration steps below to move from the Assistants API to the Responses API, without losing any feature support. ### 1. Create prompts from your assistants 1. Identify the most important assistant objects in your application. 1. Find these in the dashboard and click `Create prompt`. This will create a prompt object out of each existing assistant object. Reusable prompt objects are also being deprecated. If you use this migration path, review the [prompts deprecation timeline](https://developers.openai.com/api/docs/deprecations#2026-06-03-reusable-prompts) before adopting prompt objects in a long-lived integration. ### 2. Move new user chats over to conversations and responses We will not provide an automated tool for migrating Threads to Conversations. Instead, we recommend migrating new user threads onto conversations and backfilling old ones as necessary. Here's an example for how you might backfill a thread: ```python thread_id = "thread_EIpHrTAVe0OzoLQg3TXfvrkG" for page in openai.beta.threads.messages.list(thread_id=thread_id, order="asc").iter_pages(): messages += page.data items = [] for m in messages: item = {"role": m.role} item_content = [] for content in m.content: match content.type: case "text": item_content_type = "input_text" if m.role == "user" else "output_text" item_content += [{"type": item_content_type, "text": content.text.value}] case "image_url": item_content + [ { "type": "input_image", "image_url": content.image_url.url, "detail": content.image_url.detail, } ] item |= {"content": item_content} items.append(item) # create a conversation with your converted items conversation = openai.conversations.create(items=items) ``` ## Comparing full examples Here’s a few simple examples of integrations using both the Assistants API and the Responses API so you can see how they compare. ### User chat app
```python thread = openai.threads.create() @app.post("/messages") async def message(message: Message): openai.beta.threads.messages.create( role="user", content=message.content ) run = openai.beta.threads.runs.create( assistant_id=os.getenv("ASSISTANT_ID"), thread_id=thread.id ) while run.status in ("queued", "in_progress"): await asyncio.sleep(1) run = openai.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id) messages = openai.beta.threads.messages.list( order="desc", limit=1, thread_id=thread.id ) return { "content": messages[-1].content } ```