自主任務執行的 Agentic Loop

Agentic loop 是每個自主 Claude 系統的執行心跳。Claude Certified Architect — Foundations（CCA-F）考試任務說明 1.1——「設計並實作用於自主任務執行的 agentic loop」——之所以居於 Domain 1（佔比 27%）的核心位置，是有原因的：考試中 Domain 1 的所有其他 orchestration 模式——從 coordinator-subagent 的扇出架構、session forking 到多步驟交接——都是建構在一個正確設計的 agentic loop 之上的結構性延伸。若你對 loop 的基本原語（primitive）理解有誤，Domain 1 的其餘部分也會跟著偏差。

這份學習筆記涵蓋 CCA-F 考生需要在架構層級設計的 agentic loop 完整面向：感知-推理-行動-觀察循環、stop_reason 欄位的精確語義、必須能夠一眼辨認的四個 stop_reason 值、防止迴圈失控的安全終止條件、tool_result 注入的資料結構、對話歷史成長的管理、循序執行與並行工具呼叫、Agent SDK 的三個迴圈進入點（run、stream、process）、迴圈內部的錯誤處理分支，以及生產等級的可觀測性設計。最後的考試陷阱章節與六題 FAQ，將每個抽象概念連回四個練習 agentic loop 的考試情境：customer-support-resolution-agent、code-generation-with-claude-code、developer-productivity-with-claude，以及 multi-agent-research-system。

什麼是 Agentic Loop？感知、推理、行動、觀察

Agentic loop 是一種受控的多輪互動模式：Claude 在提出 tool_use 與接收 tool_result 之間交替迭代，直到滿足終止條件為止。沒有 agentic loop，Claude 只是文字補全；有了它，Claude 才是 agent。

迴圈是明確的（explicit）——驅動 Claude 的 while 迴圈由你的程式碼跑，這跟傳統聊天機器人「每次回應後對話就結束」本質不同。Agentic loop 持續執行，直到 Claude 發出 end_turn、你的 guardrail 切斷、或觸及硬性限制為止。

為什麼 CCA-F 把 Agentic Loop 放在第一位

考試指南將任務 1.1 列為 Domain 1 的基礎，是因為所有後續任務說明（1.2 coordinator-subagent、1.3 spawning、1.4 handoff、1.5 hook、1.6 任務分解、1.7 session 狀態）都預設你已經理解 Claude 在 tool_use 和 end_turn 之間做了什麼。社群通過考試的報告反覆指出「忽略 stop_reason 訊號」是前五大錯誤之一——這種錯誤在考試當天會悄悄損失兩到三道計分題。

Agentic Loop 與單次推論的比較 — 何時選擇哪種架構

並非每次 Claude 呼叫都需要迴圈。生產環境中有很大比例的 Claude 用法仍是單次：分類這段文字、摘要這份文件、起草這封電子郵件。在只需單次呼叫的情況下選擇迴圈，只會多增加延遲、成本和失敗模式，毫無好處；反過來，在需要迴圈時選擇單次呼叫，則保證任務無法完成。

單次推論（Single-Turn Inference）

一問一答的形狀。任務可以用 prompt 中現有資訊完成、沒有外部狀態要查、輸出結構事先已知（散文、JSON、分類標籤）就用它。

Agentic Loop

當任務有認識論上的不確定性——Claude 訊息當下無法知道完整答案，必須取得資訊或採取行動才能推進——就要用迴圈。讀檔案、查資料庫、呼叫 API，以及任何步驟數量無法事先預測的開放式任務（修這個 bug、解這張票）都屬此類。

決策捷思法

把工具從設計中拿掉，Claude 仍能完成任務 → 不需要迴圈。拿掉之後任務不可能完成 → 需要迴圈。

stop_reason 欄位 — 區分 tool_use 與 end_turn

