Subagent 委托

delegate_task 工具生成具有隔离上下文、受限工具集和各自终端会话的子 AIAgent 实例。每个子级获得新的对话并独立工作 — 只有其最终摘要进入父级的上下文。

单个任务

delegate_task(
    goal="Debug why tests fail",
    context="Error: assertion in test_foo.py line 42",
    toolsets=["terminal", "file"]
)

并行批处理

最多 3 个并发 subagent：

delegate_task(tasks=[
    {"goal": "Research topic A", "toolsets": ["web"]},
    {"goal": "Research topic B", "toolsets": ["web"]},
    {"goal": "Fix the build", "toolsets": ["terminal", "file"]}
])

Subagent 上下文如何工作

关键：Subagent 什么都不知道

Subagent 从完全新鲜的对话开始。他们对父级的对话历史、之前的工具调用或委托之前讨论的任何内容零了解。Subagent 的唯一上下文来自您提供的 goal 和 context 字段。

这意味着您必须传递 subagent 需要的一切：

# 不好 - subagent 不知道"错误"是什么
delegate_task(goal="Fix the error")

# 好 - subagent 拥有它需要的所有上下文
delegate_task(
    goal="Fix the TypeError in api/handlers.py",
    context="""The file api/handlers.py has a TypeError on line 47:
    'NoneType' object has no attribute 'get'.
    The function process_request() receives a dict from parse_body(),
    but parse_body() returns None when Content-Type is missing.
    The project is at /home/user/myproject and uses Python 3.11."""
)

Subagent 接收从您的 goal 和 context 构建的专注系统提示，指导它完成任务并提供所做工作的结构化摘要，包括修改了哪些文件、遇到了什么问题。

实际示例

并行研究

同时研究多个主题并收集摘要：

delegate_task(tasks=[
    {
        "goal": "Research the current state of WebAssembly in 2025",
        "context": "Focus on: browser support, non-browser runtimes, language support",
        "toolsets": ["web"]
    },
    {
        "goal": "Research the current state of RISC-V adoption in 2025",
        "context": "Focus on: server chips, embedded systems, software ecosystem",
        "toolsets": ["web"]
    },
    {
        "goal": "Research quantum computing progress in 2025",
        "context": "Focus on: error correction breakthroughs, practical applications, key players",
        "toolsets": ["web"]
    }
])

代码审查 + 修复

将审查和修复工作流委托给新鲜上下文：

delegate_task(
    goal="Review the authentication module for security issues and fix any found",
    context="""Project at /home/user/webapp.
    Auth module files: src/auth/login.py, src/auth/jwt.py, src/auth/middleware.py.
    The project uses Flask, PyJWT, and bcrypt.
    Focus on: SQL injection, JWT validation, password handling, session management.
    Fix any issues found and run the test suite (pytest tests/auth/).""",
    toolsets=["terminal", "file"]
)

多文件重构

委托一个会淹没父级上下文的大型重构任务：

delegate_task(
    goal="Refactor all Python files in src/ to replace print() with proper logging",
    context="""Project at /home/user/myproject.
    Use the 'logging' module with logger = logging.getLogger(__name__).
    Replace print() calls with appropriate log levels:
    - print(f"Error: ...") -> logger.error(...)
    - print(f"Warning: ...") -> logger.warning(...)
    - print(f"Debug: ...") -> logger.debug(...)
    - Other prints -> logger.info(...)
    Don't change print() in test files or CLI output.
    Run pytest after to verify nothing broke.""",
    toolsets=["terminal", "file"]
)

批处理模式详情

当您提供 tasks 数组时，subagent 使用线程池并行运行：

• 最大并发： 3 个任务（如果 tasks 数组更长，则截断为 3）
• 线程池： 使用 ThreadPoolExecutor，MAX_CONCURRENT_CHILDREN = 3 workers
• 进度显示： 在 CLI 模式下，树视图实时显示每个 subagent 的工具调用，带每任务完成行。在 gateway 模式下，进度被批处理并传递到父级的进度回调
• 结果排序： 结果按任务索引排序以匹配输入顺序，无论完成顺序如何
• 中断传播： 中断父级（例如，发送新消息）会中断所有活动子级

单任务委托直接运行，没有线程池开销。

模型覆盖

您可以通过 config.yaml 为 subagent 配置不同的模型 — 用于将简单任务委托给更便宜/更快的模型：

# 在 ~/.hermes/config.yaml 中
delegation:
  model: "google/gemini-flash-2.0"    # 用于 subagent 的更便宜模型
  provider: "openrouter"              # 可选：将 subagent 路由到不同的 provider

如果省略，subagent 使用与父级相同的模型。

工具集选择技巧

toolsets 参数控制 subagent 可以访问哪些工具。根据任务选择：

工具集模式	用例
["terminal", "file"]	代码工作、调试、文件编辑、构建
["web"]	研究、事实核查、文档查找
["terminal", "file", "web"]	全栈任务（默认）
["file"]	纯只读分析，无需执行的代码审查
["terminal"]	系统管理、进程管理

某些工具集始终被阻止用于 subagent，无论您指定什么：

• delegation — 无递归委托（防止无限生成）
• clarify — subagent 无法与用户交互
• memory — 不写入共享持久化内存
• code_execution — 子级应该逐步推理
• send_message — 无跨平台副作用（例如，发送 Telegram 消息）

最大迭代

每个 subagent 有迭代限制（默认：50），控制它可以进行多少次工具调用轮次：

delegate_task(
    goal="Quick file check",
    context="Check if /etc/nginx/nginx.conf exists and print its first 10 lines",
    max_iterations=10  # 简单任务，不需要很多轮次
)

深度限制

委托有深度限制为 2 — 父级（深度 0）可以生成子级（深度 1），但子级不能进一步委托。这防止失控的递归委托链。

关键属性

• 每个 subagent 获得自己的终端会话（与父级分开）
• 无嵌套委托 — 子级不能进一步委托（无孙级）
• Subagent 不能调用：delegate_task、clarify、memory、send_message、execute_code
• 中断传播 — 中断父级会中断所有活动子级
• 只有最终摘要进入父级上下文，保持 token 使用高效
• Subagent 继承父级的 API 密钥、provider 配置和凭证池（在速率限制时启用密钥轮换）

委托 vs execute_code

因素	delegate_task	execute_code
推理	完整 LLM 推理循环	仅 Python 代码执行
上下文	新鲜隔离对话	无对话，仅脚本
工具访问	带推理的所有非阻止工具	通过 RPC 的 7 个工具，无推理
并行性	最多 3 个并发 subagent	单脚本
最适合	需要判断的复杂任务	机械数据处理或脚本工作流
Token 成本	更高（完整 LLM 循环）	更低（仅返回 stdout）
用户交互	无（subagent 不能澄清）	无

经验法则： 当子任务需要推理、判断或多步骤问题时使用 delegate_task。当您需要机械数据处理或脚本工作流时使用 execute_code。

配置

# 在 ~/.hermes/config.yaml 中
delegation:
  max_iterations: 50                        # 每个子级的最大轮次（默认：50）
  default_toolsets: ["terminal", "file", "web"]  # 默认工具集
  model: "google/gemini-3-flash-preview"             # 可选的 provider/model 覆盖
  provider: "openrouter"                             # 可选内置 provider

# 或使用直接自定义端点而不是 provider：
delegation:
  model: "qwen2.5-coder"
  base_url: "http://localhost:1234/v1"
  api_key: "local-key"

提示

Agent 根据任务复杂度自动处理委托。您不需要明确要求它委托 — 当它有意义时会这样做。