<!-- Source: https://hermesbible.com/docs/guides/delegation-patterns -->

Hermes 可以產生獨立的子代理來平行處理任務。每個子代理都有自己的對話、終端機程式會話和工具集。只有最終摘要會回傳——中間的工具呼叫不會進入你的 context 視窗。

完整功能參考請見 子代理委派。

---

何時該委派

適合委派的情境：

• 需要大量推理的子任務（除錯、程式碼審查、研究綜合分析）
• 會用大量中間資料塞滿你 context 的任務
• 可平行處理的獨立工作流（同時研究 A 和 B）
• 需要無偏見切入的新 context 任務

使用其他方式的情境：

• 單一工具呼叫 → 直接使用工具
• 有邏輯判斷的機械式多步驟工作 → execute_code
• 需要使用者互動的任務 → 子代理無法使用 clarify
• 快速檔案編輯 → 直接操作
• 必須在目前回合結束後持續執行的長時間工作 → cronjob 或 terminal(background=True, notify_on_complete=True)。delegate_task 是同步的：如果父代被中斷，進行中的子代理會被取消，其工作成果會被丟棄。

---

模式：平行研究

同時研究三個主題並取得結構化摘要：

平行研究這三個主題：
1. WebAssembly 在瀏覽器之外的現狀
2. 2025 年 RISC-V 伺服器晶片的採用情況
3. 實用的量子運算應用

聚焦於最新發展和主要參與者。

底層 Hermes 使用的是：

delegate_task(tasks=[
    {
        "goal": "研究 2025 年 WebAssembly 在瀏覽器之外的發展",
        "context": "聚焦於：運行時（Wasmtime、Wasmer）、雲端/邊緣使用情境、WASI 進展",
        "toolsets": ["web"]
    },
    {
        "goal": "研究 RISC-V 伺服器晶片的採用情況",
        "context": "聚焦於：已出貨的伺服器晶片、雲端供應商的採用、軟體生態系",
        "toolsets": ["web"]
    },
    {
        "goal": "研究實用的量子運算應用",
        "context": "聚焦於：錯誤修正的突破、實際使用情境、關鍵企業",
        "toolsets": ["web"]
    }
])

三者同時執行。每個子代理獨立搜尋網路並回傳摘要。父代理再將它們綜合成一份連貫的簡報。

---

模式：程式碼審查

將安全審查委派給一個全新 context 的子代理，讓它毫無預設立場地審視程式碼：

審查 src/auth/ 中的模組是否有安全問題。
檢查 SQL 注入、JWT 驗證問題、密碼處理
以及 Session 管理。修復任何發現的問題並執行測試。

關鍵在於 context 欄位——必須包含子代理需要的所有資訊：

delegate_task(
    goal="審查 src/auth/ 的安全問題並修復任何發現的問題",
    context="""專案位於 /home/user/webapp。Python 3.11、Flask、PyJWT、bcrypt。
    認證檔案：src/auth/login.py、src/auth/jwt.py、src/auth/middleware.py
    測試指令：pytest tests/auth/ -v
    聚焦於：SQL 注入、JWT 驗證、密碼雜湊、Session 管理。
    修復發現的問題並確認測試通過。""",
    toolsets=["terminal", "file"]
)

WARNING — Context 問題

子代理對你的對話完全一無所知。它們從空白狀態開始。如果你委派「修復我們正在討論的那個 Bug」，子代理根本不知道你在說哪個 Bug。永遠要明確傳遞檔案路徑、錯誤訊息、專案結構和限制條件。

---

模式：比較替代方案

平行評估同一問題的多個方法，然後選出最佳方案：

我需要為我們的 Django 應用加入全文搜尋功能。平行評估三個方案：
1. PostgreSQL tsvector（內建）
2. 透過 django-elasticsearch-dsl 使用 Elasticsearch
3. 透過 meilisearch-python 使用 Meilisearch

針對每個方案評估：設定複雜度、查詢能力、資源需求
以及維護成本。比較後推薦一個方案。

每個子代理獨立研究一個選項。因為它們是隔離的，所以不存在交叉污染——每個評估都基於自身優劣。父代理取得所有三個摘要後進行比較。

---

模式：多檔案重構

將大型重構任務拆分給平行的子代理，各自處理程式碼庫的不同部分：

delegate_task(tasks=[
    {
        "goal": "將所有 API 端點處理器重構為使用新的回應格式",
        "context": """專案位於 /home/user/api-server。
        檔案：src/handlers/users.py、src/handlers/auth.py、src/handlers/billing.py
        舊格式：return {"data": result, "status": "ok"}
        新格式：return APIResponse(data=result, status=200).to_dict()
        匯入：from src.responses import APIResponse
        重構後執行測試：pytest tests/handlers/ -v""",
        "toolsets": ["terminal", "file"]
    },
    {
        "goal": "更新所有客戶端 SDK 方法以處理新的回應格式",
        "context": """專案位於 /home/user/api-server。
        檔案：sdk/python/client.py、sdk/python/models.py
        舊解析方式：result = response.json()["data"]
        新解析方式：result = response.json()["data"]（相同的 key，但需加上狀態碼檢查）
        同時更新 sdk/python/tests/test_client.py""",
        "toolsets": ["terminal", "file"]
    },
    {
        "goal": "更新 API 文件以反映新的回應格式",
        "context": """專案位於 /home/user/api-server。
        文件位於：docs/api/。格式：帶有程式碼範例的 Markdown。
        將所有回應範例從舊格式更新為新格式。
        在 docs/api/overview.md 新增「回應格式」章節說明 schema。""",
        "toolsets": ["terminal", "file"]
    }
])