每次 Claude 回應上的 stop_reason 欄位是驅動迴圈的訊號。Agentic loop 在架構上就是一個對 stop_reason 的 switch 陳述式。誤讀這個欄位，是 CCA-F 社群題庫中 Domain 1 出現頻率最高的陷阱。

Switch 陳述式心理模型

while true:
    response = claude.messages.create(messages=history, tools=tools, ...)
    history.append(response)

    if response.stop_reason == "tool_use":
        tool_results = execute_tools(response.content)
        history.append({"role": "user", "content": tool_results})
        continue   # 繼續迭代
    elif response.stop_reason == "end_turn":
        break      # Claude 表示已完成
    elif response.stop_reason == "max_tokens":
        handle_truncation(response)
        break      # 或決定以後續訊息繼續
    elif response.stop_reason == "stop_sequence":
        break      # 設定的停止字串匹配；視為終止

這個骨架值得背下來。大多數真實的 CCA-F agentic loop 題目，測的都是你能否為給定的 stop_reason 值選出正確的分支行為。

tool_use — 繼續迴圈

當 stop_reason == "tool_use" 時，Claude 的訊息內容包含一個或多個 tool_use 區塊。每個區塊帶有 name、id 和 input 物件。你的迴圈必須：

1. 執行每個 tool_use 區塊（你的客戶端程式碼執行工具，或 Anthropic 平台執行伺服器端工具）。
2. 將每個結果封裝為帶有對應 tool_use_id 的 tool_result 區塊。
3. 將一條新的 user 訊息附加到歷史記錄，其 content 為 tool_result 區塊的陣列。
4. 再次呼叫 Messages API。

看到 tool_use 不代表迴圈結束。恰恰相反，tool_use 是唯一強制要求繼續的 stop_reason。

end_turn — 終止迴圈

當 stop_reason == "end_turn" 時，Claude 在告訴你它已完成當前任務的工作，不再有工具呼叫要發出。最後的 assistant 訊息包含呈現給使用者的答案。end_turn 是 agentic loop 的正常終止路徑（happy path）。

stop_reason 值完整目錄 — tool_use、end_turn、max_tokens、stop_sequence

CCA-F 要求你認識四個 stop_reason 值，並知道每個值對應的正確迴圈反應。

tool_use

Claude 產生一個或多個 tool_use 區塊。附加對應的 tool_result 區塊後，迴圈繼續。

end_turn

Claude 決定完成。退出迴圈，最後的 assistant 訊息就是答案。

max_tokens

Claude 觸及設定的 max_tokens 上限，訊息被截斷——可能截在句中或 tool_use 中間。不是正常完成：表示輸出預算對這個任務太小。提高 max_tokens 重試、加一條「請繼續」user 訊息、或視為失敗升級處理。

stop_sequence

Claude 的生成匹配 stop_sequences 中的字串。常見於結構化輸出工作流程，你預先要求 Claude 在已知分隔符停止。對該步驟是終止；更高層 agentic loop 仍可能繼續。

迴圈終止條件 — 設計安全退出準則以避免無限迴圈

end_turn 是 Claude 的自我宣告終止訊號，但生產等級的 agentic loop 不能只依賴 Claude 的判斷。你需要設計守衛條件作為縱深防禦。

每個生產迴圈都應實作的五個終止守衛

1. 迭代上限 — 迴圈輪次的硬性最大值（例如 20 輪）。沒有這個守衛的迴圈，偶爾會永遠跑下去。
2. 掛鐘超時（Wall-clock timeout） — 整個迴圈的最大經過時間。
3. Token 預算 — 所有輪次累計的輸入加輸出 token 數，上限為業務定義的值。
4. 重複狀態偵測 — 若 Claude 連續三次以相同 input 發出相同的 tool_use，代表迴圈卡住了；中止。
5. 人工升級觸發 — 迴圈主動將控制權交回人類的條件（低置信度、敏感操作、超出範疇的請求）。

為什麼安全退出很重要

