Multiagent 编排

Multiagent 编排允许一个 Agent 作为 Coordinator，将任务委派给其他 Agent。每个子 Agent 在独立的 Session Thread 中运行，Coordinator 汇总各线程的结果并向用户返回最终答案。也可以配置 Advisor，在关键步骤为主 Agent 提供独立建议。适用于可以按职责拆分、并行或分阶段执行的复杂任务。对于一步即可完成、必须严格串行，或多个执行者会频繁修改同一文件的任务，建议使用单 Agent，流程会更简单。

工作原理

Multiagent 编排建立在 Session Thread 模型之上。创建 Session 时指定的 Agent 成为 Coordinator；Coordinator 根据系统提示词，从 multiagent.agents 定义的 Agent 列表中选择子 Agent 并发起委派。

概念	说明
Coordinator	每个 Session 唯一的协调线程。负责拆分任务、选择子 Agent、跟进结果并汇总回答
Child Agent	`multiagent.agents` 中可被委派的 Agent。可以拥有独立的模型、系统提示词、工具、MCP Server 和 Skill
Advisor	主线程可在执行中咨询的顾问模型，只返回建议，不执行工具或接管任务。每次咨询使用独立的临时 Thread
Session Thread	Coordinator 或 Child Agent 的执行线程，ID 前缀为 `sthr_`。每个线程拥有独立的对话历史、Agent 快照和状态
Agent 列表	在 `multiagent.agents` 中配置，指定 Coordinator 可以调用哪些子 Agent，也可包含 Advisor

Multiagent Session 中各类资源、上下文与配置的作用范围如下：

范围	行为
环境与文件系统	Session 内所有线程共享同一个 Environment、Sandbox 和文件系统
Vault	创建 Session 时绑定，供该 Session 中有权限的 Agent 使用
对话历史	每个 Thread 独立，子 Agent 不会自动获得其他线程的完整上下文
Agent 配置	每个 Thread 使用自己的 Agent 版本快照，包括模型、系统提示词、工具、MCP Server 和 Skill
事件流	Session 事件流展示主线程和跨线程协作事件，不是所有子线程事件的并集；Thread 接口用于读取单个线程的事件

并行子 Agent 共享同一文件系统。应在 Coordinator 的系统提示词中划分清晰的文件或目录边界，避免多个子 Agent 同时修改同一文件。

适合委派的任务

根据任务依赖和职责边界设计 Agent 列表及 Coordinator 的系统提示词：

彼此独立的调研、模块实现或数据收集任务，可以交给不同 Agent 并行执行。
按职责拆分实现、测试和评审。例如，实现 Agent 可以编写代码，评审 Agent 只读代码并返回问题清单；需要更强模型或专用工具的工作交给对应 Agent。
有前后依赖的任务按阶段执行，例如先实现、再评审；Coordinator 根据评审结果决定是否继续迭代。

系统提示词还应约定各 Agent 的输出格式，以及哪些任务必须由 Coordinator 自己处理。

配置 Coordinator

通过控制台配置

在 Cloud Agents 控制台进入 Agents，先创建参与协作的各 Agent。
创建或编辑 Coordinator，在 Multiagent 区域选择可委派的 Agent。控制台会保存所选 Agent 的当前版本。
在 Coordinator 的系统提示词中定义任务拆分、委派条件、交付格式和冲突处理方式。
保存 Coordinator，并使用它创建 Session。

控制台选择器用于引用其他 Agent。如需把 Coordinator 自身加入 Agent 列表，请通过 API 或直接编辑 JSON 配置添加 {"type":"self"}。

通过 API 配置

委派普通子 Agent 时，设置 multiagent，并在 tools 中加入 agent_toolset_20260401。仅配置 Advisor 时不要求该工具集：

curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "engineering-coordinator",
    "model": "ultimate",
    "system": "分析任务并委派给最合适的 Agent。可并行的工作应并行执行；汇总前检查各 Agent 的结论和冲突。",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]
      }
    ],
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "agent", "id": "agent_00nc01ht8gcn4w8sb7zv", "version": 3},
        {"type": "agent", "id": "agent_00nc01ht8gcn4w8sb7zw", "version": "latest"},
        {"type": "self"}
      ]
    }
  }'

multiagent.agents 支持以下格式：

格式	示例	说明
Agent 对象	`{"type":"agent","id":"agent_00nc01ht8gcn4w8sb7zv","version":2}`	引用其他 Agent。`id` 必填，`version` 可选
Self 对象	`{"type":"self"}`	使用 Coordinator 自身的 Agent 配置创建子线程
Advisor 对象	`{"type":"advisor","model":"ultimate"}`	给主线程配置一个顾问模型；每份列表最多一个，详见配置 Advisor
字符串简写	`"agent_00nc01ht8gcn4w8sb7zv"`	等价于 `{"type":"agent","id":"agent_00nc01ht8gcn4w8sb7zv"}`

