OpenAI Agents API Multi-agent 怎么用？

官方资料（2026-11-02 核对）：Agents API Multi-agent · Sessions · Events 与 Items · Observability 与 Usage

什么任务适合拆给 Subagent

每个委派任务都写清问题、允许使用的数据、预期输出、停止条件和禁止事项。主 Agent 的职责不是“多开几个模型”，而是拆分、协调、检查证据并合并最终结果。

最小 JavaScript 示例

import OpenAI from "openai";

const client = new OpenAI();
const events = await client.beta.agents.sessions.create({
  agent: {
    model: process.env.OPENAI_MODEL,
    instructions: [
      "只把相互独立的问题交给 Subagent。",
      "每个任务写清来源与预期结果。",
      "等待结果，核对冲突，再输出合并结论。"
    ].join(" "),
    multi_agent: {
      enabled: true,
      max_concurrent_subagents: 2
    }
  },
  environment: { type: "none" },
  input: "让两个 Subagent 分别审查文档 A 与文档 B，并合并差异。",
  stream: true
});

events.withResultCollection();
for await (const event of events) {
  console.log(event.type);
}
console.log((await events.finalResult()).output_text);

示例用环境变量选择模型，避免把型号写成永久默认。environment.type: "none" 时应在创建请求中提供初始 input；stream: true 同时流式返回第一轮。SDK 会处理 Agents Beta 头，原始 HTTP 请求仍需按最新官方文档发送相应 Header。

并发限制不是越大越好

max_concurrent_subagents 限制同时运行的 Subagent 数量，不包含协调者；官方当前默认值是 6。生产环境建议从 2–3 个开始，记录总耗时、每个 Subagent 的 Token、工具调用、共享环境资源和外部 API 限流，再决定是否提高。

省略 multi_agent，或设置 enabled: false 并省略 limit，可关闭委派。该配置在 Session 创建时生效；修改已保存 Agent 的配置只会影响新 Session。

共享环境与文件冲突

需要命令或文件时可使用 openai_hosted 或 self_hosted 环境。协调者和全部 Subagent 共用该 Session 的文件系统，创建 Subagent 不会新增 Sandbox。

1. 给每个 Subagent 独立目录、文件集合或只读任务。
2. 不要让多个代理同时修改同一文件；必要时使用锁、工作树或由主 Agent 统一应用补丁。
3. 限制网络、密钥、MCP allowed tools 和命令权限，因为这些能力可能被 Subagent 继承。
4. 写操作用幂等键、审批和回滚；不要把自然语言协调当成事务保证。

Subagent 能继承什么工具

如果任务依赖 function tool，不要假设 Subagent 能直接调用；可留给主 Agent、改用受支持的 MCP/环境能力，或重新设计委派边界。

事件流怎么看

• agent.session.subagent.created：提供新 Subagent ID。
• agent.session.turn.item.added / done：报告协调动作。
• Item 类型包括 create_subagent_call、send_subagent_input_call、wait_for_subagents_call、interrupt_subagent_call。
• create 或 wait item completed 只代表协调动作完成，不代表 Subagent 已完成任务。
• agent_message 在可用时包含代理间文字，但事件流不是完整聊天记录。

最终结果以主 Agent 合并响应为入口，并结合保存的 Items、Turns 和每个 Subagent 历史检查遗漏、冲突或失败。

怎样给命令和成本归因

拿命令 Item 的 turn_id 与 Session ID 查询 Turn；turn.subagent_id 为 null 表示主 Agent，否则就是执行命令的 Subagent。生产日志至少保存 Session、Turn、Subagent、工具/命令、耗时、Token、错误与审批结果，避免只保留最终回答。

安全、可靠性与评测清单

1. 任务隔离：分别说明数据范围、输出格式和停止条件。
2. 最小权限：限制 MCP、网络、密钥、目录和命令。
3. 写入协调：单写者、目录分区或主 Agent 合并补丁。
4. 完成判定：区分协调 item completed、Subagent 结果、主 Agent 合并和业务成功。
5. 失败恢复：对子任务设置超时、重试上限、interrupt 与部分结果策略。
6. 成本：同时记录主 Agent 和全部 Subagent 的 Token、工具及环境资源。
7. 评测：比较单 Agent 与 2/3/6 并发在正确率、耗时、冲突和单位成功成本上的差异。

常见问题

本文核对日期为 2026-11-02。Agents API Multi-agent 当前是 Beta；配置、默认并发、Subagent 工具、事件与计费可能变化，部署前请重新读取 Multi-agent、Sessions、Events 和 Observability 官方文档。