子代理委派

delegate_task 工具会启动子 AIAgent 实例，它们拥有隔离的上下文、受限的工具集以及各自独立的终端会话。每个子智能体都会从一段全新对话开始独立工作，只有最终总结会进入父智能体的上下文。

单任务示例

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

并行批量任务

默认最多并发 3 个子智能体（可配置，无硬上限）：

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

子智能体上下文如何工作

Critical: Subagents Know Nothing

子智能体会以全新对话启动。它们不知道父智能体此前的对话历史、工具调用或任何讨论内容。子智能体唯一拥有的上下文就是父智能体在调用 delegate_task 时通过 goal 和 context 传入的信息。

这意味着父智能体必须显式传入子智能体所需的一切：

# BAD - subagent has no idea what "the error" is
delegate_task(goal="Fix the error")

# GOOD - subagent has all context it needs
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."""
)

子智能体会收到一个聚焦式系统提示，基于你提供的 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__).""",
    toolsets=["terminal", "file"]
)

Batch 模式细节

当你提供 tasks 数组时，子智能体会通过线程池并行运行：

• 默认最大并发： 3，可通过 delegation.max_concurrent_children 或 DELEGATION_MAX_CONCURRENT_CHILDREN 配置
• 线程池： 使用 ThreadPoolExecutor
• 进度显示： CLI 中会显示树状进度；gateway 模式下会批量转发进度
• 结果顺序： 无论完成顺序如何，最终结果都会按输入顺序排序
• 中断传播： 中断父智能体会同时中断全部活跃子智能体

单任务 delegation 会直接执行，不经过线程池。

模型覆盖

你可以在 config.yaml 中为子智能体指定不同模型，以便把简单任务委派给更便宜或更快的模型：

delegation:
  model: "google/gemini-flash-2.0"
  provider: "openrouter"

如果不设置，子智能体会继承父智能体当前模型。

工具集选择建议

toolsets 参数控制子智能体能使用哪些工具：

Toolset Pattern	Use Case
["terminal", "file"]	代码工作、调试、文件编辑、构建
["web"]	研究、事实核查、查文档
["terminal", "file", "web"]	全栈任务（默认）
["file"]	只读分析、无需执行的代码审查
["terminal"]	系统管理、进程管理

无论你怎么传，某些工具集对子智能体始终会被屏蔽：

• delegation — leaf 子智能体默认不可再次委派
• clarify — 子智能体不能直接与用户交互
• memory — 不能写共享持久记忆
• code_execution — 子智能体应逐步推理，而非再开代码执行
• send_message — 不能产生跨平台副作用

最大迭代数

每个子智能体有独立的迭代上限（默认 50），用于限制其工具调用轮数：

delegate_task(
    goal="Quick file check",
    context="Check if /etc/nginx/nginx.conf exists and print its first 10 lines",
    max_iterations=10
)

深度限制与嵌套编排

默认情况下，delegation 是扁平的：父级（深度 0）生成子级（深度 1），而这些子级不能继续 delegation。这样可以防止递归式委派失控。

如果要构建多阶段工作流（如研究 → 汇总），父级可以生成 orchestrator 子级，让它继续启动自己的 worker：

delegate_task(
    goal="Survey three code review approaches and recommend one",
    role="orchestrator",
    context="...",
)

• role="leaf"（默认）：子智能体不能继续 delegation
• role="orchestrator"：保留 delegation 工具集，但是否真能继续 delegation 还取决于 delegation.max_spawn_depth
• delegation.orchestrator_enabled: false：全局关闭 orchestrator，强制所有子智能体都作为 leaf 运行

提示

如果开启多层 delegation，成本会呈乘法增长，因此请谨慎提升 max_spawn_depth。

关键特性

• 每个子智能体都有自己的终端会话
• 嵌套 delegation 是 opt-in，默认关闭
• leaf 子智能体不能调用：delegate_task、clarify、memory、send_message、execute_code
• 中断传播：中断父级会中断所有子级
• 只有最终总结进入父级上下文，因此 token 消耗更高效
• 子智能体会继承父级的 API key、provider 配置和 credential pool

delegation vs execute_code

因素	delegate_task	execute_code
推理能力	完整 LLM 推理循环	仅 Python 脚本执行
上下文	全新隔离对话	无对话，仅脚本
工具访问	全部未屏蔽工具	通过 RPC 调 7 个工具
并行性	默认 3 个并发子智能体	单脚本
适用场景	复杂、需要判断的子任务	机械式多步流水线
token 成本	更高	更低
用户交互	无	无

经验法则： 子任务需要推理、判断或多步问题求解时，用 delegate_task；需要机械式数据处理或脚本化流程时，用 execute_code。

配置

# In ~/.hermes/config.yaml
delegation:
  max_iterations: 50
  model: "google/gemini-3-flash-preview"
  provider: "openrouter"

提示

智能体会根据任务复杂度自动决定是否使用 delegation。多数情况下，你不需要显式要求它进行委派。