Agent 条目的显示名称由平台解析；名称来源、name 字段处理、唯一性要求及其他校验规则请参阅 Agent 数据结构。

Agent 版本与 Session 快照

上面的示例展示了三种用法：

"latest"：新会话自动采用子 Agent 的最新版本。
整数：固定使用已验证的版本，便于回滚和复现。
self：用当前 Session 的 Coordinator 配置创建子线程。

例如，主 Agent 在 multiagent.agents 中以 "version": "latest" 引用一个子 Agent。子 Agent 从 v2 更新到 v3 后，用该主 Agent 新建的会话会使用子 Agent v3；更新前已创建的会话及其后续子线程仍使用子 Agent v2。 API 省略 version 时，会在保存 Coordinator 时固定子 Agent 当时的最新版本；之后即使子 Agent 更新，新建会话仍使用已固定的版本。完整规则见子 Agent 版本规则。

配置 Advisor

Advisor 为主 Agent 提供建议，适合方案评审、复杂问题分析等场景。主 Agent 决定何时咨询及是否采纳建议；你可以在系统提示词中写明咨询条件。在控制台创建或编辑 Agent 时，进入 多智能体 区域，选择 添加 Advisor 并选择模型，也可以通过 API 配置：

curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend-engineer",
    "model": "auto",
    "system": "分析后端方案。涉及数据迁移或不可逆变更时，先咨询 Advisor，再结合建议回答。",
    "multiagent": {
      "type": "coordinator",
      "agents": [{"type": "advisor", "model": "ultimate"}]
    }
  }'

每个 Agent 最多配置一个 Advisor，可与普通子 Agent 一起使用，无需加入 enabled_tools；模型可从模型列表中选择，配置字段见 Agent 数据结构。

咨询过程

Advisor 根据主 Agent 的当前对话上下文提供建议，不执行工具；主 Agent 收到结果后继续处理任务。同一个 Advisor 可以多次咨询，控制台会分别展示每次咨询的记录。

事件与异常处理

咨询失败时，主 Agent 会继续处理任务；错误详情可在 Advisor 的事件记录中查看。通过 API 获取结果和状态，参见 Advisor 事件。

中断和移除

可中断单次咨询，或通过更新 Agent 移除 Advisor；配置变更仅对新建 Session 生效。

成本与上下文

Advisor 使用当前对话上下文，每次咨询会增加模型费用和等待时间。

创建并运行 Session

使用配置了 multiagent 的 Coordinator 创建 Session：

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "id": "agent_00nc01ht8gcn4w8sb7zx",
      "version": 4
    },
    "environment_id": "env_00l99wwqo8ydc81s4djg",
    "vault_ids": ["vault_00j9owzm7vfnkgckud6o"],
    "title": "分析并评审登录模块"
  }'

向 Session 发送任务消息。Coordinator 会根据系统提示词判断是否委派以及如何拆分：

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [
          {"type": "text", "text": "分析登录模块的实现和安全风险，并给出修复建议。"}
        ]
      }
    ]
  }'

即使配置了 Agent 列表，是否真正委派仍由 Coordinator 的判断和系统提示词决定。请在提示词中明确委派条件，而不是只列出子 Agent。参阅创建 Session 和发送 Session 事件。

连接 MCP Server 和 Vault

MCP Server、工具和 Skill 属于 Agent 配置；Vault 在创建 Session 时绑定：

只有配置了对应 MCP Server 或工具集的 Agent 才能调用相关能力。
Session 中所有线程共享该 Session 绑定的 Vault，但每个 Agent 仍受自身工具配置和权限策略约束。
Vault 中的凭据 URL 必须与 Agent 配置的 MCP Server URL 匹配。
Coordinator 通常只需要编排和汇总能力；只把高权限凭据授给真正需要它的 Agent。

参阅工具、Vault 和权限策略。

观察线程和事件

Session 事件流可以观察整体协作过程：

curl -N "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"

Multiagent 场景会出现以下线程事件：

事件类型	说明
`session.thread_created`	创建了新的子线程
`session.thread_status_running`	线程开始执行
`session.thread_status_rescheduled`	线程任务重试并重新调度
`session.thread_status_idle`	线程完成当前工作或等待后续消息
`session.thread_status_terminated`	线程已归档或终止
`agent.thread_message_sent`	Coordinator 向子线程发送任务或后续消息
`agent.thread_message_received`	Coordinator 收到子线程返回的消息

相关事件包含 session_thread_id，可用于定位所属线程。列出 Session 中的线程：

