現(xiàn)的循環(huán)骨架)
1. 從一次“跑不完”的 Agent 說起很多人第一次接觸 Claude Agent SDK都會寫出一段看起來沒問題的代碼給個 prompt開幾個工具然后for await消費(fèi)消息流。結(jié)果要么卡住不動要么跑了幾十輪還在改同一個文件要么直接報error_max_turns退出。問題往往不在模型而在于沒搞清楚 Agent Loop 到底是怎么轉(zhuǎn)起來的。Agent Loop 說白了就是一個“評估—行動—再評估”的循環(huán)Claude 看當(dāng)前狀態(tài)決定調(diào)哪個工具SDK 執(zhí)行工具把結(jié)果塞回去Claude 再評估直到它覺得不需要工具了循環(huán)結(jié)束。Claude Agent SDK 把 Claude Code 內(nèi)部那套循環(huán)完整開放出來你拿到的不是黑盒而是一個可以自己控制輪次、預(yù)算、工具權(quán)限的骨架。這篇面向想從零理解循環(huán)驅(qū)動 Agent 的開發(fā)者聚焦最小可運(yùn)行結(jié)構(gòu)。我會給出settings.json與 SDK 初始化配置骨架再附一次本地循環(huán)調(diào)用的驗(yàn)證步驟幫你在 TaoToken 統(tǒng)一 Key/API 通道下跑通第一個 Agent 循環(huán)。全程可跟做不需要你先啃完官方文檔。2. TaoToken 前置把 Key 和通道準(zhǔn)備好Agent SDK 本身不綁定某一家通道它需要一個兼容 Anthropic 接口的入口。TaoToken 在這里的角色是統(tǒng)一 Key/API 通道你申請一個 Key就能在模型對話、Coding Plan、API 調(diào)用之間復(fù)用同一套憑證不用為每個工具單獨(dú)配一遍。先做三件事第一拿到 Key。登錄 TaoToken 控制臺在 API Keys 頁面創(chuàng)建一個新 Key復(fù)制保存。這個 Key 后面會寫進(jìn)環(huán)境變量不要硬編碼進(jìn)代碼。第二確認(rèn)接入地址。API 端點(diǎn)是https://taotoken.net/apiSDK 初始化時通過baseURL指向它。注意這里不加任何查詢參數(shù)保持干凈。第三想清楚你要跑哪種循環(huán)。如果只是驗(yàn)證模型能不能正常對話用模型對話入口就夠如果是長期編碼、跑 Agent 任務(wù)建議走 Coding Plan配額和穩(wěn)定性更適合持續(xù)循環(huán)。提示Key 只顯示一次創(chuàng)建后立刻存到密碼管理器或本地.env。后面所有配置都從環(huán)境變量讀避免泄露。環(huán)境變量這樣設(shè)Linux/macOSexport ANTHROPIC_API_KEY你的_taotoken_key export ANTHROPIC_BASE_URLhttps://taotoken.net/apiWindows PowerShell$env:ANTHROPIC_API_KEY你的_taotoken_key $env:ANTHROPIC_BASE_URLhttps://taotoken.net/api這兩行是整個循環(huán)的“供電”。SDK 啟動時會讀它們把請求發(fā)到 TaoToken 通道再由通道轉(zhuǎn)發(fā)到模型。你不需要改 SDK 源碼也不需要額外裝代理層。3. 可復(fù)制配置settings.json 與 SDK 初始化骨架3.1 settings.json 最小骨架Claude Agent SDK 支持從settings.json讀取默認(rèn)配置放在項目根目錄或.claude/下。最小可用版本長這樣{ permissions: { allow: [ Read, Glob, Grep ], deny: [ Bash(rm -rf *), Bash(curl *) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api } }這里做了兩件事allow列出 Agent 可以用的工具deny擋住危險命令。第一次跑循環(huán)建議只開只讀工具確認(rèn)流程通了再逐步放開Edit和Bash。env里把 baseURL 固化省得每次手動 export。3.2 SDK 初始化配置骨架下面是 TypeScript 版的最小初始化。先裝依賴npm init -y npm install anthropic-ai/claude-agent-sdk然后寫agent-loop.tsimport { query } from anthropic-ai/claude-agent-sdk; async function main() { const stream query({ prompt: 列出當(dāng)前目錄下所有 .ts 文件并統(tǒng)計每個文件的行數(shù)。, options: { allowedTools: [Glob, Read, Bash], permissionMode: acceptEdits, maxTurns: 8, maxBudgetUsd: 0.30, systemPrompt: 你是一個只讀分析助手。只做統(tǒng)計和匯報不修改任何文件。, }, }); for await (const message of stream) { if (message.type system) { if (session_id in message) { console.log([session] ${message.session_id}); } } else if (message.type assistant) { for (const block of message.message.content) { if (text in block) { console.log([text] ${block.text}); } else if (name in block) { console.log([tool] ${block.name}); } } } else if (message.type result) { console.log([done] ${message.subtype}); console.log([cost] $${message.total_cost_usd.toFixed(4)}); console.log([turns] ${message.num_turns}); } } } main().catch(console.error);幾個關(guān)鍵參數(shù)解釋一下。allowedTools決定 Agent 的手腳范圍這里給了Glob找文件、Read讀內(nèi)容、Bash跑wc -l統(tǒng)計行數(shù)。permissionMode: acceptEdits讓文件編輯自動通過但因?yàn)槲覀儧]開Edit實(shí)際改不了文件。maxTurns: 8是硬護(hù)欄防止循環(huán)失控。maxBudgetUsd: 0.30是花費(fèi)上限命中后循環(huán)立即終止并返回error_max_budget_usd。注意message.message.content多了一層.message包裝不是message.content。這是第一次寫最容易踩的坑后面排障章節(jié)會再強(qiáng)調(diào)。3.3 用環(huán)境變量注入 Key不要把 Key 寫進(jìn)代碼。在項目根目錄建.envANTHROPIC_API_KEY你的_taotoken_key ANTHROPIC_BASE_URLhttps://taotoken.net/api用dotenv加載npm install dotenv在agent-loop.ts頂部加一行import dotenv/config;這樣 SDK 啟動時自動讀到 Key 和 baseURL請求走 TaoToken 通道。4. 驗(yàn)證請求跑通第一個循環(huán)4.1 執(zhí)行與預(yù)期輸出在項目目錄下跑npx tsx agent-loop.ts如果一切正常你會看到類似這樣的輸出[session] sess_abc123 [tool] Glob [tool] Bash [text] 當(dāng)前目錄下有 3 個 .ts 文件 - agent-loop.ts: 42 行 - utils.ts: 118 行 - index.ts: 27 行 [done] success [cost] $0.0123 [turns] 3[tool]行說明 Claude 請求了工具調(diào)用SDK 執(zhí)行后把結(jié)果回傳。[turns] 3表示整個任務(wù)用了 3 個包含工具調(diào)用的輪次。[done] success表示循環(huán)正常結(jié)束Claude 產(chǎn)出了不含工具調(diào)用的最終響應(yīng)。4.2 循環(huán)五步對照把上面的輸出對應(yīng)到 Agent Loop 的五步第一步接收 Prompt。SDK 把 prompt、systemPrompt、工具定義打包發(fā)給模型同時產(chǎn)出system消息里面帶session_id。第二步評估并響應(yīng)。Claude 分析任務(wù)決定先調(diào)Glob找文件產(chǎn)出assistant消息內(nèi)容塊里有name: Glob。第三步執(zhí)行工具。SDK 運(yùn)行Glob拿到文件列表回傳給 Claude。第四步循環(huán)。Claude 看到文件列表決定調(diào)Bash跑wc -lSDK 執(zhí)行回傳結(jié)果。這一輪又產(chǎn)生一個 Turn。第五步返回結(jié)果。Claude 拿到行數(shù)產(chǎn)出純文本總結(jié)沒有工具調(diào)用循環(huán)結(jié)束SDK 產(chǎn)出result消息。4.3 換一個任務(wù)驗(yàn)證循環(huán)把 prompt 改成需要多輪的任務(wù)比如prompt: 找出 utils.ts 里所有可能拋異常的函數(shù)逐個說明原因。,這次 Agent 會先Glob找文件再Read讀內(nèi)容可能分多次讀取然后產(chǎn)出分析。觀察[turns]數(shù)字變化你就能直觀感受到循環(huán)在轉(zhuǎn)。5. 本篇常見錯排查5.1 報錯error_max_turns循環(huán)跑到maxTurns上限還沒結(jié)束。常見原因有兩個任務(wù)太開放比如“優(yōu)化整個代碼庫”Agent 會一直改一直跑或者工具結(jié)果太長上下文被塞滿Agent 反復(fù)讀同一個文件。排查方法先把 prompt 收窄明確告訴它改哪個文件、驗(yàn)證標(biāo)準(zhǔn)是什么。再把maxTurns調(diào)大一點(diǎn)同時看[tool]輸出確認(rèn)它是不是在重復(fù)調(diào)同一個工具。如果是說明任務(wù)描述不夠具體。5.2 報錯error_max_budget_usd花費(fèi)命中上限。這通常發(fā)生在長任務(wù)或大文件讀取上。Read一個大文件會消耗大量 tokenBash輸出很長也一樣。排查方法在Bash命令里加| head -50限制輸出用Grep定位后再Read特定行而不是讀整個文件。把maxBudgetUsd適當(dāng)調(diào)高但生產(chǎn)環(huán)境建議保持硬上限。5.3 拿不到message.content如果你寫message.content報 undefined是因?yàn)閍ssistant消息的內(nèi)容在message.message.content。多了一層.message包裝。正確寫法for (const block of message.message.content) { // ... }5.4 工具調(diào)用被拒絕如果看到工具沒執(zhí)行檢查allowedTools是否包含該工具以及permissions.deny是否擋住了它。settings.json里的deny優(yōu)先級高于allow。另外permissionMode如果是dontAsk不在allowedTools里的操作會被直接拒絕。5.5 請求發(fā)不出去或 401先確認(rèn)ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL都設(shè)對了。baseURL 應(yīng)該是https://taotoken.net/api不要多加路徑或參數(shù)。Key 如果復(fù)制時帶了空格也會 401。用echo $ANTHROPIC_API_KEY檢查一下。5.6 循環(huán)卡住不動如果for await一直不產(chǎn)出消息可能是網(wǎng)絡(luò)問題或通道超時。先單獨(dú)用模型對話入口驗(yàn)證 Key 是否可用確認(rèn)通道正常后再跑 SDK。如果模型對話正常但 SDK 卡住檢查 SDK 版本是否過舊升級到最新版再試。6. 下一步把循環(huán)用起來跑通第一個循環(huán)后你可以做三件事。第一把a(bǔ)llowedTools逐步放開到Edit和Bash讓 Agent 能真正改代碼、跑測試但記得配deny擋住危險命令。第二用resume或continue接續(xù)會話讓 Agent 在多輪任務(wù)里保持上下文。第三把maxTurns和maxBudgetUsd當(dāng)成生產(chǎn)環(huán)境的默認(rèn)護(hù)欄開放式任務(wù)尤其要設(shè)預(yù)算。如果你要長期跑編碼類 Agent建議走 Coding Plan配額和穩(wěn)定性更適合持續(xù)循環(huán)。需要管理多個 Key 或查看用量去控制臺。想先驗(yàn)證模型對話是否正常用模型對話入口。接入文檔里有完整的參數(shù)說明和更多示例遇到配置問題可以直接查。循環(huán)骨架搭好之后剩下的就是往里面填工具和任務(wù)。Agent Loop 不神秘它就是一個你能看見、能控制、能中斷的循環(huán)。理解它你就理解了 Agent 的心臟。 Agent Loop 拆解：用 Claude Agent SDK 搭一個可復(fù)現(xiàn)的循環(huán)骨架
1. 從一次“跑不完”的 Agent 說起很多人第一次接觸 Claude Agent SDK都會寫出一段看起來沒問題的代碼給個 prompt開幾個工具然后for await消費(fèi)消息流。結(jié)果要么卡住不動要么跑了幾十輪還在改同一個文件要么直接報error_max_turns退出。問題往往不在模型而在于沒搞清楚 Agent Loop 到底是怎么轉(zhuǎn)起來的。Agent Loop 說白了就是一個“評估—行動—再評估”的循環(huán)Claude 看當(dāng)前狀態(tài)決定調(diào)哪個工具SDK 執(zhí)行工具把結(jié)果塞回去Claude 再評估直到它覺得不需要工具了循環(huán)結(jié)束。Claude Agent SDK 把 Claude Code 內(nèi)部那套循環(huán)完整開放出來你拿到的不是黑盒而是一個可以自己控制輪次、預(yù)算、工具權(quán)限的骨架。這篇面向想從零理解循環(huán)驅(qū)動 Agent 的開發(fā)者聚焦最小可運(yùn)行結(jié)構(gòu)。我會給出settings.json與 SDK 初始化配置骨架再附一次本地循環(huán)調(diào)用的驗(yàn)證步驟幫你在 TaoToken 統(tǒng)一 Key/API 通道下跑通第一個 Agent 循環(huán)。全程可跟做不需要你先啃完官方文檔。2. TaoToken 前置把 Key 和通道準(zhǔn)備好Agent SDK 本身不綁定某一家通道它需要一個兼容 Anthropic 接口的入口。TaoToken 在這里的角色是統(tǒng)一 Key/API 通道你申請一個 Key就能在模型對話、Coding Plan、API 調(diào)用之間復(fù)用同一套憑證不用為每個工具單獨(dú)配一遍。先做三件事第一拿到 Key。登錄 TaoToken 控制臺在 API Keys 頁面創(chuàng)建一個新 Key復(fù)制保存。這個 Key 后面會寫進(jìn)環(huán)境變量不要硬編碼進(jìn)代碼。第二確認(rèn)接入地址。API 端點(diǎn)是https://taotoken.net/apiSDK 初始化時通過baseURL指向它。注意這里不加任何查詢參數(shù)保持干凈。第三想清楚你要跑哪種循環(huán)。如果只是驗(yàn)證模型能不能正常對話用模型對話入口就夠如果是長期編碼、跑 Agent 任務(wù)建議走 Coding Plan配額和穩(wěn)定性更適合持續(xù)循環(huán)。提示Key 只顯示一次創(chuàng)建后立刻存到密碼管理器或本地.env。后面所有配置都從環(huán)境變量讀避免泄露。環(huán)境變量這樣設(shè)Linux/macOSexport ANTHROPIC_API_KEY你的_taotoken_key export ANTHROPIC_BASE_URLhttps://taotoken.net/apiWindows PowerShell$env:ANTHROPIC_API_KEY你的_taotoken_key $env:ANTHROPIC_BASE_URLhttps://taotoken.net/api這兩行是整個循環(huán)的“供電”。SDK 啟動時會讀它們把請求發(fā)到 TaoToken 通道再由通道轉(zhuǎn)發(fā)到模型。你不需要改 SDK 源碼也不需要額外裝代理層。3. 可復(fù)制配置settings.json 與 SDK 初始化骨架3.1 settings.json 最小骨架Claude Agent SDK 支持從settings.json讀取默認(rèn)配置放在項目根目錄或.claude/下。最小可用版本長這樣{ permissions: { allow: [ Read, Glob, Grep ], deny: [ Bash(rm -rf *), Bash(curl *) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api } }這里做了兩件事allow列出 Agent 可以用的工具deny擋住危險命令。第一次跑循環(huán)建議只開只讀工具確認(rèn)流程通了再逐步放開Edit和Bash。env里把 baseURL 固化省得每次手動 export。3.2 SDK 初始化配置骨架下面是 TypeScript 版的最小初始化。先裝依賴npm init -y npm install anthropic-ai/claude-agent-sdk然后寫agent-loop.tsimport { query } from anthropic-ai/claude-agent-sdk; async function main() { const stream query({ prompt: 列出當(dāng)前目錄下所有 .ts 文件并統(tǒng)計每個文件的行數(shù)。, options: { allowedTools: [Glob, Read, Bash], permissionMode: acceptEdits, maxTurns: 8, maxBudgetUsd: 0.30, systemPrompt: 你是一個只讀分析助手。只做統(tǒng)計和匯報不修改任何文件。, }, }); for await (const message of stream) { if (message.type system) { if (session_id in message) { console.log([session] ${message.session_id}); } } else if (message.type assistant) { for (const block of message.message.content) { if (text in block) { console.log([text] ${block.text}); } else if (name in block) { console.log([tool] ${block.name}); } } } else if (message.type result) { console.log([done] ${message.subtype}); console.log([cost] $${message.total_cost_usd.toFixed(4)}); console.log([turns] ${message.num_turns}); } } } main().catch(console.error);幾個關(guān)鍵參數(shù)解釋一下。allowedTools決定 Agent 的手腳范圍這里給了Glob找文件、Read讀內(nèi)容、Bash跑wc -l統(tǒng)計行數(shù)。permissionMode: acceptEdits讓文件編輯自動通過但因?yàn)槲覀儧]開Edit實(shí)際改不了文件。maxTurns: 8是硬護(hù)欄防止循環(huán)失控。maxBudgetUsd: 0.30是花費(fèi)上限命中后循環(huán)立即終止并返回error_max_budget_usd。注意message.message.content多了一層.message包裝不是message.content。這是第一次寫最容易踩的坑后面排障章節(jié)會再強(qiáng)調(diào)。3.3 用環(huán)境變量注入 Key不要把 Key 寫進(jìn)代碼。在項目根目錄建.envANTHROPIC_API_KEY你的_taotoken_key ANTHROPIC_BASE_URLhttps://taotoken.net/api用dotenv加載npm install dotenv在agent-loop.ts頂部加一行import dotenv/config;這樣 SDK 啟動時自動讀到 Key 和 baseURL請求走 TaoToken 通道。4. 驗(yàn)證請求跑通第一個循環(huán)4.1 執(zhí)行與預(yù)期輸出在項目目錄下跑npx tsx agent-loop.ts如果一切正常你會看到類似這樣的輸出[session] sess_abc123 [tool] Glob [tool] Bash [text] 當(dāng)前目錄下有 3 個 .ts 文件 - agent-loop.ts: 42 行 - utils.ts: 118 行 - index.ts: 27 行 [done] success [cost] $0.0123 [turns] 3[tool]行說明 Claude 請求了工具調(diào)用SDK 執(zhí)行后把結(jié)果回傳。[turns] 3表示整個任務(wù)用了 3 個包含工具調(diào)用的輪次。[done] success表示循環(huán)正常結(jié)束Claude 產(chǎn)出了不含工具調(diào)用的最終響應(yīng)。4.2 循環(huán)五步對照把上面的輸出對應(yīng)到 Agent Loop 的五步第一步接收 Prompt。SDK 把 prompt、systemPrompt、工具定義打包發(fā)給模型同時產(chǎn)出system消息里面帶session_id。第二步評估并響應(yīng)。Claude 分析任務(wù)決定先調(diào)Glob找文件產(chǎn)出assistant消息內(nèi)容塊里有name: Glob。第三步執(zhí)行工具。SDK 運(yùn)行Glob拿到文件列表回傳給 Claude。第四步循環(huán)。Claude 看到文件列表決定調(diào)Bash跑wc -lSDK 執(zhí)行回傳結(jié)果。這一輪又產(chǎn)生一個 Turn。第五步返回結(jié)果。Claude 拿到行數(shù)產(chǎn)出純文本總結(jié)沒有工具調(diào)用循環(huán)結(jié)束SDK 產(chǎn)出result消息。4.3 換一個任務(wù)驗(yàn)證循環(huán)把 prompt 改成需要多輪的任務(wù)比如prompt: 找出 utils.ts 里所有可能拋異常的函數(shù)逐個說明原因。,這次 Agent 會先Glob找文件再Read讀內(nèi)容可能分多次讀取然后產(chǎn)出分析。觀察[turns]數(shù)字變化你就能直觀感受到循環(huán)在轉(zhuǎn)。5. 本篇常見錯排查5.1 報錯error_max_turns循環(huán)跑到maxTurns上限還沒結(jié)束。常見原因有兩個任務(wù)太開放比如“優(yōu)化整個代碼庫”Agent 會一直改一直跑或者工具結(jié)果太長上下文被塞滿Agent 反復(fù)讀同一個文件。排查方法先把 prompt 收窄明確告訴它改哪個文件、驗(yàn)證標(biāo)準(zhǔn)是什么。再把maxTurns調(diào)大一點(diǎn)同時看[tool]輸出確認(rèn)它是不是在重復(fù)調(diào)同一個工具。如果是說明任務(wù)描述不夠具體。5.2 報錯error_max_budget_usd花費(fèi)命中上限。這通常發(fā)生在長任務(wù)或大文件讀取上。Read一個大文件會消耗大量 tokenBash輸出很長也一樣。排查方法在Bash命令里加| head -50限制輸出用Grep定位后再Read特定行而不是讀整個文件。把maxBudgetUsd適當(dāng)調(diào)高但生產(chǎn)環(huán)境建議保持硬上限。5.3 拿不到message.content如果你寫message.content報 undefined是因?yàn)閍ssistant消息的內(nèi)容在message.message.content。多了一層.message包裝。正確寫法for (const block of message.message.content) { // ... }5.4 工具調(diào)用被拒絕如果看到工具沒執(zhí)行檢查allowedTools是否包含該工具以及permissions.deny是否擋住了它。settings.json里的deny優(yōu)先級高于allow。另外permissionMode如果是dontAsk不在allowedTools里的操作會被直接拒絕。5.5 請求發(fā)不出去或 401先確認(rèn)ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL都設(shè)對了。baseURL 應(yīng)該是https://taotoken.net/api不要多加路徑或參數(shù)。Key 如果復(fù)制時帶了空格也會 401。用echo $ANTHROPIC_API_KEY檢查一下。5.6 循環(huán)卡住不動如果for await一直不產(chǎn)出消息可能是網(wǎng)絡(luò)問題或通道超時。先單獨(dú)用模型對話入口驗(yàn)證 Key 是否可用確認(rèn)通道正常后再跑 SDK。如果模型對話正常但 SDK 卡住檢查 SDK 版本是否過舊升級到最新版再試。6. 下一步把循環(huán)用起來跑通第一個循環(huán)后你可以做三件事。第一把a(bǔ)llowedTools逐步放開到Edit和Bash讓 Agent 能真正改代碼、跑測試但記得配deny擋住危險命令。第二用resume或continue接續(xù)會話讓 Agent 在多輪任務(wù)里保持上下文。第三把maxTurns和maxBudgetUsd當(dāng)成生產(chǎn)環(huán)境的默認(rèn)護(hù)欄開放式任務(wù)尤其要設(shè)預(yù)算。如果你要長期跑編碼類 Agent建議走 Coding Plan配額和穩(wěn)定性更適合持續(xù)循環(huán)。需要管理多個 Key 或查看用量去控制臺。想先驗(yàn)證模型對話是否正常用模型對話入口。接入文檔里有完整的參數(shù)說明和更多示例遇到配置問題可以直接查。循環(huán)骨架搭好之后剩下的就是往里面填工具和任務(wù)。Agent Loop 不神秘它就是一個你能看見、能控制、能中斷的循環(huán)。理解它你就理解了 Agent 的心臟。