用錯一個名字，你的Claude Agent SDK就跑不起來

你從某個技術(shù)博客抄了段代碼，想用Claude Agent SDK搭建一個能自己干活的智能體。結(jié)果運(yùn)行時報錯，找不到包，import失敗。你盯著屏幕上的“ModuleNotFoundError: No module named 'claude-code-sdk'”一頭霧水。不是你寫錯了——是Anthropic自己把名字換了。2025年9月29日，之前叫“Claude Code SDK”的庫正式更名，包名、導(dǎo)入路徑、選項對象全變了。如果你還在用舊的名字，不跑錯才奇怪?，F(xiàn)在TypeScript的正確包名是@anthropic-ai/claude-agent-sdk，Python 3.10以上用claude-agent-sdk，入口叫query()。只要是看到“claude-code-sdk”的代碼片段，直接當(dāng)過期處理。這事沒什么技術(shù)含量，但坑的人不少，原因很簡單：SDK的定位變了，而多數(shù)人還沒意識到它其實不是簡單套殼。

Claude Agent SDK到底是什么？它是驅(qū)動Claude Code本身的引擎，封裝成了Python和TypeScript庫。不是輕量的HTTP包裝，不是Claude Code的仿制品，它就是Claude Code，只是以庫的形式暴露了完整的agent循環(huán)、內(nèi)置工具、權(quán)限系統(tǒng)、子智能體機(jī)制。用這個SDK，你不需要在終端里敲提示詞，而是你的代碼向它描述任務(wù)，SDK負(fù)責(zé)調(diào)度模型、執(zhí)行工具、把結(jié)果流式返回。整個過程里，“誰在驅(qū)動循環(huán)”這個核心問題發(fā)生了轉(zhuǎn)移，而這也正是做技術(shù)選型時要判斷的分水嶺。

想把這件事說明白，最直接的方法是拿它和兩個替代項放在一起比較：原始Messages API和Claude Code CLI。Anthropic還提供了托管的Managed Agent作為第四種形態(tài)，但多數(shù)團(tuán)隊卡在前三項之間的三岔口。三條路指向同一個問題——誰擁有agent循環(huán)的控制權(quán)？

走原始Messages API這條路，循環(huán)是你自己寫的。發(fā)提示，檢查響應(yīng)里有沒有tool_use塊，自己執(zhí)行工具，把結(jié)果追加回去，再調(diào)模型，循環(huán)往復(fù)直到模型不再要工具。示范代碼看起來極其簡單：while response.stop_reason == "tool_use": 執(zhí)行工具，重置消息，再調(diào)client.messages.create。但在真實的生產(chǎn)環(huán)境里，你還得自己處理重試邏輯、上下文窗口管理、對話膨脹時的壓縮、并行工具調(diào)用、錯誤恢復(fù)。每一項都是實打?qū)嵉墓こ袒?。換句話說，這個API給了你完全的自由，也把所有的臟活累活都甩給了你。如果用的場景是單次模型調(diào)用，比如分類、提取，或者你需要一個完全由自己掌控每一步、每一token、每一次工具調(diào)用的自定義循環(huán)，原始API就一定合適。

到了Claude Agent SDK這邊，角色的譜系反轉(zhuǎn)了。輪到Claude來擁有循環(huán)。你的工作從寫循環(huán)變成了定義任務(wù)和邊界。SDK接棒后，所有工具的執(zhí)行、上下文管理、權(quán)限檢查、子智能體的啟動都由它來完成。不需要你一行行地關(guān)心重試和壓縮。這決定了它的主戰(zhàn)場：當(dāng)你需要把智能體能力產(chǎn)品化，或者要讓它在無人值守的環(huán)境里長時間運(yùn)轉(zhuǎn)時，伸手拿SDK就對了。它幫開發(fā)者把“怎么跑”的問題變成了“該做什么”的問題，生產(chǎn)力邊界一下子被推到工具側(cè)。

不過，千萬別把SDK想象成萬金油。有兩大易混淆的點值得單說。第一，它不是那種在Messages API外面糊一層HTTP客戶端的薄封裝，而是一整套智能體具現(xiàn)的套件。這兩者的區(qū)別就像拿到了汽車的鑰匙和坐進(jìn)了一輛自帶司機(jī)的車——駕駛位的歸屬變了。第二，它也不是重新實現(xiàn)了Claude Code，它就是把Claude Code以庫的形式交給你，原汁原味。因此，理解它的本質(zhì)之后，很多奇怪的兼容問題會自然消解，比如為什么不能把原始API的舊的循環(huán)代碼直接扔進(jìn)去用，因為控制權(quán)的交接改變了架構(gòu)的基礎(chǔ)假設(shè)。

回到技術(shù)選型的現(xiàn)實困擾。如果你正處于“用了SDK能不能提高效率”的糾結(jié)期，可以記住一個簡單判斷法：凡是你只能通過終端交互運(yùn)行Claude Code來完成的復(fù)雜任務(wù)，把它搬到后臺自動執(zhí)行，就用SDK；凡是你只想做簡單的問答、信息提取，或者有一個極其特定的工具調(diào)度順序需要全程硬控，就不要上SDK，老老實實擁抱Messages API。這分別對應(yīng)了產(chǎn)品化思路和工程控思路的兩條線。搞反了，你會在不該造輪子的地方重復(fù)造輪子，而在需要深度控制的地方丟掉靈活性。

順帶一提Anthropic的Managed Agents。它們作為第四股力量，省去了所有基礎(chǔ)設(shè)施的考量，但適用面窄。如果你評估后覺得代理的管理成本和運(yùn)維復(fù)雜度超出了收益，那么這股力量可以拿來兜底。只是和SDK相比，又隔了一層對循環(huán)控制的讓渡層級，這是另外一套決策模型了。

最后說一個看起來老生常談但尤其容易被忽視的東西：文檔和社區(qū)。SDK剛改完名那段時間，網(wǎng)上的信息新舊混雜，AI搜索引擎推薦的答案可能還引用著半年前的示例。查資料時注意看包名，只要不是@anthropic-ai/claude-agent-sdk或claude-agent-sdk，就馬上劃走。同時，Anthropic對SDK后續(xù)的發(fā)展方向也明確——架構(gòu)、構(gòu)建走查、成本控制、安全、部署，這些內(nèi)容已經(jīng)寫進(jìn)了他們的指南。在跳進(jìn)代碼之前，花半天時間把這些章節(jié)啃完，比一頭扎進(jìn)去一個個報錯排查要劃算得多。畢竟，當(dāng)智能體的控制權(quán)從你手里交出去的那一瞬，對邊界的理解就決定了你的系統(tǒng)是持續(xù)運(yùn)轉(zhuǎn)的機(jī)器還是一臺隨時拋錨的概念車。