子 agent

子 agent 是从现有 agent 运行生成的后台 agent 运行。它们在自己的会话中运行(agent:<agentId>:subagent:<uuid>),完成后宣布结果回到请求者聊天频道。

斜杠命令

使用 /subagents 检查或控制当前会话的子 agent 运行:

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

/subagents info 显示运行元数据(状态、时间戳、会话 id、转录路径、清理)。

主要目标:

  • 在不阻塞主运行的情况下并行化"研究/长任务/慢工具"工作。
  • 默认保持子 agent 隔离(会话分离 + 可选沙箱)。
  • 保持工具接口难以误用: 子 agent 默认不获得会话工具。
  • 避免嵌套扇出: 子 agent 无法生成子 agent。

成本注意事项: 每个子 agent 都有自己的上下文和 token 使用量。对于繁重或重复的任务,为子 agent 设置更便宜的模型,并在更高质量的模型上保持主 agent。您可以通过 agents.defaults.subagents.model 或每个 agent 的覆盖来配置这一点。

工具

使用 sessions_spawn:

  • 启动子 agent 运行(deliver: false,全局通道: subagent)
  • 然后运行宣布步骤并将宣布回复发布到请求者聊天频道
  • 默认模型: 继承调用者,除非您设置 agents.defaults.subagents.model (或每个 agent 的 agents.list[].subagents.model);显式的 sessions_spawn.model 仍然获胜。

工具参数:

  • task (必需)
  • label? (可选)
  • agentId? (可选;如果允许,在另一个 agent id 下生成)
  • model? (可选;覆盖子 agent 模型;无效值被跳过,子 agent 在默认模型上运行,工具结果中有警告)
  • thinking? (可选;覆盖子 agent 运行的思考级别)
  • runTimeoutSeconds? (默认 0;设置时,子 agent 运行在 N 秒后中止)
  • cleanup? (delete|keep,默认 keep)

Allowlist:

  • agents.list[].subagents.allowAgents: 可以通过 agentId 定位的 agent id 列表(["*"] 允许任何)。默认: 仅请求者 agent。

发现:

  • 使用 agents_list 查看当前允许 sessions_spawn 的 agent id。

自动归档:

  • 子 agent 会话在 agents.defaults.subagents.archiveAfterMinutes (默认: 60) 后自动归档。
  • 归档使用 sessions.delete 并将转录重命名为 *.deleted.<timestamp> (同一文件夹)。
  • cleanup: "delete" 在宣布后立即归档(仍通过重命名保留转录)。
  • 自动归档是尽力而为的;如果 gateway 重启,挂起的计时器会丢失。
  • runTimeoutSeconds 不自动归档;它仅停止运行。会话保留直到自动归档。

认证

子 agent 认证由agent id 解析,而非会话类型:

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

注意: 合并是累加的,因此主配置文件始终作为回退可用。尚不支持每个 agent 完全隔离的认证。

宣布

子 agent 通过宣布步骤报告:

  • 宣布步骤在子 agent 会话内运行(而非请求者会话)。
  • 如果子 agent 准确回复 ANNOUNCE_SKIP,则不发布任何内容。
  • 否则,宣布回复通过后续 agent 调用(deliver=true)发布到请求者聊天频道。
  • 宣布回复在可用时保留线程/主题路由(Slack 线程、Telegram 主题、Matrix 线程)。
  • 宣布消息被规范化为稳定的模板:
    • Status: 从运行结果派生(success, error, timeout, 或 unknown)。
    • Result: 来自宣布步骤的摘要内容(或如果缺失则为 (not available))。
    • Notes: 错误详情和其他有用的上下文。
  • Status 不是从模型输出推断的;它来自运行时结果信号。

宣布有效负载在末尾包含统计行(即使包装时):

  • 运行时间(例如,runtime 5m12s)
  • Token 使用量(输入/输出/总计)
  • 配置模型定价时的估计成本(models.providers.*.models[].cost)
  • sessionKey, sessionId, 和转录路径(以便主 agent 可以通过 sessions_history 获取历史或检查磁盘上的文件)

工具策略(子 agent 工具)

默认情况下,子 agent 获得除会话工具外的所有工具:

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn

通过配置覆盖:

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1
      }
    }
  },
  tools: {
    subagents: {
      tools: {
        // deny 优先
        deny: ["gateway", "cron"],
        // 如果设置 allow,它变成仅允许(deny 仍然优先)
        // allow: ["read", "exec", "process"]
      }
    }
  }
}

并发

子 agent 使用专用的进程内队列通道:

  • 通道名称: subagent
  • 并发: agents.defaults.subagents.maxConcurrent (默认 8)

停止

  • 在请求者聊天中发送 /stop 会中止请求者会话并停止从它生成的任何活动子 agent 运行。

限制

  • 子 agent 宣布是尽力而为的。如果 gateway 重启,挂起的"宣布回来"工作会丢失。
  • 子 agent 仍然共享相同的 gateway 进程资源;将 maxConcurrent 视为安全阀。
  • sessions_spawn 始终是非阻塞的: 它立即返回 { status: "accepted", runId, childSessionKey }。
  • 子 agent 上下文仅注入 AGENTS.md + TOOLS.md (无 SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, 或 BOOTSTRAP.md)。
← 返回文档首页