子代理委派

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"]}
])

子代理上下文机制

重要：子代理一无所知

子代理从一个完全全新的对话开始。它们对父代理的对话历史、之前的工具调用或任何先前讨论的内容都一无所知。子代理的唯一上下文仅来自您提供的 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."""
)

子代理将收到一个基于您的目标和上下文构建的聚焦系统提示，指示其完成任务，并提供结构化的摘要，包括所执行的操作、发现的内容、修改的文件以及遇到的问题。

实际示例

并行研究

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

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 数组时，子代理将以并行方式运行，使用线程池：

• 最大并发数：3 个任务（如果 tasks 数组长度超过 3，则截断为 3）
• 线程池：使用 ThreadPoolExecutor，配置 MAX_CONCURRENT_CHILDREN = 3 个工作线程
• 进度显示：在 CLI 模式下，以树形视图实时显示每个子代理的工具调用，并显示每项任务的完成行；在网关模式下，进度将批量处理并转发给父代理的进度回调
• 结果排序：结果按任务索引排序，以匹配输入顺序，无论完成顺序如何
• 中断传播：中断父代理（例如发送新消息）将中断所有活跃的子代理

单任务委派直接运行，无需线程池开销。

模型覆盖

您可以通过 config.yaml 配置子代理使用不同的模型——这在将简单任务委派给更便宜/更快的模型时非常有用：

# In ~/.hermes/config.yaml
delegation:
  model: "google/gemini-flash-2.0"    # Cheaper model for subagents
  provider: "openrouter"              # Optional: route subagents to a different provider

若未指定，子代理将使用与父代理相同的模型。

工具集选择建议

toolsets 参数控制子代理可访问的工具。请根据任务类型选择：

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

某些工具集始终被禁止用于子代理，无论您如何配置：

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

最大迭代次数

每个子代理都有一个迭代限制（默认：50），控制其可执行的工具调用轮次：

delegate_task(
    goal="Quick file check",
    context="Check if /etc/nginx/nginx.conf exists and print its first 10 lines",
    max_iterations=10  # Simple task, don't need many turns
)

深度限制

委派具有深度限制 2 —— 父代理（深度 0）可生成子代理（深度 1），但子代理无法进一步委派。这可防止失控的递归委派链。

关键属性

• 每个子代理都拥有自己的终端会话（与父代理分离）
• 无嵌套委派 —— 子代理无法进一步委派（无孙代理）
• 子代理无法调用：delegate_task、clarify、memory、send_message、execute_code
• 中断传播 —— 中断父代理将中断所有活跃子代理
• 仅最终摘要进入父代理上下文，保持令牌使用效率
• 子代理继承父代理的API 密钥、提供方配置和凭证池（支持在限流时进行密钥轮换）

委派 vs execute_code

因素	delegate_task	execute_code
推理能力	完整的 LLM 推理循环	仅执行 Python 代码
上下文	完全隔离的全新对话	无对话，仅脚本
工具访问	所有非被禁用工具，支持推理	通过 RPC 访问 7 个工具，无推理能力
并行性	最多 3 个并发子代理	单个脚本
适用场景	需要判断力或多步问题解决的复杂任务	机械式多步骤流水线
令牌成本	较高（完整 LLM 循环）	较低（仅返回 stdout）
用户交互	无（子代理无法澄清）	无

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

配置

# In ~/.hermes/config.yaml
delegation:
  max_iterations: 50                        # Max turns per child (default: 50)
  default_toolsets: ["terminal", "file", "web"]  # Default toolsets
  model: "google/gemini-3-flash-preview"             # Optional provider/model override
  provider: "openrouter"                             # Optional built-in provider

# Or use a direct custom endpoint instead of provider:
delegation:
  model: "qwen2.5-coder"
  base_url: "http://localhost:1234/v1"
  api_key: "local-key"

提示

代理会根据任务的复杂程度自动处理委托。您无需明确要求它进行委托——当合适时，它会自动完成。