H繁中版
文件user-guidedelegation
<!-- Source: https://hermesbible.com/docs/user-guide/features/delegation -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/delegation

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

子代理上下文運作方式

警告 — 重要：子代理什麼都不知道

子代理從完全嶄新的對話開始。它對父代理的對話歷史、先前的工具呼叫或委派前討論過的任何內容都一無所知。子代理唯一的上下文來自父代理在呼叫 delegate_task 時填入的 goal 和 context 欄位。

這意味著父代理必須在呼叫中傳遞子代理所需的所有資訊：

# 不佳 — 子代理完全不知道「錯誤」是什麼
delegate_task(goal="Fix the error")

# 良好 — 子代理擁有所有必要的上下文
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__).
    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 個任務（可透過 delegation.max_concurrent_children 或環境變數 DELEGATION_MAX_CONCURRENT_CHILDREN 設定；下限為 1，無硬性上限）。超過限制的批次會回傳工具錯誤，而非靜默截斷。
  • 執行緒池： 使用 ThreadPoolExecutor，以設定的並行上限作為最大工作執行緒數
  • 進度顯示： 在 CLI 模式中，以樹狀視圖即時顯示每個子代理的工具呼叫，並帶有每個任務的完成行。在 gateway 模式中，進度會批次處理並傳送到父代理的進度回呼函式
  • 結果排序： 結果按任務索引排序，以符合輸入順序，不論完成順序為何
  • 中斷傳播： 中斷父代理（例如傳送新訊息）會中斷所有作用中的子代理

單一任務委派直接執行，不經過執行緒池。

模型覆寫

你可以透過 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 — 葉子子代理（預設）被封鎖。role="orchestrator" 的子代理會保留此工具組，但受 max_spawn_depth 限制——詳見下方深度限制與巢狀編排。
  • 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  # 簡單任務，不需要太多輪次
)

子代理逾時

預設情況下，子代理沒有時間逾時限制。子代理只會因為實際執行的內容而失敗——API 錯誤、工具錯誤或達到迭代表次預算——永遠不會因為委派層級的計時器而中止。早期版本曾實作硬性上限（300 秒，後改為 600 秒），但這導致正當忙碌的子代理在任務中途被終止：深度程式碼審查、大型研究扇出和較慢的推理模型通常需要超過 10 分鐘，且整個過程都在穩定進展中。

真正卡住的子代理仍會被偵測到：心跳過期監控器會在子代理毫無進展（無 API 呼叫、無工具啟動）時停止刷新父代理的活動狀態，讓 gateway 的閒置逾時能在真正卡死的工作者上觸發。

如果你仍然需要硬性上限（例如對無人值守的 cron 驅動委派進行成本控制），可以選擇啟用：

delegation:
  child_timeout_seconds: 0     # default: 0 = no timeout
  # child_timeout_seconds: 1800  # opt-in hard cap (floor 30s)

正值會對每個子代理強制執行硬性的時間限制；0 或負值則停用此功能。

提示 — 零呼叫逾時的診斷轉儲

設定硬性上限後，如果子代理在零次 API 呼叫的情況下逾時（通常是：提供者無法連線、認證失敗或工具結構描述被拒絕），delegate_task 會將結構化診斷資訊寫入 ~/.hermes/logs/subagent-timeout-<session>-<timestamp>.log，包含子代理的設定快照、認證解析追蹤和任何早期錯誤訊息。比先前的靜默逾時行為更容易找出根本原因。

監控執行中的子代理（/agents）

TUI 內建 /agents 視圖覆蓋層（別名 /tasks），將遞迴的 delegate_task 扇出轉變為一級稽核介面：

  • 即時樹狀視圖，顯示執行中和最近完成的子代理，按父代理分組
  • 每個分支的成本、token 使用量和檔案存取彙總
  • 終止和暫停控制——可以在不中斷同級子代理的情況下取消特定子代理
  • 事後審查：即使子代理已回傳父代理，仍可逐步檢視每個子代理的逐輪歷史

經典 CLI 模式只會以文字摘要列印 /agents；TUI 才是覆蓋層真正發揮作用的地方。詳見 TUI — 斜線指令。

深度限制與巢狀編排

預設情況下，委派是扁平的：父代理（深度 0）產生子代理（深度 1），而這些子代理無法進一步委派。這可防止遞迴委派失控。

對於多階段工作流程（研究→綜合，或跨子問題的並行編排），父代理可以產生orchestrator（編排器）子代理，它可以委派自己的工作者：

delegate_task(
    goal="Survey three code review approaches and recommend one",
    role="orchestrator",  # 允許此子代理產生自己的工作者
    context="...",
)
  • role="leaf"（預設）：子代理無法進一步委派——與扁平行為相同。
  • role="orchestrator"：子代理保留 delegation 工具組。受 delegation.max_spawn_depth 限制（預設 1 = 扁平，所以 role="orchestrator" 在預設設定下不起作用）。將 max_spawn_depth 提高到 2 可允許編排器子代理產生葉子孫代理；3 或更高可用於更深的樹狀結構。沒有硬性上限——成本才是實際的限制。
  • delegation.orchestrator_enabled: false：全域停用開關，強制所有子代理使用 leaf 角色，不論 role 參數為何。