Claude 被訓練成樂於助人且有韌性。任務模糊或工具回傳無益錯誤時，Claude 會持續嘗試新的工具呼叫——在 CI/CD 中沒有上限的迴圈可以一夜燒光 API 預算，沒有重複狀態偵測的迴圈會在兩個等效呼叫之間震盪直到 token 耗盡。

Tool Result 注入 — 以 tool_result 訊息回饋觀察結果

每次迴圈迭代的觀察階段，在機械上實作為附加一條新的 user 訊息，其 content 是一個 tool_result 區塊的陣列。訊息格式錯誤是考試中常見的實作層級陷阱。

tool_result 區塊的資料結構

每個 tool_result 區塊包含：

• type: "tool_result"
• tool_use_id — 對應前一條 assistant 訊息中對應 tool_use 區塊的 id。
• content — 代表工具輸出的字串或內容區塊陣列（文字、圖像）。
• is_error — 可選布林值；true 表示工具呼叫以 Claude 應當回應的方式失敗了。

一條 user 訊息，多個 tool_result 區塊

當 Claude 在單一 assistant 訊息中發出多個 tool_use 區塊（並行工具呼叫）時，你的下一條 user 訊息必須在同一條訊息中包含所有對應的 tool_result 區塊——每個未回應的 tool_use_id 對應一個區塊。逐一發送或與新的使用者文字交錯，都會違反 API 合約。

錯誤作為結構化訊號

當工具失敗時，回傳 is_error: true，並在 content 中附上簡潔、可行動的錯誤字串。這告訴 Claude 工具呼叫未成功，並給它足夠的上下文來決定是否重試、切換到替代工具，或升級處理。結構化錯誤回應（在 content 中包含明確的 errorCategory 和 isRetryable 欄位）是 Domain 2 的模式，但它們的消耗發生在 agentic loop 的錯誤處理分支內。

對話歷史成長 — 管理跨迴圈迭代累積的上下文

每次迴圈迭代至少附加兩條訊息到對話歷史（assistant 輪次與 user tool_result 輪次）。長時間執行的 agentic loop 因此會累積大量上下文——一個 30 輪迭代、帶有中等工具輸出的迴圈，輕易就能填滿數萬個 token。

歷史增長帶來的三種壓力

1. 成本 — 每次後續的 API 呼叫，都要在新生成之上，為完整歷史支付輸入 token 的費用。
2. 延遲 — 輸入處理時間隨上下文長度成比例增加。
3. 注意力退化 — 超過一定規模後，Claude 會出現「迷失在中間」效應，中段上下文的資訊受到的加權少於首尾內容。

迴圈內部的緩解策略

• 修剪冗長的工具輸出 — 若工具回傳一份五萬 token 的文件，在存入歷史前先摘要或擷取關鍵內容。
• 清除已過時的 tool result — 較新的工具結果往往會取代較舊的；上下文編輯功能（Claude 4 的 beta 功能）可以刪除廢棄的結果。
• 使用 subagent — 將高 token 消耗的子任務委派給擁有獨立隔離上下文的 subagent（涵蓋於任務 1.2 / 1.3）。
• 壓縮 / 交接（Compaction / handoff） — 在某個檢查點，將迄今為止的迴圈摘要為結構化的狀態 blob，並開始新的 session。

這些技術在上下文管理主題（Domain 5）中有深入說明，但 agentic loop 的架構師必須知道它們的存在，以及何時使用。

迴圈中的並行性 — 循序工具呼叫 vs 並行扇出執行

當 Claude 在單一 assistant 訊息中發出多個 tool_use 區塊時，你有兩種執行選擇。

循序 vs 並行

循序——逐一執行工具，等前一個完成才開始下一個。當工具 A 的輸出餵給工具 B 時，必用此法。

並行——同時跑所有工具呼叫。當呼叫彼此獨立（不同檔案、不同 DB 查詢、不同搜尋詞）時就用這個。

架構層面的含義

