11.18 子代理

子代理是从现有代理运行中产生的后台代理运行。它们在自己的会话中运行,完成后将结果通告回请求者聊天频道。

概述

子代理系统允许主代理派生独立的后台任务,实现并行处理和任务隔离,同时保持会话安全性。

主要目标

• 并行化"研究/长任务/慢工具"工作而不阻塞主运行
• 通过会话分离和可选沙箱保持子代理隔离
• 保持工具表面难以误用:子代理默认不获取会话工具
• 避免嵌套扇出:子代理无法产生子代理

斜杠命令

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

# 列出子代理
/subagents list

# 停止子代理
/subagents stop <runId>

# 查看日志
/subagents log [limit] [tools]

# 查看详细信息
/subagents info <runId>

# 发送消息给子代理
/subagents send <runId> <message>

/subagents info 输出

显示运行元数据:

• 状态(运行中/完成/失败)
• 时间戳(开始/结束时间)
• 会话ID
• 转录路径
• 清理设置

工具使用: sessions_spawn

{
  "tool": "sessions_spawn",
  "task": "研究最新的AI技术趋势",
  "label": "AI研究",
  "agentId": "research",
  "model": "gpt-4",
  "thinking": "high",
  "runTimeoutSeconds": 600,
  "cleanup": "delete"
}

工具参数

• task (必需): 任务描述
• label (可选): 运行标签
• agentId (可选): 指定代理ID
• model (可选): 覆盖子代理模型
• thinking (可选): 思考级别
• runTimeoutSeconds (可选,默认0): 运行超时
• cleanup (可选,默认keep): "delete"或"keep"

模型配置

子代理继承调用者的模型,除非配置覆盖:

{
  "agents": {
    "defaults": {
      "subagents": {
        "model": "gpt-3.5-turbo"
      }
    },
    "list": [
      {
        "id": "main",
        "subagents": {
          "model": "gpt-4"
        }
      }
    ]
  }
}

代理白名单

{
  "agents": {
    "list": [
      {
        "id": "main",
        "subagents": {
          "allowAgents": ["research", "data-processor", "*"]
        }
      }
    ]
  }
}

使用 agents_list 工具查看允许的代理ID。

通告机制

子代理通过通告步骤报告结果:

1. 通告步骤在子代理会话内运行(非请求者会话)
2. 如果子代理回复 ANNOUNCE_SKIP,则不发送任何内容
3. 否则通告回复通过follow-up agent 调用发送到请求者频道
4. 通告消息在可用时保留线程/主题路由

通告消息格式

• Status: 从运行结果派生(success/error/timeout/unknown)
• Result: 通告步骤的摘要内容
• Notes: 错误详情和其他上下文

统计信息

通告有效载荷末尾包含统计行:

• 运行时间(如 runtime 5m12s)
• Token使用(输入/输出/总计)
• 估算成本(如果配置了模型定价)
• sessionKey, sessionId 和转录路径

自动归档

子代理会话在一定时间后自动归档:

{
  "agents": {
    "defaults": {
      "subagents": {
        "archiveAfterMinutes": 60
      }
    }
  }
}

• 默认: 60分钟后归档
• cleanup: "delete": 通告后立即归档
• 归档使用 sessions.delete 并将转录重命名为 *.deleted.
• Gateway重启时,待处理的定时器会丢失
• runTimeoutSeconds 不会自动归档,仅停止运行

认证

子代理认证按代理ID解析:

• 子代理会话键: agent::subagent:
• 从该代理的 agentDir 加载认证存储
• 主代理的认证配置文件作为回退合并
• 代理配置文件在冲突时覆盖主配置文件

工具策略

默认情况下,子代理获取除会话工具外的所有工具:

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

配置覆盖

{
  "tools": {
    "subagents": {
      "tools": {
        "deny": ["gateway", "cron"],
        // 如果设置allow,则变为仅允许模式(deny仍优先)
        // "allow": ["read", "exec", "process"]
      }
    }
  }
}

并发控制

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

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

• 通道名称: subagent
• 默认并发: 8

停止子代理

在请求者聊天中发送 /stop:

• 中止请求者会话
• 停止从中产生的所有活动子代理运行

限制

• 子代理通告是尽力而为的。Gateway重启时,待处理的"通告回复"工作会丢失
• 子代理共享相同的Gateway进程资源;将 maxConcurrent 视为安全阀
• sessions_spawn 始终非阻塞:立即返回 { status: "accepted", runId, childSessionKey }
• 子代理上下文仅注入 AGENTS.md + TOOLS.md(无 SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md 或 BOOTSTRAP.md)

使用场景

• 长时间研究任务: 不阻塞主对话的深度研究
• 并行数据处理: 同时处理多个数据源
• 独立任务隔离: 风险任务在隔离环境中执行
• 多阶段工作流: 复杂任务分解为多个子任务

最佳实践

• 为子代理使用描述性标签
• 设置适当的超时避免无限运行
• 为重复性任务使用更便宜的模型
• 监控子代理的资源使用
• 使用cleanup: "delete"自动清理短期任务
• 定期检查子代理日志