curl "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/threads" \
  -H "Authorization: Bearer $QODER_PAT"

需要检查某个子 Agent 的完整过程时，连接该 Thread 的事件流：

curl -N "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/threads/sthr_xxx/stream" \
  -H "Authorization: Bearer $QODER_PAT"

Session 事件流适合观察跨线程进度和 Coordinator 汇总结果；Thread 事件流适合调试单个子 Agent。参阅列出 Session Threads、列出 Thread 事件和 Thread 事件流。

中断单个线程

向 Session 发送 user.interrupt 事件并指定 session_thread_id，只会中断目标 Thread；省略时则请求中断整个 Session 当前正在处理的工作。普通子 Thread 中断后不会归档；Advisor Thread 在咨询完成、失败或被中断后自动归档，但历史记录仍可查看。

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.interrupt",
        "session_thread_id": "sthr_xxx"
      }
    ]
  }'

工具权限和交互

每个 Thread 使用自身 Agent 快照中的工具配置和权限策略。需要确认的工具调用会发送 agent.tool_use，客户端使用 user.tool_confirmation 回复，并提供 tool_use_id 和 result。Custom Tool 调用会发送 agent.custom_tool_use，客户端执行后使用 user.custom_tool_result 回复，并提供 custom_tool_use_id。存在待处理操作时，事件流会发送 session.status_idle，其中 stop_reason.type 为 requires_action，stop_reason.event_ids 列出需要回复的事件 ID。相关 Agent 事件中的 session_thread_id 可用于识别发起请求的 Thread。以下示例允许一个需要确认的工具调用：

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
        "result": "allow"
      }
    ]
  }'

回复工具操作时不要传 session_thread_id；平台会根据 tool_use_id 或 custom_tool_use_id 将结果路由回原始 Thread。stop_reason.event_ids 包含多个 ID 时，需要逐一回复；仍有操作未处理时，当前 turn 会继续暂停。此时的 requires_action 表示等待输入，并不表示 Session 已完成。归档子线程前，应先确认没有等待中的工具交互。参阅发送 Session 事件。

限制

项目	行为或限制
Agent 列表大小	最多 20 个不重复的普通 Agent 条目，另可配置 1 个 Advisor；列表不能整体为空
Session Thread 数量	每个 Session 最多 25 个未归档普通 Thread（含 Coordinator）；Advisor Thread 不计入此上限
委派层级	仅 Coordinator 可以创建子线程；Child Agent 不能继续创建下一层子线程
Session 空闲	所有 Thread 都停止运行后，Session 才进入空闲状态
Agent 引用	不存在、已归档或当前用户无权访问的 Agent/版本会导致配置失败
工具集	列表含普通 Agent 或 `self` 时必须包含 `agent_toolset_20260401`；仅配置 Advisor 时不要求

常见问题

Coordinator 未委派任务

确认 Coordinator 当前版本包含非空的 multiagent.agents；配置规则参阅 Agent 数据结构。
确认系统提示词明确说明委派条件和各 Agent 的职责。

更新子 Agent 后，新建 Session 为什么仍使用旧版本？

如果 multiagent.agents 中的子 Agent 指定了数字 version，或省略了 version（默认行为），Coordinator 保存的就是固定版本。子 Agent 更新不会改变这个引用，因此新建 Session 仍使用旧版本。将 multiagent.agents 中子 Agent 的 version 改为 "latest"，保存后新建会话即可。

创建或更新 Coordinator 返回 400

常见原因包括 Agent 或版本引用无效，或者 multiagent 配置未通过校验。根据 API 返回的错误消息定位对应字段；完整规则参阅 Agent 数据结构。

​工作原理

​适合委派的任务

​配置 Coordinator

​通过控制台配置

​通过 API 配置

​Agent 版本与 Session 快照

​配置 Advisor

​咨询过程

​事件与异常处理

​中断和移除

​成本与上下文

​创建并运行 Session

​连接 MCP Server 和 Vault

​观察线程和事件

​中断单个线程

​工具权限和交互

​限制

​常见问题

​Coordinator 未委派任务

​更新子 Agent 后，新建 Session 为什么仍使用旧版本？

​创建或更新 Coordinator 返回 400

​相关文档

工作原理

适合委派的任务

配置 Coordinator

通过控制台配置

通过 API 配置

Agent 版本与 Session 快照

配置 Advisor

咨询过程

事件与异常处理

中断和移除

成本与上下文

创建并运行 Session

连接 MCP Server 和 Vault

观察线程和事件

中断单个线程

工具权限和交互

限制

常见问题

Coordinator 未委派任务

更新子 Agent 后，新建 Session 为什么仍使用旧版本？

创建或更新 Coordinator 返回 400

相关文档