迴圈不是「每輪一個工具」。單一 assistant 輪次可能含 N 個 tool_use 區塊，對應的 user 輪次必須含 N 個匹配的 tool_result。現代 Claude 在能判斷獨立性時積極並行化，所以把並行呼叫串列成 N 輪會浪費圖 5 中明顯可見的延遲節省。

Agent SDK 迴圈原語 — run()、stream() 與 process() 進入點

Claude Agent SDK（前身為 Claude Code SDK）提供自動化的 agentic loop，讓你不必每次都手寫 switch 陳述式。CCA-F 要求認識三個進入點以及各自的使用時機。

run() — 阻塞式全迴圈

從頭到尾跑完整迴圈，回傳最終結果。同步「給我答案」形狀。適合腳本任務、批次工作、短暫整合。

stream() — 增量事件串流

在迴圈推進時 yield 事件——assistant 文字片段、tool_use 提案、tool_result 附加、迭代邊界。需要渲染部分輸出（聊天 UI）、對中途決策埋點、或 agent 工作中即時更新 UI 時用。

process() — 低階程式化控制

逐訊息 hook、任意狀態轉換、自訂 loop 形狀（例如輪次之間暫停等外部核准）。run() 和 stream() 表達不了你的設計時才用。

自動化 vs 手動

SDK 的自動化迴圈幫你處理 switch、tool_result 建構、終止守衛。代價是降低每輪決策可見性、對非常規架構不夠靈活。大部分生產系統用 run() 或 stream()；直接對 Messages API 手寫迴圈通常出現在自訂多 agent orchestrator——只在需要 SDK 隱藏掉的細粒度控制時才這麼做。

迴圈內部的錯誤處理 — 工具失敗時的重試、跳過或中止

在生產環境中，工具呼叫持續失敗：網路抖動、速率限制、過期憑證、工具輸入的邏輯錯誤。設計良好的 agentic loop 對每次工具失敗都有三種回應選項。

重試（Retry）

回傳帶有 is_error: true 的 tool_result，並附上表示錯誤是暫時性的訊息（例如：「網路超時——1 秒後重試」）。Claude 通常會重新發出相同或略作調整的 tool_use。當底層條件預期會自行解決時，重試是合適的。

跳過（Skip）

回傳帶有 is_error: true 的 tool_result，並附上表示該特定請求無法完成、但替代方案可能有效的訊息。Claude 接著會嘗試不同的方法。跳過適合特定資源的權限錯誤、特定查詢的格式錯誤輸入，或超出範疇的項目。

中止（Abort）

從應用程式端終止迴圈。適合不可恢復的錯誤（身份驗證完全失效、工具後端完全停機、關鍵守衛條件觸發）。

結構化錯誤分類

在每個 is_error: true 的回應中，搭配結構化的分類（transient、business、permission、internal）和 isRetryable 布林值。這在形式上是 Domain 2 的模式，但其消耗發生在 agentic loop 的錯誤處理分支中。通用的錯誤字串會觸發 Claude 進入長時間的重試風暴；結構化錯誤讓 Claude 能做出正確的路由決策。

迴圈可觀測性 — 記錄 tool_use 和 tool_result 以便除錯

Agentic loop 在沒有埋點的情況下，出了名地難以除錯。每位 CCA-F 考生都應知道生產迴圈的最低可觀測性面向。

每次迭代應記錄的內容

• 迭代索引 — 這是迴圈的第幾輪。
• stop_reason — 驅動 switch 陳述式的訊號。
• 每個 tool_use 區塊 — 工具名稱、輸入參數、tool_use_id。
• 每個 tool_result 區塊 — tool_use_id、is_error、截斷的內容預覽、延遲。
• Token 計數 — 每輪的輸入和輸出 token；累計總量。
• 時間 — 每輪的掛鐘時間；累計掛鐘時間。

為什麼這些全都重要

當 agent 在生產環境中行為異常，第一個診斷動作是「Claude 在每個步驟決定做什麼？」tool_use 串流說的就是這個故事。tool_result 串流揭示了環境是否配合。Token 和時間計數揭示了成本和延遲的病徵。沒有這些資料，每次除錯工作都必須從零開始。

