The Responses API Multi-agent beta lets GPT-6.2 Astra delegate independent subtasks to subagents in parallel and then have /root synthesize their results. Enable multi_agent.enabled and include the beta header; by default, up to 3 subagents can run concurrently.
Suitable tasks: Research, analysis, code exploration, or implementation tasks that can be divided into clearly bounded, independent parts.
Unsuitable tasks: Tasks with steps that depend heavily on prior results, very small tasks, tasks where multiple agents frequently write to the same shared state, or tasks whose main bottleneck is a single slow external operation.
Supported model versions: GPT-6.2 Astra (the Multi-agent beta also lists GPT-6.2 Sol, GPT-6.1 Sol, and all GPT-5.6 models).
Supported client, agent, or API: Responses API; this is not a Codex-specific workflow.
Recommended reasoning level and parameters: This guide does not recommend a reasoning.effort value. The default for max_concurrent_subagents is 3, which the documentation recommends for most workloads.
The following is a minimal request example using the official HTTP fields. Replace the task description with a specific goal; provide the API key through an environment variable. The request enables the beta and subagent capabilities, but does not guarantee that the model will actually spawn subagents for every task. State the request explicitly in the task instructions and describe how to split the work.
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: responses_multi_agent=v1" \
-d '{
"model": "gpt-6.2-astra",
"input": "把这项工作拆成若干相互独立的部分并行研究。每个子代理只处理一个部分,报告证据和结论;你负责比较结果、消解冲突并给出最终答复。任务:<在此填写>",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 3
}
}'The prompt in the request is preserved in its original Chinese. In English, it asks the model to split the work into independent parts for parallel research, have each subagent handle one part and report evidence and conclusions, and have the coordinator compare results, resolve conflicts, and provide the final answer. Fill in the task placeholder with the actual task.
For the SDK beta Responses API, the Python and TypeScript examples make requests with client.beta.responses.create(...) and pass responses_multi_agent=v1 in the betas parameter. Raw HTTP requests and WebSocket connections use the OpenAI-Beta: responses_multi_agent=v1 header. The item schema may change during the beta.
Check for parallelizable work: Divide the workflow into parts with clear inputs and outputs that do not depend on one another; avoid having multiple agents modify shared state at the same time.
Enable the beta: Use GPT-6.2 Astra, set multi_agent.enabled: true, and include the beta marker.
Set concurrency: Usually keep max_concurrent_subagents: 3. It limits the number of subagents active at once across the entire agent tree, including descendants but excluding /root; it is not a limit on the total number of agents. There is no fixed limit on tree depth or the total number of subagents created during a run.
Coordinate through the root agent: /root can spawn agents, send follow-up information, wait for results, and synthesize a response. Each subagent has its own bounded context; the root agent and subagents use the model and available tools from the request. The system automatically appends a developer message with coordination instructions to the root agent and each subagent. Those instructions cannot be edited or removed; add your own application developer instructions alongside them.
Handle application tools: The Responses API provides the hosted collaboration operations; the application should not execute them or submit their outputs. If any agent calls a function defined in the request, the application must still execute that function and submit the matching function_call_output. With HTTP, this usually means sending a follow-up request after the current response ends. For long-running or tool-intensive workflows, use WebSocket and inject outputs when they are ready.
Manage cost and latency: Parallelism can reduce waiting time, but adding subagents increases token usage. The documentation recommends the default concurrency of 3 for most workloads; tighten the limit as needed and avoid enabling multi-agent for serial tasks. The documentation does not promise fixed cost or latency benefits.
The official guide labels Multi-agent as beta and explicitly lists GPT-6.2 Astra.
The switch is multi_agent.enabled; the HTTP beta marker is OpenAI-Beta: responses_multi_agent=v1; and the example concurrency field is max_concurrent_subagents.
Subagents share the request's model and available tools, while maintaining separate bounded contexts; the root agent synthesizes the final response.
Hosted collaboration operations include spawn_agent, send_message, followup_task, wait_agent, interrupt_agent, and list_agents. The application executes tool calls defined by the application.
max_concurrent_subagents defaults to 3, which is recommended for most workloads. It counts active subagents across the entire tree and excludes the root agent. There is no fixed maximum tree depth or total number of subagents.
Enabling Multi-agent automatically enables separate server-side compaction for the root agent and each subagent; context_management.compact_threshold can be set explicitly in the request. reasoning.summary and max_tool_calls are not supported in this mode.
The guide says parallel subagents increase token usage. It does not say that subagents inherit a specific reasoning.effort value, nor does it provide a cost formula; do not treat the concurrency limit as a token budget.
Multi-agent in the Responses API is a hosted coordination capability in an API request. It does not launch a Codex client or Codex workspace. Tools defined in the request are still handled by the application integrated with the API. The guide does not describe Codex as the execution environment for this feature.
The item schema may change during the beta; check the model page and the latest API documentation before deployment.
Multi-agent is suited to work that can be parallelized independently. It increases token usage and is unsuitable for tasks with strong sequential dependencies or frequent writes to shared mutable state.
The request example in this article only enables coordination and provides task instructions. It does not include application tools, complete SDK response parsing, or production-grade retry logic.
When Multi-agent is enabled, reasoning.summary and max_tool_calls are unsupported; the guide does not specify inheritance of reasoning levels or a precise cost calculation method.
Use an OpenAI API key to send the request above to /v1/responses, inspect the agent identifiers and output items in the response, and use /root's final answer as the synthesized result. This article records the official capability description; it does not claim that the API was actually called, Codex was run, or the performance and cost of any task were verified.
GPT-6.2 Astra