Kingy AI
Subscribe, 2.1M subscribersWork with Kingy
AI News

Assistants API to Responses and Conversations: Complete Migration Guide

August 23, 2026 AI
Legacy assistant message stacks crossing a controlled bridge into a modern conversation and response architecture

Migration verdict: treat this as a state-model migration, not an endpoint rename. OpenAI officially sunset the Assistants API on August 26, 2026, and says it is no longer available. The supported destination is the Responses API plus the Conversations API. New conversations should move first; old Threads should be backfilled only when they are still needed.

For the wider decision path, continue through Kingy’s Model Economics and Migrations hub to connect this migration with pricing evidence, provider comparisons and canonical API records.

Source audit: checked against current OpenAI documentation on August 27, 2026. Track the underlying deadline on the AI Stack Change Radar and its Assistants API change record.

What broke on August 26

Requests to the Assistants API are no longer a viable production path. Applications that create or retrieve Assistants, Threads, Messages, Runs or Run Steps through the beta Assistants surface need a replacement. The important object mapping is:

Assistants API Replacement Migration consequence
Assistant Prompt or application configuration Move model, instructions and tool configuration into a versioned prompt or your code/configuration layer.
Thread Conversation Store a new Conversation ID beside your own user/session key.
Message Input/output item Expect conversations to contain tool calls and tool outputs as well as messages.
Run Response Replace run polling and status handling with Responses API handling, streaming or background-mode logic as appropriate.
Run Step Response item Update tracing, audit logs and tool-call parsers to consume typed response items.

Do not assume that preserving the same prompt text preserves the same behavior. State representation, tool-call events, retry logic, streaming events and observability all change.

Who is affected

  • Applications that reference client.beta.assistants or client.beta.threads.
  • Backends that persist assistant_id, thread_id, run_id or Run Step IDs.
  • Tool integrations that submit outputs to an active Run.
  • Support, compliance or analytics systems that reconstruct a session from Thread Messages.
  • Queues that poll Run status or assume one active Run per Thread.

If your application already calls client.responses.create() and either passes a Conversation ID or manages state explicitly, this deadline may not affect that path.

Prerequisites

  1. Inventory every Assistants call. Search code, workers, notebooks and scheduled jobs for Assistants, Threads, Runs and Run Steps.
  2. Record the current contract. Save representative prompts, tool schemas, expected outputs, latency, token use, error rates and safety behavior.
  3. Separate configuration from state. Decide whether model/instructions/tools live in a versioned OpenAI Prompt or in your application.
  4. Add dual identifiers. Your data model needs room for both the legacy thread_id and a new conversation_id during rollout.
  5. Pin a current OpenAI SDK. Upgrade in a branch and verify the Conversations and Responses methods used by your language SDK.

Exact migration steps

1. Freeze the legacy baseline

Capture at least 50 representative sessions, including tool success, tool failure, long conversations, file retrieval, malformed tool output, timeout and moderation cases. Store expected assertions rather than only screenshots.

2. Replace the Assistant with a versioned configuration

Create a reusable Prompt in the OpenAI dashboard or move the Assistant’s model, instructions and tools into source-controlled application configuration. Record the Prompt ID and version. Preserve a read-only export of the legacy Assistant configuration for audit and reconstruction.

3. Create a Conversation for each new session

from openai import OpenAI
import os

client = OpenAI()

conversation = client.conversations.create(
    metadata={"app_session_id": "session_123"}
)

response = client.responses.create(
    prompt={"id": os.environ["OPENAI_PROMPT_ID"]},
    conversation=conversation.id,
    input=[{
        "role": "user",
        "content": "Summarize the customer issue and propose the next action."
    }],
)

print(response.output_text)

Persist conversation.id against your own session key. A Conversation can store messages, tool calls, tool outputs and other items, so downstream readers must not assume every item is a user or assistant message.

4. Rebuild tool execution around response items

Keep tool schemas strict and versioned. When a response asks for a function call, validate its name and arguments, run the tool with least privilege, submit the tool output using the current Responses API pattern, and continue until a terminal response is reached. Add idempotency at your tool boundary so a retry cannot repeat a payment, ticket update or destructive write.