PostToolUse 和 PreToolUse Hook

Agent SDK 暴露了 PreToolUse 和 PostToolUse hook，在每次工具執行前後運行。這是附加日誌、指標和策略檢查的乾淨位置。Hook 正式屬於任務 1.5 的主題，但它們的存在是 agentic loop 可觀測性面向的一部分。

白話文解釋

抽象的迴圈機制，一旦錨定在考生已經熟悉的具體情境上，就會變得直觀。以下三個類比涵蓋了 agentic loop 的完整面貌。

類比一：辦桌總鋪師 — 感知、推理、行動、觀察

想像一位正在辦桌場合忙碌的總鋪師。一張菜單進來（感知——「12 桌要上紅蟳米糕和白斬雞」）。總鋪師盤算所需（推理——「紅蟳要蒸，米糕要炊，雞要滷，醬料要拼盤」）。接著同時對各攤位下令（行動——這就是 tool_use 區塊）。片刻後各攤位回報進度、送回食材、反映狀況（觀察——這就是 tool_result 區塊）。總鋪師看看回報的情況，決定這道菜是否完成，還是需要再來一個步驟。整場辦桌宴席就是一個 agentic loop。tool_use 是總鋪師喊「蒸台把紅蟳送上來！」；end_turn 是他拍板「這桌上菜！」；max_tokens 是廚房中途鍋具不夠、被迫停工；stop_sequence 是東家說「晚上十一點前一定要收攤」。總鋪師從不會事先把每一道步驟完整寫下來——他一輪一輪地迭代，觀察每個攤位回傳的狀況。這正是 agentic loop 的形狀。

類比二：刑警偵查 — 認識論上的不確定性驅動迴圈

一名刑警接手案件時，手頭資訊有限——一個受害者、一個地點、一條時間線。他不可能一次就偵破案件，因為他還不知道自己不知道什麼。他追蹤一條線索（訊問目擊者、調閱通聯記錄、勘查現場），觀察回傳的結果，更新假設，再追蹤下一條線索。有時線索走到死路（is_error: true），他改換角度（跳過）。有時電話第一次打不通（暫時性失敗），他再打一次（重試）。調查結束於刑警確信已掌握答案（end_turn），或局長因加班費超支而喊停（迭代上限）。刑警不預先規劃每一個步驟；他根據觀察做反應。Agentic loop 就是一場偵查：Claude 是刑警，工具是偵查動作，你的應用程式是提供預算與規則的警察局。

類比三：導航 App 的路線重算 — 單次推論不足的原因

導航 App 說明了為什麼在世界可能改變時，agentic loop 勝過單次推論。一張紙本地圖（單次推論）在出發時給你一條路線，並假設整段行程不會有任何變化。即時導航 App（agentic loop）則在每個步驟重新計算：觀察你的當前位置（感知），決定下一個轉彎（推理），告訴你轉彎（行動），等待確認你是否真的轉了（觀察）。若塞車，它就重新規劃路線。若你錯過一個交流道，它就自動調整。若你抵達目的地，它說「已到達目的地」（end_turn）。若汽油耗盡（max_tokens），不管地圖多好，它都無法繼續導航。紙本地圖適合沒有不確定性的一次性查詢。即時導航 App——agentic loop——適合現實可能在每個步驟給你帶來驚喜的情況。CCA-F 中帶有驚喜的情境，幾乎總是需要迴圈，而不是單次呼叫。

考試當天選用哪個類比

• 關於四階段循環的題目 → 辦桌總鋪師類比。
• 關於為什麼需要迴圈的題目 → 刑警偵查類比。
• 關於 agentic loop vs 單次推論的題目 → 導航 App 類比。

常見考試陷阱