TIP

每個子代理都有自己的終端機程式會話。它們可以在同一個專案目錄下工作而不會互相干擾——前提是它們編輯的是不同的檔案。如果兩個子代理可能編輯同一個檔案，請在平行工作完成後自行處理該檔案。

---

模式：先收集再分析

使用 execute_code 進行機械式的資料收集，然後委派需要大量推理的分析工作：

# 步驟 1：機械式收集（這裡用 execute_code 較好——不需要推理）
execute_code("""
from hermes_tools import web_search, web_extract

results = []
for query in ["AI funding Q1 2026", "AI startup acquisitions 2026", "AI IPOs 2026"]:
    r = web_search(query, limit=5)
    for item in r["data"]["web"]:
        results.append({"title": item["title"], "url": item["url"], "desc": item["description"]})

# 從前 5 個最相關的結果提取完整內容
urls = [r["url"] for r in results[:5]]
content = web_extract(urls)

# 儲存供分析步驟使用
import json
with open("/tmp/ai-funding-data.json", "w") as f:
    json.dump({"search_results": results, "extracted": content["results"]}, f)
print(f"Collected {len(results)} results, extracted {len(content['results'])} pages")
""")

# 步驟 2：需要大量推理的分析（這裡委派較好）
delegate_task(
    goal="分析 AI 融資資料並撰寫市場報告",
    context="""/tmp/ai-funding-data.json 中的原始資料包含搜尋結果和
    2026 年第一季 AI 融資、收購和 IPO 的擷取網頁內容。
    撰寫一份結構化的市場報告：重要交易、趨勢、值得注意的參與者
    和展望。聚焦於超過 1 億美元的交易。""",
    toolsets=["terminal", "file"]
)

這通常是最有效率的模式：execute_code 便宜地處理 10 個以上的順序工具呼叫，然後子代理在乾淨的 context 中完成單一的高成本推理任務。

---

工具集選擇

根據子代理的需求選擇工具集：

限制工具集可以讓子代理保持專注，並防止意外的副作用（例如研究子代理執行終端機指令）。

---

限制

• 預設 3 個平行任務：批次預設為 3 個並行子代理（可透過 config.yaml 中的 delegation.max_concurrent_children 設定，無硬性上限，只有下限 1）
• 巢狀委派需手動啟用：葉子子代理（預設）無法呼叫 delegate_task、clarify、memory、send_message 或 execute_code。協調器子代理（role="orchestrator"）保留 delegate_task 以進行進一步委派，但僅在 delegation.max_spawn_depth 高於預設值 1 時可用（下限 1，無上限）；其餘四項仍被封鎖。可透過 delegation.orchestrator_enabled: false 全域停用。

調整並行度與深度

範例：執行 30 個平行工作者並使用巢狀子代理：

delegation:
  max_concurrent_children: 30
  max_spawn_depth: 2

• 獨立終端機 — 每個子代理都有自己的終端機程式會話，包含獨立的工作目錄和狀態
• 無對話歷史 — 子代理只能看到父代理在呼叫 delegate_task 時傳遞的 goal 和 context
• 預設 50 次迭代 — 對於簡單任務可設定較低的 max_iterations 以節省成本
• 非持久化 — delegate_task 是同步的，在父代回合內執行。如果父代被中斷（新的使用者訊息、/stop、/new），所有進行中的子代都會被取消（status="interrupted"），其工作成果會被丟棄。對於必須在目前回合結束後持續的工作，請使用 cronjob 或 terminal(background=True, notify_on_complete=True)。

---

小技巧

目標要具體。「修復那個 Bug」太模糊了。「修復 api/handlers.py 第 47 行的 TypeError，其中 process_request() 從 parse_body() 收到 None」能給子代理足夠的資訊來執行。

**包含檔案路徑。**子代理不知道你的專案結構。永遠要包含相關檔案的絕對路徑、專案根目錄和測試指令。

**利用委派實現 context 隔離。**有時候你需要一個全新的視角。委派能強制你清楚陳述問題，而子代理會在不受你對話中累積的假設影響下處理它。

**驗證結果。**子代理的摘要只是摘要——如果子代理說「已修復 Bug 且測試通過」，請親自執行測試或閱讀 diff 來驗證。

---

完整的委派參考——所有參數、ACP 整合和進階設定——請見 子代理委派。

---

---

教學：GitHub PR 審查代理