子 Agent 委派

delegate_task 工具會啟動具有隔離上下文、受限工具集和獨立終端會話的子 AIAgent 實例。每個子 Agent 都會獲得一個全新的對話，並獨立工作——只有其最終摘要才會進入父 Agent 的上下文。

單個任務

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

並行批量任務

最多支持 3 個併發子 Agent：

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

子 Agent 上下文機制

重要：子 Agent 一無所知

子 Agent 從一個完全全新的對話開始。它們對父 Agent 的對話歷史、之前的工具調用或任何先前討論的內容都一無所知。子 Agent 的唯一上下文僅來自您提供的 goal 和 context 字段。

這意味著您必須傳遞所有子 Agent 所需的信息：

# BAD - subagent 不知道 "the error" 是什麼
delegate_task(goal="Fix the error")

# GOOD - subagent 擁有 context 所需的所有內容
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."""
)

子 Agent 將收到一個基於您的目標和上下文構建的聚焦系統提示，指示其完成任務，並提供結構化的摘要，包括所執行的操作、發現的內容、修改的文件以及遇到的問題。

實際示例

並行研究

同時研究多個主題並收集摘要：

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

多文件重構

委派一個大型重構任務，避免父 Agent 上下文被淹沒：

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 數組時，子 Agent 將以並行方式運行，使用線程池：

最大併發數：3 個任務（如果 tasks 數組長度超過 3，則截斷為 3）
線程池：使用 ThreadPoolExecutor，配置 MAX_CONCURRENT_CHILDREN = 3 個工作線程
進度顯示：在 CLI 模式下，以樹形視圖實時顯示每個子 Agent 的工具調用，並顯示每項任務的完成行；在網關模式下，進度將批量處理並轉發給父 Agent 的進度回調
結果排序：結果按任務索引排序，以匹配輸入順序，無論完成順序如何
中斷傳播：中斷父 Agent（例如發送新消息）將中斷所有活躍的子 Agent

單任務委派直接運行，無需線程池開銷。

模型覆蓋

您可以通過 config.yaml 配置子 Agent 使用不同的模型——這在將簡單任務委派給更便宜/更快的模型時非常有用：

# 在“0”中
delegation:
  model: "google/gemini-flash-2.0"    # 更便宜的 model 子代理
  provider: "openrouter"              # 可選：將子代理路由到不同的 provider

若未指定，子 Agent 將使用與父 Agent 相同的模型。

工具集選擇建議

toolsets 參數控制子 Agent 可訪問的工具。請根據任務類型選擇：

工具集模式	使用場景
`["terminal", "file"]`	代碼工作、調試、文件編輯、構建
`["web"]`	研究、事實核查、文檔查詢
`["terminal", "file", "web"]`	全棧任務（默認）
`["file"]`	只讀分析、不執行代碼的代碼審查
`["terminal"]`	系統管理、進程管理

某些工具集始終被禁止用於子 Agent，無論您如何配置：

delegation —— 禁止遞歸委派（防止無限生成）
clarify —— 子 Agent 無法與用戶交互
memory —— 無法寫入共享持久記憶
code_execution —— 子 Agent 應逐步推理
send_message —— 無跨平臺副作用（例如發送 Telegram 消息）

最大迭代次數

每個子 Agent 都有一個迭代限制（默認：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 —— 父 Agent（深度 0）可生成子 Agent（深度 1），但子 Agent 無法進一步委派。這可防止失控的遞歸委派鏈。

關鍵屬性

每個子 Agent 都擁有自己的終端會話（與父 Agent 分離）
無嵌套委派 —— 子 Agent 無法進一步委派（無孫 Agent）
子 Agent無法調用：delegate_task、clarify、memory、send_message、execute_code
中斷傳播 —— 中斷父 Agent 將中斷所有活躍子 Agent
僅最終摘要進入父 Agent 上下文，保持令牌使用效率
子 Agent 繼承父 Agent 的API 密鑰、提供方配置和憑證池（支持在限流時進行密鑰輪換）

委派 vs execute_code

因素	delegate_task	execute_code
推理能力	完整的 LLM 推理循環	僅執行 Python 代碼
上下文	完全隔離的全新對話	無對話，僅腳本
工具訪問	所有非被禁用工具，支持推理	通過 RPC 訪問 7 個工具，無推理能力
並行性	最多 3 個併發子 Agent	單個腳本
適用場景	需要判斷力或多步問題解決的複雜任務	機械式多步驟流水線
令牌成本	較高（完整 LLM 循環）	較低（僅返回 stdout）
用戶交互	無（子 Agent 無法澄清）	無

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

配置

# 在“0”中
delegation:
  max_iterations: 50                        # 每個孩子的最大輪數（默認值：50）
  default_toolsets: ["terminal", "file", "web"]  # 默認toolsets
  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 會根據任務的複雜程度自動處理委託。您無需明確要求它進行委託——當合適時，它會自動完成。

單個任務​

並行批量任務​

子 Agent 上下文機制​

實際示例​

並行研究​

代碼審查 + 修復​

多文件重構​

批量模式細節​

模型覆蓋​

工具集選擇建議​

最大迭代次數​

深度限制​

關鍵屬性​

委派 vs execute_code​

配置​