CCA-F Domain 1 持續利用五種與 agentic loop 相關的反覆出現陷阱模式。全部五種都有社群通過報告記錄在案，並以合理的干擾選項形式出現。

陷阱一：把 end_turn 當成錯誤

end_turn 是 agentic loop 的正確、成功終止——它意味著 Claude 決定任務已完成，沒有更多要做的事。干擾答案將 end_turn 框架為「模型放棄了」或「迴圈失敗了」。兩種框架都是錯的。end_turn 是 happy path。

陷阱二：把 max_tokens 當成正常完成

迴圈中途的 max_tokens 是截斷訊號，不是優雅的完成。回應因輸出預算耗盡而被切斷。把 max_tokens 當成 end_turn——例如將截斷的內容作為最終答案回傳給使用者——會產生損壞的輸出。正確的處理方式是延長預算、請 Claude 繼續，或明確以錯誤中止。

陷阱三：tool_result 上缺少 tool_use_id

每個 tool_result 區塊都必須帶有與原始 tool_use 區塊匹配的 tool_use_id。描述 tool_result 注入但沒有 ID 欄位的答案是錯的。沒有 ID，API 會拒絕這條訊息，或 Claude 會因為看不到上一批呼叫已被回應而重複發出相同的工具呼叫。

陷阱四：生產迴圈沒有迭代上限

只在 end_turn 上終止的迴圈，對失控行為沒有任何防護。Agent 偶爾會卡在重複狀態的循環中，在兩個工具呼叫之間來回震盪，直到 token 耗盡或帳單暴增。每個生產 agentic loop 都必須有明確的迭代上限，加上理想情況下的掛鐘超時。省略上限的答案是不安全的。

陷阱五：run() 夠用時卻選 process()

CCA-F 對過度工程化扣分。批次模式的擷取 agent 應使用 run()，而不是 process()。渲染部分輸出的聊天 UI 應使用 stream()，而不是 process()。process() 是為其他兩者無法表達的架構而設計的——自訂的暫停與恢復、外部核准閘道、新型的多 agent 形態。不問需求就預設選最低階原語，是設計壞味道。

練習錨點

Agentic loop 的概念在六個 CCA-F 情境中的兩個最集中出現。將以下內容視為情境叢集題的架構骨幹。

Customer-Support-Resolution-Agent 情境

在這個情境中，一個客服 agent 接收進入的工單，透過呼叫知識庫查詢工具、CRM 查詢工具和帳戶狀態工具來調查，並自主解決工單或升級給人工處理。Agentic loop 是骨幹：每次工具呼叫觀察不同的系統，而呼叫的順序無法事先規劃，因為它取決於每次查詢回傳的結果。預期會有題目測試你是否正確地在 stop_reason 上做分支，是否用 is_error: true 標記無法連線的後端，以及是否實作了迭代上限加上人工升級觸發。

Developer-Productivity-With-Claude 情境

在這個情境中，一名開發者使用 SDK 驅動的 agent 在大型程式碼庫上執行自主任務——bug 調查、多檔案重構、測試撰寫。Agent 在一個可能延伸至數十輪迭代的長迴圈中呼叫 Read、Grep、Glob、Edit 和 Bash 工具。預期會有題目測試 tool_result 注入的資料結構、訊息歷史管理（何時壓縮、何時 spawn subagent）、並行工具呼叫處理（Claude 會頻繁地扇出讀取多個檔案），以及正確的 SDK 進入點（腳本化批次用 run()，IDE UI 用 stream()）。Multi-agent-research-system 情境也會練習 agentic loop，但主要重心轉移到任務 1.2（coordinator-subagent orchestration）。

FAQ — Agentic Loop 前六大問題

在 Claude 的語境下，agentic loop 究竟是什麼？

