Responses API 的 Multi-agent beta 可让 GPT-6.2 Astra 将独立子任务并行委派给子代理,再由 /root 汇总;启用 multi_agent.enabled 并带上 beta 标记即可,默认最多同时运行 3 个子代理。
适合的任务:可拆成边界清晰、彼此独立的研究、分析、代码探索或实现任务。
不适合的任务:步骤强依赖前序结果、任务很小、多个代理会频繁写同一共享状态,或瓶颈主要是单个慢速外部操作。
适用的模型版本:GPT-6.2 Astra(Multi-agent beta 也列出 GPT-6.2 Sol、GPT-6.1 Sol 和所有 GPT-5.6 模型)。
适用的客户端、Agent 或 API:Responses API;不是 Codex 专属工作流。
推荐的推理档位和参数:本指南未给出 reasoning.effort 建议。max_concurrent_subagents 默认值为 3,文档建议多数工作负载使用默认值。
以下是按官方 HTTP 字段整理的最小请求示例。将任务描述替换为具体目标;API key 通过环境变量提供。该请求启用 beta 和子代理能力,但并不保证模型对任何任务都实际派生子代理,应在任务说明中明确要求并描述拆分方式。
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
}
}'SDK 使用 beta Responses API 时,Python/TypeScript 示例以 client.beta.responses.create(...) 发起请求,并在 betas 参数中传入 responses_multi_agent=v1。原始 HTTP 请求和 WebSocket 连接则使用 OpenAI-Beta: responses_multi_agent=v1 请求头。Beta 期间 item schema 可能变化。
检查可并行性:划分出互不依赖、输入输出明确的工作流;避免多个代理同时修改共享状态。
启用 beta:请求使用 GPT-6.2 Astra,设置 multi_agent.enabled: true,并带上 beta 标记。
界定任务并发:通常保留 max_concurrent_subagents: 3。它限制整个代理树中同时活跃的子代理数(包括后代,不包括 /root);并非总代理数限制。树深度和整次运行创建的子代理数没有固定上限。
由根代理协调:/root 可派生代理、发送补充信息、等待结果并综合答复。子代理拥有各自的有界上下文;根代理和子代理使用该请求的模型及可用工具。系统会自动向根代理及子代理追加一条 developer message,其中的协调指令不可编辑或移除;应用自己的 developer 指令应作为补充。
处理应用工具:托管协作操作由 Responses API 提供,应用不应执行或提交这些操作的输出。若任一代理调用请求中定义的 function,应用仍需执行该函数并提交匹配的 function_call_output。HTTP 下通常在当前响应结束后续发请求;长时间或工具密集型工作流可用 WebSocket,在结果就绪时注入输出。
控制成本和延迟:并行可减少等待时间,但增加子代理会增加 token 使用量。默认并发数 3 是文档建议值;按需要收紧并发并避免对串行任务启用多代理。文档没有承诺固定成本或延迟收益。
官方指南将 Multi-agent 标为 beta,并明确列出 GPT-6.2 Astra。
开关字段为 multi_agent.enabled;HTTP beta 标记为 OpenAI-Beta: responses_multi_agent=v1;示例并发字段为 max_concurrent_subagents。
子代理共享请求模型和可用工具,各自维护有界上下文;根代理负责综合最终答复。
托管协作操作包括 spawn_agent、send_message、followup_task、wait_agent、interrupt_agent 和 list_agents。应用定义的工具调用由应用执行。
max_concurrent_subagents 默认 3,推荐多数工作负载使用;它计数整棵树中活跃的子代理,不包括根代理。没有固定树深或子代理总数上限。
开启 Multi-agent 会自动启用根代理和各子代理各自的服务端自动压缩;可在请求中显式设置 context_management.compact_threshold。reasoning.summary 和 max_tool_calls 在该模式下不受支持。
指南指出并行子代理会增加 token 使用量。它未说明子代理会继承特定 reasoning.effort 值,也未给出成本公式;不要把并发上限当作 token 预算。
Responses API 的 Multi-agent 是 API 请求中的托管协调能力。它不会因此启动 Codex 客户端或 Codex 工作区;调用请求中定义的工具仍由集成 API 的应用处理。该指南没有将 Codex 描述为此功能的执行环境。
Beta 中的 item schema 可能变化,部署前应检查模型页和最新 API 文档。
多代理适用于可独立并行的工作;多代理增加 token 用量,且不适合强顺序依赖或共享可变状态频繁写入的任务。
本文的请求示例只启用协调能力并给出任务指令,不包含应用工具、完整 SDK 响应解析或生产级重试逻辑。
开启 Multi-agent 时,reasoning.summary 和 max_tool_calls 不受支持;指南没有给出推理档位继承或费用精确计算方法。
使用 OpenAI API key 对 /v1/responses 发起上述请求,查看响应中的代理标识与输出项,并以 /root 的最终答复作为汇总结果。此文记录官方能力说明,不代表已实际调用 API、运行 Codex 或验证某项任务的性能与成本。
GPT-6.2 Astra