Chat Completions → Responses

Chat Completions organizes conversations with messages and choices. Responses uses input, Typed Items, and output for inputs, tool calls, and results. Migration requires changes to the endpoint, input structure, response parsing, tool loop, and streaming state machine.

Whether migration is needed

Situations suitable for migration to Responses:

• The new project aims to use unified Typed Input and Output Items;
• Requires multi-turn state capability such as previous_response_id;
• Requires built-in tools supported by Responses;
• Applications are willing to handle text, utility calls, and other outputs according to Item types.

Situations where you can continue using Chat Completions:

• Existing applications relied on messages, choices, and Chat Delta;
• The target model or required tool only supports Chat Completions;
• Currently, there is not enough regression testing coverage tools, multi-turn, and streaming;
• The migration benefits are insufficient to cover the retrofit costs of response resolution and state management.

Core changes

Minimum Request Before / After

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "Answers should be concise and accurate."
    },
    {
      "role": "user",
      "content": "Please introduce AGTCloud in one sentence."
    }
  ]
}

When using the OpenAI SDK, keep the client Base URL as https://api.agtcloud.cn/v1 and change the method from client.chat.completions.create(...) to client.responses.create(...). For complete Python and TypeScript initialization instructions, see OpenAI SDK.

Migration response read

Chat Completions usually reads the assistant message from the first Choice:

choices[0].message.content

Responses returns an ordered output[] array that can contain messages, function calls, search calls, and other items. The SDK's output_text helper reads aggregated text; when processing tools or other output types, traverse the complete output array.

response.output_text
response.output[]

Migrate to multi-turn states

When using previous_response_id, the previous request's instructions are not inherited automatically. Set instructions for each turn according to the application's needs.

After migration, do not simultaneously replay the entire history and re-reference it via previous_response_id, as this may lead to repeated context.

Migrate Function Calling

Tool definition

Chat Completions puts function definitions in tools[].function:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Check the city weather",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}

Responses places the function information directly in the Function Tool object:

{
  "type": "function",
  "name": "get_weather",
  "description": "Check the city weather",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" }
    },
    "required": ["city"]
  }
}

Results are sent back

• Chat: Read calls from assistant.tool_calls[], then add a tool message with the matching tool_call_id.
• Responses: Read function_call items from output[], then send function_call_output with the matching call_id.

No matter which protocol you use, the function is executed by your application. Do not directly execute unverified parameters, and do not disguise tool exceptions as normal results.

Migrate Streaming

Chat Completions returns incremental content in choices[].delta and commonly uses [DONE] to terminate the stream.

Responses use named events, such as:

• response.created;
• response.output_item.added;
• response.content_part.added;
• response.output_text.delta;
• response.output_text.done;
• response.completed.

During migration, the original "text concatenation only" logic should be changed to an event dispatcher: first handle by event type, then update the corresponding status based on identifiers such as output_index, content_index, item_id.

Migrate Structured Outputs

Chat Completions uses response_format for output formatting, while Responses uses text.format. Update this configuration during migration:

1. Request field location;
2. JSON Schema wrapper structure;
3. SDK parsing assistance methods;
4. Handling of rejections, incomplete responses, and schema validation failures.

For detailed fields, please refer to Chat Completions and OpenAI Responses.

Migrating Web Search

The search entry points for the two protocols are different:

• Chat Completions uses web_search_options and requires a model that supports web search;
• Responses enables supported web search tools in tools and may return search-call items and citations.

Settings such as domain filtering, source listings, user location, and real-time internet access depend on the chosen protocol and model. For a full example, please refer to OpenAI Web Search.

Usage, errors, and interrupts

When migrating monitoring and billing read logic, at least adjust the following:

Record the HTTP status code, error object, and Request ID together. Do not capture only the SDK exception text. Application logs should distinguish authentication failures, unavailable models, rate limits, service errors, and connection interruptions.

Phased migration

Regression and Rollback Checklist

• Plain text, empty output, rejection, incomplete, and failed states;
• Single tool, multi-tool, tool failure, and parameter validation failure;
• Stateless history playback and previous_response_id;
• Streaming: Normal completion, disconnection, and repeated events;
• Structured Outputs validation failed;
• Usage, error messages, Request ID, timeout, and rate limiting;
• If the target model does not support a certain Responses capability, it can switch back to Chat Completions.

Before production switchover, keep separate configurations and controllable switches for Chat and Responses. After confirming that business metrics, logs, and error handling are stable, clean up old resolution paths.

Next

• Use OpenAI SDK to configure Python or TypeScript clients;
• View Text and Conversations to understand the daily invocation flow of Responses;
• Check the full fields and responses in OpenAI Responses;
• When encountering invocation errors, check Errors and Troubleshooting.