Skip to main content
委派任务给 Agent

Multiagent 编排

配置 Coordinator，将任务委派给职责明确的 Agent，并通过 Session Thread 观察协作过程。

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

工作原理

Multiagent 编排建立在 Session Thread 模型之上。创建 Session 时指定的 Agent 成为 Coordinator；Coordinator 根据系统提示词，从 multiagent.agents 定义的 Agent 名单中选择子 Agent 并发起委派。
概念说明
Coordinator每个 Session 唯一的协调线程。负责拆分任务、选择子 Agent、跟进结果并汇总回答
Child Agentmultiagent.agents 中可被委派的 Agent。可以拥有独立的模型、系统提示词、工具、MCP Server 和 Skill
Session ThreadCoordinator 或 Child Agent 的执行线程，ID 前缀为 sthr_。每个线程拥有独立的对话历史、Agent 快照和状态
Agent 名单Coordinator 可委派的 Agent 集合。创建或更新 Coordinator 时解析并保存对应的 Agent 版本
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

通过控制台配置

  1. 在 Cloud Agents 控制台进入 Agents，先创建参与协作的各 Agent。
  2. 创建或编辑 Coordinator，在 Multiagent 区域选择可委派的 Agent。控制台会保存所选 Agent 的当前版本。
  3. 在 Coordinator 的系统提示词中定义任务拆分、委派条件、交付格式和冲突处理方式。
  4. 保存 Coordinator，并使用它创建 Session。
控制台选择器用于引用其他 Agent。如需把 Coordinator 自身加入 Agent 名单，请通过 API 或直接编辑 JSON 配置添加 {"type":"self"}。

通过 API 配置

创建 Agent 时设置 multiagent，并在 tools 中加入 agent_toolset_20260401： 
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"},
        {"type": "self"}
      ]
    }
  }'
multiagent.agents 支持以下格式：
格式示例说明
Agent 对象{"type":"agent","id":"agent_00nc01ht8gcn4w8sb7zv","version":2}引用其他 Agent。id 必填，version 可选
Self 对象{"type":"self"}使用 Coordinator 自身的 Agent 配置创建子线程
字符串简写"agent_00nc01ht8gcn4w8sb7zv"等价于 {"type":"agent","id":"agent_00nc01ht8gcn4w8sb7zv"}
Agent 条目的显示名称由平台解析；名称来源、name 字段处理、唯一性要求及其他校验规则请参阅 Agent 数据结构。

Agent 版本与 Session 快照

版本决定委派执行时使用哪一份 Agent 配置：
  • 指定 version 时，Coordinator 固定引用该版本。
  • 省略 version 时，平台会在创建或更新 Coordinator 时解析被引用 Agent 的最新 Active 版本，并将解析结果保存到 Coordinator 版本中。
  • 后续更新子 Agent 不会自动改变已经保存的 Coordinator。要使用新版本，请更新并重新保存 Coordinator。
  • 创建 Session 后，Coordinator 和 Agent 名单会冻结为 Session 快照。正在运行的 Session 不受之后 Agent 更新影响。
生产场景应先验证子 Agent 版本，再更新 Coordinator。

创建并运行 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_sentCoordinator 向子线程发送任务或后续消息
agent.thread_message_receivedCoordinator 收到子线程返回的消息
相关事件包含 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_id 则会请求中断整个 Session 当前正在处理的工作。中断操作不会归档 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 名单大小每个 Coordinator 可配置 1-20 个不重复的 Agent 条目
Session Thread 数量每个 Session 最多 25 个未归档 Thread（含 Coordinator）；达到上限后，先归档已完成的子 Thread
委派层级仅 Coordinator 可以创建子线程；Child Agent 不能继续创建下一层子线程
Session 空闲所有 Thread 都停止运行后，Session 才进入空闲状态
Agent 引用不存在、已归档或当前用户无权访问的 Agent/版本会导致配置失败
工具集配置 multiagent 时必须包含 agent_toolset_20260401

常见问题

Coordinator 未委派任务

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

更新 Agent 后 Session 未使用新配置

Session 创建时会固定 Coordinator 和子 Agent 的版本快照。更新子 Agent 后，还需要更新并保存 Coordinator，再创建新的 Session；已有 Session 不会使用新配置。

创建或更新 Coordinator 返回 400

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

相关文档

快速入门
构建 Agent
配置 Agent 环境
委派任务给 Agent
集成 Agent
管理 Agent 上下文
账户
最佳实践
公告
API 参考