5. Change state lookup

Replace “load Thread, append Message, create Run” with “load Conversation ID, create Response with new input.” Keep the application session key as the durable lookup key; OpenAI object IDs should be replaceable implementation details.

6. Move new traffic before old history

OpenAI explicitly says it will not provide an automated Threads-to-Conversations migration tool. Route new chats to Conversations immediately. Backfill an old Thread only when a user resumes it or when retention requirements justify the work. For each backfill, list the Thread messages in chronological order, transform supported text/image parts into Conversation items, create the Conversation, and record a one-time mapping from Thread ID to Conversation ID.

7. Update observability

Log response IDs, conversation IDs, prompt version, model, tool-call IDs, finish state, latency, input/output tokens and error class. Do not carry Run Step dashboards forward unchanged; rebase them on response items and tool events.

Code and configuration checklist

  • Remove new writes to client.beta.assistants and client.beta.threads.
  • Add OPENAI_PROMPT_ID and, if used, a pinned prompt version to deployment configuration.
  • Add conversation_id beside—not over—thread_id until rollback closes.
  • Replace Run polling with Responses streaming, background processing or direct response handling appropriate to the workload.
  • Update event parsers and audit schemas for response items.
  • Make every state write and tool side effect idempotent.

Tests that must pass

  • Golden behavior: required facts, refusal behavior and tool selection match approved expectations.
  • Conversation continuity: a five-turn session preserves relevant facts without duplicating tool output.
  • Tool contract: valid calls succeed; invalid arguments fail closed; repeated calls do not repeat side effects.
  • Ordering: concurrent user messages and tool results do not corrupt state.
  • Failure recovery: timeouts, 429s and 5xx responses use bounded retries and remain observable.
  • Cost and latency: p50/p95 latency and token cost stay inside explicit release thresholds.
  • Backfill: resumed Threads preserve the required user-visible history after selective conversion.
  • Data controls: retention, deletion, access and regional-processing requirements remain satisfied.

Staged rollout

  1. Fixture shadow: replay captured sessions against Responses in a non-production environment.
  2. Staff canary: route employee traffic and synthetic monitors to the new Responses implementation.
  3. One percent: enable the new Responses build for a small cohort of sessions.
  4. Ten to fifty percent: expand by tenant while watching tool errors, latency, cost and safety metrics.
  5. Full cutover: promote the validated Responses path and retain the last-known-good Responses build.
  6. Selective history conversion: convert only the legacy history that users or retention requirements still need.

Rollback

The provider-level rollback to Assistants is closed. Use a server-side flag between the current and last-known-good Responses implementation, preserve the previous prompt/configuration version, keep Conversation mappings and migration ledgers immutable, and make schema changes backward compatible. If a release threshold fails, stop the rollout and restore the last validated Responses build and configuration.

Do not attempt to recover by calling Assistants, deleting Conversations or overwriting Thread mappings. After the August 26 sunset, recovery is a Responses-side rollback or fix-forward.

Replacement options and limitations

Recommended: Responses API plus Conversations API, with Prompts or application configuration replacing Assistant objects. previous_response_id can be useful for some short-lived chains, but Conversations are the closer match when the application needs a durable server-side container.

Limitations to plan for: no automated Thread migration; item types are broader than messages; a new tool loop and event model; possible output differences even with identical instructions; and no provider-level rollback to the now-unavailable Assistants API.

The useful “graveyard” lesson

The Assistants API belongs in historical context, but a separate AI tool graveyard would not help a team ship. The reusable lesson is operational: vendor-managed objects can disappear while the user’s session still matters. Keep your own durable session key, version prompts and tool contracts, isolate provider IDs, and preserve a reversible routing layer. This guide is where that history becomes an actionable migration pattern.

Official sources

Bottom line: the Assistants API is already unavailable. Move remaining workloads to Responses now, use Conversations where durable state is required, preserve legacy mappings for audit, and roll back only between validated Responses implementations.