Assistants to Responses skill for Codex

The OpenAI Assistants API was deprecated in August 2025 and shut down on 26 August 2026. Any code path still calling beta.assistants, beta.threads or threads.runs is broken or about to be. Migration is done when no Assistants calls remain, every existing user conversation either continues in a Conversation or is explicitly archived, tool loops run in your code with caps, and behaviour on a replay set matches the old app.

Concept map

Assistants API	Responses API	What changes for you
Assistant (model, instructions, tools)	instructions + tools in code, or a Prompt object (prompt={"id": ...})	Config moves into version control (or a dashboard prompt)
Thread	Conversation (conversations.create)	Holds items: messages, tool calls, tool outputs
Message	Item (message with input_text / output_text content)	Typed content parts
Run + polling	responses.create (synchronous, streamed, or background=True)	No polling loop for normal calls
Run step	Output items (function_call, file_search_call, code_interpreter_call, message)	Inspect response.output by type
requires_action / submit_tool_outputs	function_call items answered by function_call_output items in the next request	Your code owns the loop
tool_resources on assistant/thread	vector_store_ids on the file_search tool; container on code_interpreter	Per request
additional_instructions	instructions on that request	Not inherited across turns
response_format	text={"format": ...}	Structured outputs syntax
truncation_strategy	truncation="auto" or compaction	Context management

Full parameter, event and annotation mapping: read references/mapping.md when converting a specific call site or streaming handler.

Inventory before changing code

1. Read AGENTS.md, then find every call site: rg -n "beta\.(assistants|threads)|threads\.runs|submit_tool_outputs|create_and_poll|assistant_id|thread_id" .
2. List each assistant the code references (ids in env vars or the DB) with model, instructions, tools, vector stores and files. The dashboard may still show them for reference even though the API is gone; copy the instructions and tool schemas into the repo now.
3. Find where thread ids are stored (users table, sessions). That is your mapping table.
4. Find your own copy of message history. Since shutdown, thread messages can no longer be listed through the API, so history exists only if your app stored it (or an export was taken before shutdown). Tell the user plainly if it does not exist.
5. Vector stores and uploaded files are separate resources used by Responses file_search; confirm they still list (client.vector_stores.list()) and reuse them.

Decisions

Question	Default	Alternative
Where do instructions and tools live?	In code, versioned in git, one module per former assistant	Dashboard Prompt objects when non-engineers edit prompts; check OpenAI’s deprecation notes for reusable prompts before depending on them
How is state kept?	Conversations (conversation=conv_id) for user-visible chats	previous_response_id chaining for short flows; full client-side history with store=False for zero-retention requirements
Old history	Backfill into a new Conversation per thread	Archive read-only in your DB and start fresh conversations
Long-running runs	Synchronous or streamed responses.create	background=True and poll responses.retrieve(id) for tasks over a few minutes

Code: before and after

# BEFORE (no longer works)
run = client.beta.threads.runs.create_and_poll(thread_id=thread_id, assistant_id=ASSISTANT_ID)
if run.status == "requires_action":
    outputs = [{"tool_call_id": tc.id, "output": run_tool(tc)}
               for tc in run.required_action.submit_tool_outputs.tool_calls]
    client.beta.threads.runs.submit_tool_outputs_and_poll(
        thread_id=thread_id, run_id=run.id, tool_outputs=outputs)

# AFTER
import json
from openai import OpenAI
client = OpenAI()

SUPPORT = {                                  # was assistant asst_...
    "model": "gpt-5-mini",                   # pick and evaluate; do not assume the old model
    "instructions": open("prompts/support.md").read(),
    "tools": [
        {"type": "file_search", "vector_store_ids": ["vs_abc123"]},
        {"type": "function", "name": "get_order", "description": "Look up an order by id.",
         "parameters": {"type": "object", "properties": {"order_id": {"type": "string"}},
                        "required": ["order_id"], "additionalProperties": False},
         "strict": True},
    ],
}

def reply(conversation_id: str, user_text: str) -> str:
    resp = client.responses.create(**SUPPORT, conversation=conversation_id,
                                   input=[{"role": "user", "content": user_text}])
    for _ in range(6):                                       # cap tool rounds
        calls = [o for o in resp.output if o.type == "function_call"]
        if not calls:
            return resp.output_text
        outputs = [{"type": "function_call_output", "call_id": c.call_id,
                    "output": json.dumps(run_tool(c.name, json.loads(c.arguments)))}
                   for c in calls]
        resp = client.responses.create(**SUPPORT, conversation=conversation_id, input=outputs)
    raise RuntimeError("tool loop did not finish")

instructions apply to one request only; send them on every call (the module dict does this). Tool calls and outputs are appended to the conversation automatically when you pass conversation.

Backfilling threads into conversations

def to_items(messages):          # from your own stored history, oldest first
    items = []
    for m in messages:
        part = "input_text" if m.role == "user" else "output_text"
        content = [{"type": part, "text": m.text}]
        if m.role == "user" and m.image_url:
            content.append({"type": "input_image", "image_url": m.image_url, "detail": "auto"})
        items.append({"type": "message", "role": m.role, "content": content})
    return items

conv = client.conversations.create(items=to_items(history[-40:]),
                                   metadata={"legacy_thread_id": thread_id, "user_id": uid})
db.update_user_session(uid, conversation_id=conv.id)

• Backfill only recent turns (or a summary plus recent turns); full histories cost tokens on every future request.
• Run the backfill as an idempotent job keyed on the legacy thread id; it can be resumed.
• Writing to production data and creating conversations for every user is a bulk operation: show the plan and counts to the user and get confirmation before running it.

Cutover checklist

• Inventory call sites, assistants, vector stores, thread id storage, history source
• Copy instructions and tool schemas into the repo
• Build the Responses wrapper with tool loop, caps and logging
• Map streaming handlers to Responses events (references/mapping.md)
• Render file_citation / url_citation annotations from output_text parts
• Backfill or archive old threads (after user confirmation); store conversation ids
• Replay 30-100 real conversations through old transcripts vs new path and compare
• Remove all beta.assistants / beta.threads code and dead env vars
• Deploy behind a flag; confirm with the user before the production rollout

Verification

• rg for Assistants call sites returns nothing.
• Replay set: answers are judged equivalent or better (use llm-evals graders), tool calls hit the same functions with valid arguments, citations render.
• Token and cost per conversation are logged; compare against the old app’s usage export.
• A migrated user opens an old chat and the next answer uses the backfilled context.

Gotchas

• previous_response_id and conversation are alternatives; using both errors or duplicates context.
• Responses default to store=True. If the old app relied on zero-retention settings, set store=False and replay context yourself (reasoning items need include=["reasoning.encrypted_content"]).
• Function call ids: answer with call_id, not the item id.
• Code interpreter files are now container files; download them through the containers API before the container expires, not through the old file ids.
• Model behaviour changes with the model, not the API. Evaluate the model choice separately from the plumbing migration.