成本警告： 當 max_spawn_depth: 3 且 max_concurrent_children: 3 時，樹狀結構最多可達 3×3×3 = 27 個並行葉子代理。每增加一層都會倍增花費——請有意識地調整 max_spawn_depth。

生命週期與持久性

警告 — delegate_task 是同步的——不具持久性

delegate_task 在父代理的當前輪次內執行。它會阻塞父代理直到所有子代理完成（或被取消）。它不是背景工作佇列：

  • 如果父代理被中斷（使用者傳送新訊息、/stop、/new），所有作用中的子代理都會被取消並回傳 status="interrupted"。它們進行中的工作會被丟棄。
  • 子代理不會在父代理輪次結束後繼續運作。
  • 被取消的子代理會回傳結構化結果（status="interrupted"、exit_reason="interrupted"），但因為父代理也被中斷了，該結果通常不會出現在使用者可見的回覆中。

對於必須能在中斷中存活或超越當前輪次的持久性長時間運行工作，請使用：

  • cronjob（action=create）——排程獨立的代理運行；不受父代理輪次中斷影響。
  • terminal(background=True, notify_on_complete=True)——長時間運行的 shell 指令，可在代理執行其他工作時持續運作。

關鍵屬性

  • 每個子代理獲得獨立的終端機工作階段（與父代理分開）
  • 巢狀委派為選擇性啟用——只有 role="orchestrator" 的子代理可以進一步委派，且只有在 max_spawn_depth 從預設的 1（扁平）提高時才有效。可透過 orchestrator_enabled: false 全域停用。
  • 葉子子代理無法呼叫：delegate_task、clarify、memory、send_message、execute_code。編排器子代理保留 delegate_task，但仍無法使用其他四個。
  • 中斷傳播——中斷父代理會中斷所有作用中的子代理（包括編排器下的孫代理）
  • 只有最終摘要進入父代理的上下文，保持 token 使用效率
  • 子代理繼承父代理的 API 金鑰、提供者設定和認證池（可在達到速率限制時進行金鑰輪替）

delegate_task vs execute_code

因素delegate_taskexecute_code
推理完整的 LLM 推理迴圈僅 Python 程式碼執行
上下文全新隔離的對話無對話，僅腳本
工具存取所有未封鎖的工具加上推理透過 RPC 使用 7 個工具，無推理
並行性預設 3 個並行子代理（可設定）單一脚本
最適合需要判斷力的複雜任務機械化的多步驟流程
Token 成本較高（完整 LLM 迴圈）較低（僅回傳 stdout）
使用者互動無（子代理無法澄清）無

經驗法則： 當子任務需要推理、判斷或多步驟問題解決時，使用 delegate_task。當你需要機械化的資料處理或腳本化工作流程時，使用 execute_code。

設定

# In ~/.hermes/config.yaml
delegation:
  max_iterations: 50                        # Max turns per child (default: 50)
  # max_concurrent_children: 3              # Parallel children per batch (default: 3)
  # max_spawn_depth: 1                      # Tree depth (floor 1, no ceiling, default 1 = flat). Raise to 2 to allow orchestrator children to spawn leaves; 3+ for deeper trees.
  # orchestrator_enabled: true              # Disable to force all children to leaf role.
  model: "google/gemini-3-flash-preview"             # Optional provider/model override
  provider: "openrouter"                             # Optional built-in provider
  api_mode: anthropic_messages                       # optional; auto-detected from base_url for anthropic_messages endpoints

# Or use a direct custom endpoint instead of provider:
delegation:
  model: "qwen2.5-coder"
  base_url: "http://localhost:1234/v1"
  api_key: "local-key"
  # api_mode: "anthropic_messages"  # Optional. Wire protocol override for base_url ("chat_completions", "codex_responses", or "anthropic_messages"). Empty = auto-detect from URL (e.g. /anthropic suffix). Set explicitly for endpoints the heuristic can't classify (Azure AI Foundry, MiniMax, Zhipu GLM, LiteLLM proxies, …).

當 base_url 指向相容 Anthropic 的端點——例如以 /anthropic 結尾的路徑、Azure Foundry Claude 路由或 MiniMax /anthropic 代理——api_mode 會自動偵測為 anthropic_messages，讓子代理無需額外設定即可使用正確的通訊格式。當自動偵測的判斷有誤時（少見），才需要明確設定 api_mode。

提示

代理會根據任務複雜度自動處理委派。你不需要明確要求它委派——它會在適當的時機自動執行。

看板（多代理看板）

curatordeliverable mode