子代理

将任务委托给子代理，由多个专项代理分工。子代理是由现有代理运行派生的后台代理运行，在独立会话中运行（agent:<agentId>:subagent:<uuid>），完成后将结果通知回请求方聊天频道。

斜杠命令

使用 /subagents 查看或控制当前会话的子代理运行：

/subagents list
/subagents stop <id|#|all>
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
/subagents send <id|#> <message>

/subagents info 显示运行元数据（状态、时间戳、会话 id、转录路径、清理）。主要目标：

在不阻塞主运行的前提下并行处理“调研/长任务/慢工具”类工作。
默认隔离子代理（会话分离 + 可选沙箱）。
工具表面不易误用：子代理默认不获得会话工具。
避免嵌套扇出：子代理不能再派生子代理。

成本说明：每个子代理有独立上下文与 token 消耗。对繁重或重复任务，可为子代理配置更便宜的模型，主代理使用更高质量模型。可通过 agents.defaults.subagents.model 或每代理覆盖配置。

工具

使用 sessions_spawn：

启动子代理运行（deliver: false，全局通道：subagent）
然后执行通知步骤，将通知回复发往请求方聊天频道
默认模型：继承调用方，除非设置 agents.defaults.subagents.model（或每代理 agents.list[].subagents.model）；显式传 sessions_spawn.model 优先。

工具参数：task（必填）、label?（可选）、agentId?（可选）、model?（可选）、thinking?（可选）、runTimeoutSeconds?（默认 0）、cleanup?（delete|keep，默认 keep）。白名单：agents.list[].subagents.allowAgents：可通过 agentId 指定的代理 id 列表（["*"] 表示允许任意）。默认仅允许请求方代理。发现：使用 agents_list 查看当前允许的代理 id。自动归档：子代理会话在 agents.defaults.subagents.archiveAfterMinutes（默认 60）后自动归档。归档使用 sessions.delete 并将转录重命名为 *.deleted.<timestamp>。cleanup: "delete" 在通知后立即归档。自动归档为尽力而为；网关重启会丢失未执行的计时器。runTimeoutSeconds 不触发自动归档；仅停止运行，会话保留直到自动归档。

认证

子代理认证按代理 id 解析，不按会话类型：

子代理会话键为 agent:<agentId>:subagent:<uuid>。
认证存储从该代理的 agentDir 加载。
主代理的认证配置作为回退合并；冲突时代理配置覆盖主配置。

说明：合并为叠加，主配置始终可作为回退。尚不支持按代理完全隔离的认证。

通知

子代理通过通知步骤回报：

通知步骤在子代理会话内执行（非请求方会话）。
若子代理回复恰好为 ANNOUNCE_SKIP，则不发帖。
否则通知回复通过后续 agent 调用（deliver=true）发往请求方聊天频道。
通知回复在可用时保留线程/话题路由（Slack 线程、Telegram 话题、Matrix 话题）。
通知消息规范为稳定模板：Status: 来自运行结果（success、error、timeout 或 unknown）；Result: 为通知步骤的摘要内容（缺失时为 (not available)）；Notes: 为错误详情等有用上下文。Status 不由模型输出推断，来自运行时结果信号。

通知负载末尾包含统计行（即使被换行）：运行时间、Token 使用、配置了模型定价时的估算成本、sessionKey、sessionId 与转录路径，便于主代理通过 sessions_history 获取历史或查看磁盘文件。

工具策略（子代理工具）

默认子代理获得除会话工具外的所有工具：sessions_list、sessions_history、sessions_send、sessions_spawn。可通过配置覆盖：


{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1
      }
    }
  },
  tools: {
    subagents: {
      tools: {
        deny: ["gateway", "cron"],
        // allow: ["read", "exec", "process"]
      }
    }
  }
}

并发

子代理使用专用进程内队列通道：通道名 subagent；并发数由 agents.defaults.subagents.maxConcurrent（默认 8）控制。

停止

在请求方聊天中发送 /stop 会中止请求方会话并停止由其派生的所有活跃子代理运行。

限制

子代理通知为尽力而为。网关重启时，未完成的“通知回传”会丢失。
子代理仍共享同一网关进程资源；将 maxConcurrent 视为安全阀。
sessions_spawn 始终非阻塞：立即返回 { status: "accepted", runId, childSessionKey }。
子代理上下文仅注入 AGENTS.md + TOOLS.md（无 SOUL.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md）。