Managed Agents

通过 coordinator Agent 将子任务并行或串行委派给 child Agent。

Managed Agents 允许一个 Agent 以协调者（coordinator）身份管理和委派任务给其他 Agent，实现多 Agent 协作。协调者 Agent 可以创建子 Agent 线程、发送消息、等待结果，从而将复杂任务分解为多个独立的子任务并行或串行执行。

​

核心概念

Managed Agents 建立在 Session Thread 模型之上。一个 Session 内可以同时存在多个 Thread，每个 Thread 绑定一个独立的 Agent 快照，拥有独立的对话历史和执行上下文。

概念	说明
Coordinator	协调者线程，每个 Session 有且仅有一个。使用 Session 创建时指定的 Agent，负责编排和分派任务
Child thread	子线程，由 coordinator 通过工具调用创建。绑定 multiagent.agents 花名册中的某个 Agent，独立执行任务并通过 send_to_parent 回报结果
Session Thread	线程实体，ID 前缀为 sthr_。包含 role（coordinator 或 child）、独立的 Agent 快照和状态
Mailbox	线程间消息队列，CAS 内部管理。消息入队后由调度器按目标线程状态自动分发

​

配置 Managed Agent

要启用 managed agents 能力，需要在 Agent 配置中设置 multiagent 字段：

curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "task-coordinator",
    "model": "ultimate",
    "system": "你是一个任务协调者，负责将任务分配给合适的子 Agent。",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "agent", "id": "agent_019f000000000000000000000000001a", "name": "Research Agent"},
        {"type": "agent", "id": "agent_019f000000000000000000000000002b"},
        {"type": "self"}
      ]
    }
  }'

​

multiagent 字段说明

字段	类型	必选	说明
type	string	是	必须为 "coordinator"
agents	array	是	可委派的 Agent 花名册，1-20 个唯一条目

agents 数组元素支持三种格式：

格式	示例	说明
对象 type: "agent"	{"type": "agent", "id": "agent_xxx", "version": 2, "name": "Reviewer"}	引用其他 Agent。id 必填，version 和 name 可选
对象 type: "self"	{"type": "self"}	引用 coordinator 自身作为子 Agent
字符串简写	"agent_xxx"	等价于 {"type": "agent", "id": "agent_xxx"}

配置 multiagent 时，tools 中必须包含 agent_toolset_20260401 类型的工具配置项。系统会在运行时自动注入 create_agent、send_to_agent、list_agents、Agent 四个控制工具。

​

Coordinator 控制工具

当 Session 的 Agent 配置了 multiagent 且当前线程角色为 coordinator 时，以下工具被自动注入：

​

create_agent

创建一个新的子 Agent 线程并发送初始任务。调用后立即返回线程 ID，不等待子 Agent 完成。

参数	类型	必选	说明
agent_id	string	是	花名册中的 Agent ID 或 "self"。取值范围由 multiagent.agents 决定
agent_name	string	否	为子线程指定的显示名称
task	string	是	发送给子 Agent 的初始任务描述

返回示例："Created agent thread: sthr_019f..."

​

Agent

委派一个聚焦任务给子 Agent 并同步等待其返回结果。这是一个阻塞式工具——coordinator 的 turn 会暂停直到子 Agent 完成（调用 send_to_parent）或被中断。

参数	类型	必选	说明
agent_id	string	是	花名册中的 Agent ID 或 "self"
prompt	string	是	委派给子 Agent 的任务提示

​

send_to_agent

向已存在的子线程发送后续消息。

参数	类型	必选	说明
thread_id	string	是	目标子线程 ID（sthr_ 前缀）
message	string	是	发送的消息内容

返回示例："Message queued for agent thread: sthr_019f..."

​

list_agents

列出当前 Session 中所有子线程的状态、待处理消息数以及可用的 Agent 花名册。无需参数。

​

Child 控制工具

当线程角色为 child 时，系统自动注入一个工具：

​

send_to_parent

向 coordinator 发送结果、状态更新或提问。调用后子线程会变为 idle 状态。

参数	类型	必选	说明
message	string	是	发送给 coordinator 的消息

​

Session Thread 生命周期

1. 创建 Session

   客户端创建 Session 并引用配置了 multiagent 的 Agent。

2. 启动 Turn

   客户端发送 user.message 事件，CAS 自动创建 coordinator 线程（role: coordinator）。

3. Coordinator 委派任务

   模型调用 create_agent 或 Agent 工具，CAS 创建 child 线程，将任务消息入队到 mailbox。

4. Child 执行

   CAS 调度器将 mailbox 消息分发给 child 线程，CAW 加载 child 的 Agent 快照独立执行。

5. Child 回报结果

   Child 调用 send_to_parent，消息通过 mailbox 发回 coordinator。Child 线程变为 idle。

6. Coordinator 继续

   Coordinator 收到 child 的回报，综合结果继续处理或发起新的委派。

7. Session 空闲

   当所有运行中的线程都已停止，Session 整体回到 idle 状态。

​

线程事件

在 managed agents 场景下，事件流中会出现以下新事件类型：

事件类型	说明
session.thread_created	创建了新的子线程
session.thread_status_running	线程开始执行
session.thread_status_idle	线程执行完成或暂停
session.thread_status_terminated	线程被归档/终止
agent.thread_message_sent	线程间发送消息（coordinator → child 或后续消息）
agent.thread_message_received	线程间接收消息（child → coordinator）

所有事件都包含 session_thread_id 字段标识所属线程。可以通过 列出线程事件 和 线程事件流 接口按线程维度筛选事件。

​

限制

项目	限制
每个 Agent 最多配置的子 Agent 数量	20 个唯一条目
每个 Session 最多并发线程数	25 个（含 coordinator）
Session 空闲条件	所有线程必须停止运行

​

下一步

配置 multiagent

在创建 Agent 时设置 multiagent 字段。

Agent 数据结构

multiagent 与 agent entry 字段参考。

列出 Session Threads

查看 Session 中的所有线程。

Session Thread 对象

Session Thread 对象字段与生命周期。