Map the old objects before changing code

OpenAI maps the objects this way:

Inventory every place your application creates, reads, updates, or deletes those old objects. Search for /v1/assistants, /v1/threads, assistant_id, thread_id, run_id, required_action, and Assistants streaming event names. Include background workers and admin scripts; a forgotten cleanup job can fail after the visible chat path has already migrated.

Record which Assistant fields are actually used: model, instructions, tool schemas, file-search resources, Code Interpreter, metadata, response format, temperature, and token limits. This becomes the migration contract. Do not copy fields simply because they exist on the old object.

Keep behavior configuration in the application

An Assistant was a persistent API object that combined model choice, instructions, and tools. Responses accepts those parts directly on each request. For a long-lived integration, store the configuration in source control or your own versioned configuration service:

const supportAgent = {
  model: "gpt-5.6-terra",
  instructions: SUPPORT_INSTRUCTIONS_V3,
  tools: supportTools,
  text: { format: supportOutputSchema },
} as const;

const response = await client.responses.create({
  ...supportAgent,
  input: [{ role: "user", content: userMessage }],
  conversation: conversationId,
});

A configuration revision then appears in the same review as the calling code. This approach also avoids depending on reusable prompt objects that have their own November shutdown date. If your team uses a dashboard Prompt as a temporary bridge, pin its identifier and version, document the removal date, and plan the second cutover now.

Configuration versioning should be visible in telemetry. Attach an internal revision such as support-v3 to your trace and evaluation records without placing secrets in API metadata. The agent tracing guide explains how to connect a model call to its prompt, tool set, and result.

Move new chats before backfilling history

OpenAI says it will not provide an automated tool for converting Threads to Conversations. Its migration guide recommends sending new user chats to Conversations and Responses first, then migrating older threads as needed.

Move new sessions first to limit the deadline-critical change. Add a state-version field to your own session record:

assistant_v2 -> thread_id
responses_v1 -> conversation_id

New sessions receive responses_v1. Existing sessions can continue on the old path until the cutoff, be migrated when the user returns, or be closed according to the product's retention policy. Do not backfill dormant history just to preserve it.

When a thread must move, list its messages in ascending order, translate text and image content into Response input items, and create a Conversation with those items. Preserve roles and ordering. Test annotations, attachments, and tool-produced content separately because a Conversation holds generalized items rather than only messages.

Conversation storage also changes the privacy review. OpenAI's data-control table lists Conversations as application state retained until deletion and not eligible for Zero Data Retention. Products that require ZDR should use a stateless Responses pattern and manage the necessary history themselves. The ZDR audit guide covers that decision in detail.

Replace run polling with response handling

Assistants Runs were asynchronous jobs attached to Threads. Applications commonly created a Run, polled queued and in_progress, handled required_action, submitted function outputs, and then fetched messages or run steps.

Responses returns an ordered output array containing generalized items. A response may include messages, reasoning items, built-in tool calls, custom function calls, and tool results. Do not assume output[0] is final text. OpenAI recommends using the SDK's output_text helper when it is available, while tool workflows should inspect item types and continue the explicit tool loop.

If the old application requires asynchronous execution, evaluate Responses background mode and webhooks rather than reproducing a one-second polling loop by habit. Preserve cancellation, timeout, duplicate-submission, and retry behavior as explicit product requirements. The tool-interface guide provides patterns for idempotent tool calls and reviewable results.

Replace Assistants thread and run event names in every streaming client. Responses has a different event model, and clients should tolerate new event types. Test first token, incremental text, tool calls, completion, cancellation, incomplete output, and error paths before switching traffic.

Run both paths against the same evaluations

Do not combine the API migration with a model change unless the deadline leaves no alternative. Keep the current model, instructions, tools, sampling settings, and test inputs stable for the first comparison. This makes a behavior difference easier to attribute to the new object and execution model.

Run representative conversations through both implementations and compare:

• user-visible answer quality and structured-output validity;
• tool selection, arguments, ordering, and repeated calls;
• file citations and attachment handling;
• latency, tokens, retries, and incomplete responses;
• conversation continuity after several turns;
• cancellation, timeout, and recovery behavior.

The coding-agent evaluation guide shows how to grade the full sequence instead of only the final text. ISH chat can help compare behavior across models, and ISH API can keep the application-facing model interface consistent while you change provider-specific orchestration.

Cut over with an exit check

Route a small percentage of new conversations to Responses, watch errors and behavioral regressions, then increase traffic. Before removing the old path, search production code and deployment artifacts again for Assistants endpoints and identifiers. Confirm that no worker, scheduled task, webhook handler, or admin tool still depends on them.

Keep a rollback switch that sends eligible new requests to the old implementation only while the Assistants API remains available. After August 26, that switch cannot be a recovery plan. Before release, verify that every supported user flow creates Responses, stores state in a Conversation or your own database, handles output items by type, and has no runtime dependency on Assistants or reusable prompt objects.

Sources

• OpenAI API deprecations
• OpenAI Assistants migration guide
• OpenAI API reference: Create a model response
• OpenAI API reference: Create a conversation
• OpenAI Assistants API reference