托管 Agent

Managed Agents 允许一个 Agent 以协调者（coordinator）身份向其他 Agent 委派任务，实现多 Agent 协作。每个子 Agent 在独立的 Session Thread 中运行，具有独立的对话历史和执行上下文。

核心概念

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

概念	说明
Coordinator	协调者线程，每个 Session 有且仅有一个。使用 Session 创建时指定的 Agent，负责编排和分派任务
Child thread	子线程，绑定 `multiagent.agents` 花名册中的某个 Agent，独立执行任务并向 coordinator 回报结果
Session Thread	线程实体，ID 前缀为 `sthr_`。包含 `role`（coordinator 或 child）、独立的 Agent 快照和状态

配置 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 类型的工具配置项。

线程事件

在 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 对象字段与生命周期。

​核心概念

​配置 Managed Agent

​multiagent 字段说明

​线程事件

​限制

​下一步

配置 multiagent

Agent 数据结构

列出 Session Threads

Session Thread 对象

核心概念

配置 Managed Agent

`multiagent` 字段说明

线程事件

限制

下一步