代理程式迴圈如何運作

​

迴圈概覽

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"：執行的工作階段中繼資料。當 SessionStart 或 Setup hook 在工作階段啟動期間執行時，其 hook 生命週期訊息 會在 init 訊息之前到達
  • "compact_boundary"：在 壓縮 後觸發
  • "informational"：來自迴圈的純文字狀態橫幅
  • "worker_shutting_down"：主機正在退出或遠端控制已斷開連線
  在 TypeScript 中，除了 "init" 之外的每個子類型都是 SDKMessage 聯合 中的自己的類型，而不是 SDKSystemMessage 的子類型。
• AssistantMessage： 在 Claude 回應的每個內容區塊後發出，包括最終純文字區塊。每個訊息都帶有單一內容區塊，例如文字或工具呼叫，來自一個回應的訊息共享一個訊息 ID。
• 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。

import asyncio
from claude_agent_sdk import query, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, AssistantMessage):
                # Each AssistantMessage carries one content block
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")
                    elif isinstance(block, ToolUseBlock):
                        print(f"Tool call: {block.name}")
            if isinstance(message, ResultMessage):
                if message.subtype == "success":
                    print(message.result)
                else:
                    print(f"Stopped: {message.subtype}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the error subtype branches above have
        # already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant") {
      // Each assistant message carries one content block
      for (const block of message.message.content) {
        if (block.type === "text") {
          console.log(`Claude: ${block.text}`);
        } else if (block.type === "tool_use") {
          console.log(`Tool call: ${block.name}`);
        }
      }
    }
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(message.result);
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

​

工具執行

​

內建工具

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

​

工具權限

• allowed_tools / allowedTools 自動核准列出的工具。允許工具清單中包含 ["Read", "Glob", "Grep"] 的唯讀 agent 會執行這些工具而不提示，但從網路路徑進行的讀取除外。未列出的工具仍然可用，對它們的呼叫若需要核准，會交由權限模式和 canUseTool 處理。
• disallowed_tools / disallowedTools 阻止列出的工具，無論其他設定如何。請參閱 權限 以了解在工具執行前檢查規則的順序。
• permission_mode / permissionMode 控制您想要多少人工監督。SDK 根據固定順序評估活動模式以及您的允許和拒絕規則，詳見權限如何被評估。請參閱權限模式以了解可用的模式。

​

平行工具執行

​

控制迴圈如何執行

​

回合和預算

​

預算餘裕

​

努力等級

​

權限模式

​

模型

​

上下文視窗

​

什麼消耗上下文

​

自動壓縮

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

​

保持上下文高效

• 為子任務使用 subagent。 每個 subagent 以全新的對話開始（沒有先前的訊息歷史記錄，儘管它確實載入自己的系統提示詞和專案級上下文，如 CLAUDE.md）。它看不到父級的回合，只有其最終回應會返回給父級。主 agent 的上下文只增加該摘要，而不是完整的子任務逐字稿。請參閱 subagent 繼承什麼 以了解詳細資訊。
• 選擇性地使用工具。 每個工具定義都佔用上下文空間。在 AgentDefinition 上使用 tools 欄位將子代理程式限制在它們需要的最小集合。