代理程式迴圈如何運作

​

迴圈概覽

1. 接收提示。 Claude 接收您的提示，以及系統提示、工具定義和對話歷史記錄。SDK 會產生一個 SystemMessage，其子類型為 "init"，包含工作階段中繼資料。
2. 評估並回應。 Claude 評估目前狀態並決定如何進行。它可能會以文字回應、要求一個或多個工具呼叫，或兩者都有。SDK 會產生一個 AssistantMessage，包含文字和任何工具呼叫要求。
3. 執行工具。 SDK 執行每個要求的工具並收集結果。每組工具結果都會回饋給 Claude 以進行下一個決定。您可以使用 hooks 在工具執行前攔截、修改或阻止工具呼叫。
4. 重複。 步驟 2 和 3 重複為一個週期。每個完整週期是一個回合。Claude 繼續呼叫工具並處理結果，直到它產生沒有工具呼叫的回應。
5. 返回結果。 SDK 會產生最終的 AssistantMessage，包含文字回應（無工具呼叫），然後是 ResultMessage，包含最終文字、代幣使用量、成本和工作階段 ID。

​

回合和訊息

1. 回合 1： Claude 呼叫 Bash 執行 npm test。SDK 產生一個 AssistantMessage，包含工具呼叫，執行命令，然後產生一個 UserMessage，包含輸出（三個失敗）。
2. 回合 2： Claude 在 auth.ts 和 auth.test.ts 上呼叫 Read。SDK 返回檔案內容並產生一個 AssistantMessage。
3. 回合 3： Claude 呼叫 Edit 修復 auth.ts，然後呼叫 Bash 重新執行 npm test。所有三個測試都通過。SDK 產生一個 AssistantMessage。
4. 最終回合： Claude 產生一個純文字回應，沒有工具呼叫：「修復了驗證錯誤，所有三個測試現在都通過了。」SDK 產生最終的 AssistantMessage，包含此文字，然後是 ResultMessage，包含相同的文字加上成本和使用量。

​

訊息類型

• SystemMessage： 工作階段生命週期事件。subtype 欄位區分它們：
  • "init"：第一個訊息，包含工作階段中繼資料
  • "compact_boundary"：在 壓縮 後觸發
  • "informational"：來自迴圈的純文字狀態橫幅
  • "worker_shutting_down"：迴圈將在目前回合後結束，因為主機正在退出或遠端控制已斷開連線
  在 TypeScript 中，除了 "init" 之外的每個子類型都是 SDKMessage 聯合 中的自己的類型，而不是 SDKSystemMessage 的子類型。
• AssistantMessage： 在每個 Claude 回應後發出，包括最終純文字回應。包含該回合的文字內容區塊和工具呼叫區塊。
• UserMessage： 在每個工具執行後發出，包含發送回 Claude 的工具結果內容。也針對您在迴圈中期串流的任何使用者輸入發出。
• StreamEvent： 僅在啟用部分訊息時發出。包含原始 API 串流事件（文字增量、工具輸入區塊）。請參閱 串流回應。
• ResultMessage： 標記代理程式迴圈的結束。包含最終文字結果、代幣使用量、成本和工作階段 ID。檢查 subtype 欄位以確定任務是否成功或達到限制。少數尾隨系統事件（例如 prompt_suggestion）可能在其後到達，因此請迭代串流至完成，而不是在結果時中斷。請參閱 處理結果。

​

處理訊息

• 僅最終結果： 處理 ResultMessage 以取得輸出、成本以及任務是否成功或達到限制。
• 進度更新： 處理 AssistantMessage 以查看 Claude 在每個回合中做什麼，包括它呼叫了哪些工具。
• 即時串流： 啟用部分訊息（Python 中的 include_partial_messages、TypeScript 中的 includePartialMessages）以實時取得 StreamEvent 訊息。請參閱 即時串流回應。

• Python： 使用從 claude_agent_sdk 匯入的類別檢查訊息類型，使用 isinstance()（例如，isinstance(message, ResultMessage)）。
• TypeScript： 檢查 type 字串欄位（例如，message.type === "result"）。AssistantMessage 和 UserMessage 將原始 API 訊息包裝在 .message 欄位中，因此內容區塊位於 message.message.content，而不是 message.content。

from claude_agent_sdk import query, AssistantMessage, ResultMessage

async for message in query(prompt="Summarize this project"):
    if isinstance(message, AssistantMessage):
        print(f"Turn completed: {len(message.content)} content blocks")
    if isinstance(message, ResultMessage):
        if message.subtype == "success":
            print(message.result)
        else:
            print(f"Stopped: {message.subtype}")

​

工具執行

​

內建工具

• 使用 MCP 伺服器 連接外部服務（資料庫、瀏覽器、API）
• 使用 自訂工具處理程式 定義自訂工具
• 透過 設定來源 加載專案技能以實現可重複使用的工作流程