Agentic loop 是一個受控的迭代過程：反覆呼叫 Claude Messages API，將工具執行結果以 tool_result 訊息回饋，直到 Claude 回傳 stop_reason: "end_turn"（自然終止）或你的守衛條件觸發（迭代上限、超時、token 預算）。迴圈是單次聊天機器人與自主 agent 之間的結構差異。CCA-F Domain 1 幾乎全部圍繞著把這個迴圈做對，而所有後續的 Domain 1 模式（多 agent orchestration、subagent spawning、handoff）都是建構在它之上的延伸。

tool_use 和 end_turn 作為 stop_reason 值有什麼差異？

tool_use 表示 Claude 提出了一個或多個工具呼叫，正在等待你的應用程式（或平台）執行它們並回傳 tool_result 區塊；迴圈必須繼續。end_turn 表示 Claude 決定任務已完成，不再有進一步的行動要採取；迴圈退出，最後的 assistant 訊息就是答案。混淆這兩個值，是被引用最多的 CCA-F Domain 1 錯誤。正確的迴圈在機械上就是對 stop_reason 的 switch 陳述式：tool_use 繼續，end_turn 終止。

迴圈中途出現 max_tokens 的 stop_reason 該如何處理？

max_tokens 表示 Claude 的回應因觸及輸出預算上限而被截斷。這不是正常完成。三種回應選項：（1）提高 max_tokens 並重試上一次呼叫；（2）附加一條簡短的使用者「請繼續」訊息，讓 Claude 在下一輪完成；（3）若你的業務邏輯無法容忍截斷，以明確的錯誤中止迴圈。把 max_tokens 當成 end_turn——將截斷的內容作為最終答案回傳給使用者——是常見的架構 bug，在 CCA-F 上有直接考題。

何時應使用 Agent SDK 的 run() 而非 stream() 或 process()？

批次、非互動式、腳本化的 agent 執行，你需要單一「給我最終結果」的回傳值時，使用 run()。有人正在觀看且你需要呈現增量輸出時——聊天 UI、即時儀表板、IDE 整合——使用 stream()。只有在其他兩者無法表達你的迴圈形態時，才使用 process()——自訂的暫停與恢復模式、迴圈中途的外部核准閘道、非常規的多 agent orchestration。考試獎勵選擇最符合需求的最簡單原語；出於追求靈活性而預設選 process() 是設計壞味道。

如何防止 agentic loop 永遠跑下去？

至少實作兩個守衛：（1）硬性迭代上限（典型值 15–30 輪），無論 stop_reason 是什麼都強制退出迴圈；（2）從掛鐘超時、累計 token 預算、重複狀態偵測或人工升級觸發清單中再選一個額外守衛。單純依賴 end_turn 是不夠的，因為 Claude 偶爾會卡在等效工具呼叫之間震盪。CCA-F 將「加入迭代上限」視為基準安全要求；即使設計的其他部分無懈可擊，省略它的情境答案也是錯的。

如何在 agentic loop 內部將工具錯誤回饋給 Claude？

回傳 tool_result 區塊，其中 tool_use_id 匹配原始 tool_use，is_error: true，以及在 content 中附上簡潔、可行動的錯誤訊息。理想情況下，錯誤訊息包含結構化的分類（transient、business、permission、internal）和 isRetryable 提示，讓 Claude 能決定是否重試、嘗試替代方案，或升級處理。不帶 is_error: true、以普通字串回傳工具失敗，是最糟糕的反模式——Claude 會將內容視為合法的觀察資料，並可能在憑空捏造的事實上規劃後續行動。

延伸閱讀

• Tool use with Claude — overview and agentic loop: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview
• Agent SDK overview: https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview
• Handle tool calls — tool_result format: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/handle-tool-calls
• Building effective agents — agentic loop reference: https://docs.anthropic.com/en/docs/build-with-claude/agentic-loop
• Writing tools for agents — Anthropic Engineering Blog: https://www.anthropic.com/engineering/writing-tools-for-agents

Related ExamLab topics: Multi-Agent Orchestration with Coordinator-Subagent Patterns, Task Decomposition Strategies, Session State, Resumption, and Forking, Agent SDK Hooks for Tool Call Interception.