​

工具權限

• allowed_tools / allowedTools 自動批准列出的工具。具有 ["Read", "Glob", "Grep"] 在其允許工具清單中的唯讀代理程式會執行這些工具而不提示。未列出的工具仍然可用，但需要權限。
• disallowed_tools / disallowedTools 阻止列出的工具，無論其他設定如何。請參閱 權限 以了解在工具執行前檢查規則的順序。
• permission_mode / permissionMode 控制對不受允許或拒絕規則涵蓋的工具會發生什麼。請參閱 權限模式 以了解可用的模式。

​

平行工具執行

​

控制迴圈如何執行

​

回合和預算

​

努力等級

​

權限模式

​

模型

​

上下文視窗

​

什麼消耗上下文

​

自動壓縮

• CLAUDE.md 中的摘要指示： 壓縮器像任何其他上下文一樣讀取您的 CLAUDE.md，因此您可以包含一個部分，告訴它在摘要時要保留什麼。部分標題是自由格式的（不是魔法字串）；壓縮器根據意圖匹配。
• PreCompact hook： 在壓縮發生前執行自訂邏輯，例如存檔完整成績單。hook 接收一個 trigger 欄位（manual 或 auto）。請參閱 hooks。
• 手動壓縮： 將 /compact 作為提示字串發送以按需觸發壓縮。以這種方式發送的命令是 SDK 輸入，而不是僅限 CLI 的快捷方式。請參閱 SDK 中的命令。

# Summary instructions

When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them

​

保持上下文高效

• 為子任務使用子代理程式。 每個子代理程式以新鮮的對話開始（沒有先前的訊息歷史記錄，儘管它確實加載自己的系統提示和專案級上下文，如 CLAUDE.md）。它看不到父級的回合，只有其最終回應作為工具結果返回給父級。主代理程式的上下文增長該摘要，而不是完整的子任務成績單。請參閱 子代理程式繼承什麼 以了解詳細資訊。
• 選擇性地使用工具。 每個工具定義都佔用上下文空間。在 AgentDefinition 上使用 tools 欄位將子代理程式限制在它們需要的最小集合。
• 監視 MCP 伺服器成本。 MCP 工具搜尋 預設延遲 MCP 工具架構，並按需加載它們。當工具搜尋關閉、在 Vertex AI 上或在非第一方 ANTHROPIC_BASE_URL 後面時，每個 MCP 伺服器將其所有工具架構添加到每個請求，因此具有許多工具的幾個伺服器可以在代理程式執行任何工作之前消耗大量上下文。
• 為常規任務使用較低的努力。 為僅需要讀取檔案或列出目錄的代理程式設定 努力 為 "low"。這會減少代幣使用量和成本。

​

工作階段和連續性

​

處理結果

​

Hooks

​

將其全部整合在一起

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    async for message in query(
        prompt="Find and fix the bug causing test failures in the auth module",
        options=ClaudeAgentOptions(
            allowed_tools=[
                "Read",
                "Edit",
                "Bash",
                "Glob",
                "Grep",
            ],  # Listing tools here auto-approves them (no prompting)
            setting_sources=[
                "project"
            ],  # Load CLAUDE.md, skills, hooks from current directory
            max_turns=30,  # Prevent runaway sessions
            effort="high",  # Thorough reasoning for complex debugging
        ),
    ):
        # Handle the final result
        if isinstance(message, ResultMessage):
            session_id = message.session_id  # Save for potential resumption

            if message.subtype == "success":
                print(f"Done: {message.result}")
            elif message.subtype == "error_max_turns":
                # Agent ran out of turns. Resume with a higher limit.
                print(f"Hit turn limit. Resume session {session_id} to continue.")
            elif message.subtype == "error_max_budget_usd":
                print("Hit budget limit.")
            else:
                print(f"Stopped: {message.subtype}")
            if message.total_cost_usd is not None:
                print(f"Cost: ${message.total_cost_usd:.4f}")


asyncio.run(run_agent())

​

後續步驟

• 還沒有執行代理程式？ 從 快速入門 開始，以安裝 SDK 並查看完整範例端到端執行。
• 準備好連接到您的專案？ 加載 CLAUDE.md、技能和檔案系統 hooks，以便代理程式自動遵循您的專案約定。
• 建立互動式 UI？ 啟用 串流 以在迴圈執行時顯示即時文字和工具呼叫。
• 需要對代理程式可以做什麼進行更嚴格的控制？ 使用 權限 鎖定工具存取，並使用 hooks 在工具執行前審計、阻止或轉換工具呼叫。
• 執行長期或昂貴的任務？ 將隔離的工作卸載到 子代理程式 以保持主上下文精簡。