Claude Agent SDK 介紹與實作：快速建構 AI 代理程式

大多數人初次接觸 Claude Agent SDK 時，可能只是在別人的程式碼庫中看到這個套件名稱，卻不清楚它的實際用途。它究竟是 API 用戶端、Claude Code 本身，還是一個開發框架呢？答案皆非，這種混淆常讓開發者浪費時間，因為該 SDK 與這些工具截然不同。

本文作者查閱了官方文件及兩個 GitHub 儲存庫，所有內容均已根據 Anthropic 於 2026 年 10 月 23 日的最新文件進行核對，文末也列出了參考來源。若想先了解更廣泛的 AI 代理框架生態，作者的 AI 代理框架比較文章涵蓋了該 SDK 與 LangGraph、Vercel AI SDK 等工具的關係。

Claude Agent SDK 究竟是什麼？Claude Agent SDK 是一個提供給 Python 和 TypeScript 的程式庫，它為你的應用程式提供了驅動 Claude Code 的代理迴圈、內建工具、權限管理和上下文管理功能。

你只需傳遞提示詞（prompt）和選項給 query() 函式，Claude 便會自主讀取檔案、執行指令並編輯程式碼，同時將訊息串流回傳。這就是其核心概念。Claude Code 是一個你在終端機中使用的產品，而 Agent SDK 則是相同的引擎，以程式庫的形式公開，讓你能夠將其嵌入到腳本、後端服務或 CI 工作中。

Anthropic 官方將其描述為「作為程式庫的 Claude Code」。該 SDK 過去曾被稱為 Claude Code SDK，TypeScript 套件的 GitHub README 指出 Claude Code SDK 現已更名為 Claude Agent SDK，並提供了重大變更的遷移指南。

如果你發現舊的教學文章仍匯入 @anthropic-ai/claude-code，那表示使用的是舊版套件，目前最新的套件名稱將在下方說明。

Claude Agent SDK、Messages API 與 Claude Code 的比較：這三種方式都能讓 Claude 執行任務，但它們在誰來執行迴圈（tool loop）方面有所不同。Anthropic 的概覽頁面比較了 Agent SDK、CLI、Client SDK 和 Managed Agents，以下是作者在團隊成員詢問如何選擇時會提供的版本：Messages API（Client SDK）提供從程式碼直接存取 Claude API 的方式，工具迴圈由開發者或 Client SDK 的測試版工具執行器運行，最適合用於聊天、資訊擷取、分類及自訂代理迴圈。

Claude Agent SDK 則是 Claude Code 代理的 Python 和 TypeScript 程式庫，工具迴圈由 SDK 使用 Claude Code 代理迴圈運行，內建檔案讀寫編輯、Shell 指令、網路搜尋等多種工具，並包含權限、會話和掛鉤功能，最適合將具備程式碼能力的代理嵌入到自己的應用程式中。

Claude Code CLI 則是日常互動使用的終端機介面，工具迴圈由 Claude Code 本身運行，內建與 Agent SDK 相同的工具，最適合互動式開發和一次性任務。

此外，還有第四種選項：Managed Agents。這是一種託管的代理框架，Anthropic 會在受管理的雲端沙盒中運行迴圈，並透過 Claude API 進行配置。Agent SDK 則恰好相反，代理會在你的程序中、你的機器上或你的伺服器上運行。

值得注意的是，該 SDK 並非僅僅是 HTTP 呼叫的輕量級封裝。Python 和 TypeScript 套件都捆綁了原生的 Claude Code 二進位檔，並由 SDK 驅動，這也是為什麼你能獲得與 Claude Code 完全一致的行為，同時也解釋了某些安裝設定需要額外注意的原因（詳情請見安裝部分）。

如何安裝 Claude Agent SDK：該 SDK 提供兩個套件，分別支援 Python 和 TypeScript，兩者都需要 Anthropic API 金鑰。TypeScript 套件名稱為 @anthropic-ai/claude-agent-sdk，安裝指令為 npm install @anthropic-ai/claude-agent-sdk，運行環境需 Node.js 18 或更高版本。

Python 套件名稱為 claude-agent-sdk，安裝指令為 pip install claude-agent-sdk 或 uv add claude-agent-sdk，運行環境需 Python 3.10 或更高版本。

由於兩者目前都是 0.x 版本，API 預計會持續變動，建議在你的鎖定檔（lockfile）中固定版本，並在升級前閱讀每個儲存庫的變更日誌。對於新的 TypeScript 專案，快速入門指南建議以下設定步驟：建立專案目錄、初始化 npm、設定 type = module 以支援頂層 await，並安裝 @anthropic-ai/claude-agent-sdk 和 tsx。

如果現有專案使用 CommonJS，則將腳本命名為 agent.mts。接著，在代理運行的 shell 環境中設定你的 API 金鑰，例如 export ANTHROPIC_API_KEY=your-api-key。SDK 會從程序環境中讀取金鑰，不會自動載入 .env 檔案，因此如果金鑰儲存在 .env 中，你需要自行使用 dotenv 等工具載入。

該 SDK 也支援 Amazon Bedrock（設定 CLAUDE_CODE_USE_BEDROCK=1）、Google Cloud（設定 CLAUDE_CODE_USE_VERTEX=1）和 Microsoft Foundry（設定 CLAUDE_CODE_USE_FOUNDRY=1），每個平台都有其各自的雲端憑證。

文件中提到兩個安裝注意事項。如果 pip 安裝的是 Python 原始碼發行版而非平台專用的 wheel 檔案（例如 ARM64 Windows），則不會捆綁二進位檔，你需要原生安裝 Claude Code，以便 SDK 能夠在你的 PATH 中找到它。

在 TypeScript 方面，二進位檔是透過 npm 的可選依賴項（optional dependencies）提供的，因此執行 npm ci --omit=optional 會導致缺少該二進位檔。此時，請重新安裝時不要使用該旗標，或者將 pathToClaudeCodeExecutable 指向原生安裝的 Claude Code。

使用 TypeScript 建構一個最小的 Claude 代理：這是一個快速入門的代理範例，它會檢查檔案中的崩潰錯誤並進行修復。首先，建立一個名為 utils.py 的檔案，其中包含兩個明顯的錯誤，因為這將是代理要編輯的檔案。calculate_average([]) 會導致除以零錯誤，而 get_user_name(None) 會引發 TypeError。

接著，在 agent.ts 中建立代理程式碼，其中 query() 函式是進入點，它會返回一個非同步迭代器，每次迭代都會產生一條訊息，可能是 Claude 的推理、工具呼叫、工具結果或最終結果。prompt 定義了任務，你不需要告訴 Claude 使用哪些工具，它會根據任務自行選擇。

options 用於配置代理，此處 allowedTools 預先批准了三個工具，而 permissionMode: "acceptEdits" 則批准了檔案編輯。當 Claude 完成任務或遇到錯誤時，迴圈便會結束。SDK 會處理協調、工具執行、上下文管理和重試，因此你的程式碼只需消費串流即可。

如果你不需要即時輸出，例如在背景工作中，你可以選擇一次性收集所有訊息。

使用 Python 建構相同的代理：同樣的快速入門代理範例，其 Python 版本使用了 ClaudeAgentOptions 和訊息類別。程式碼結構與 TypeScript 版本相似，但選項名稱採用 snake_case 命名慣例。

對於 Python 中的多輪對話、雙向串流、自訂工具和掛鉤，儲存庫還提供了 ClaudeSDKClient。你可以將其作為非同步上下文管理器使用，並透過 client.query(...) 和 client.receive_response() 進行互動。

Claude Agent SDK 中的工具與權限：內建工具與 Claude Code 使用的工具相同，包括讀取、寫入和編輯檔案、執行指令、搜尋和網路存取。快速入門指南將常見的工具組合歸類如下：「Read, Glob, Grep」用於唯讀分析，「Read, Edit, Glob」用於分析和修改程式碼，「Read, Edit, Bash, Glob, Grep」則用於完全自動化。

人們常誤解 allowedTools 的作用，它並非一個列出所有可用工具的白名單，而是一個權限規則列表：你指定的工具會被自動批准。任何你未列出的工具仍然對 Claude 可用，如果呼叫該工具需要批准，則會依序透過權限模式和你的 canUseTool 回呼函式進行處理。

若要完全從 Claude 的上下文中移除某個工具，請將其裸名放入 disallowedTools。例如，Bash(rm *) 這樣的範圍規則會讓 Bash 仍然可用，但在任何模式下都會拒絕匹配的呼叫。文件描述了每個工具請求的固定評估順序：首先是掛鉤（hooks），然後是拒絕規則（deny rules），接著是詢問規則（ask rules），然後是權限模式（permission mode），再來是允許規則（allow rules），最後是 canUseTool 回呼函式。即使在 bypassPermissions 模式下，拒絕規則也具有優先權。

SDK 支援六種權限模式：「default」模式下沒有基於模式的自動批准，需要批准且不符合任何允許規則的呼叫會轉到你的 canUseTool 回呼函式。「dontAsk」模式會拒絕任何會觸發提示的動作，且不呼叫 canUseTool。

「acceptEdits」模式會自動批准工作目錄內的檔案編輯和檔案系統指令，例如 mkdir、touch、rm、mv、cp 和 sed。「bypassPermissions」模式下，工具無需提示即可運行，除了少數模式無法自動批准的動作，請謹慎使用。

「plan」模式下，Claude 會進行探索和規劃，但不會編輯你的原始碼檔案。「auto」模式則由分類器模型審查 Shell 指令、網路請求等動作，並決定允許或阻止每個動作。對於一個嚴格限制的唯讀代理，文件建議將 allowedTools 與 dontAsk 搭配使用。

文件中的一項警告值得重複：allowedTools 不會限制 bypassPermissions。如果你設定 allowedTools: ["Read"] 並搭配 permissionMode: "bypassPermissions"，所有工具仍然會被批准，包括 Bash、Write 和 Edit。

如果你需要 bypass 模式但想阻止特定工具，請使用 disallowedTools。作者在「coding agent permissions and least privilege」一文中詳細闡述了更廣泛的最小權限方法，包括 CLI 中的 --dangerously-skip-permissions 旗標。

此外，請注意，除非你設定了模式或你的設定檔有指定，否則 SDK 現在預設以 default 模式啟動。在 default 模式下，如果沒有批准方式，需要批准的工具呼叫將會被拒絕。如果你的首次代理運行報告了被拒絕的工具呼叫，這通常是原因所在，解決方法是設定允許規則或 canUseTool 回呼函式，而非使用 bypass 模式。

新增 MCP 伺服器和自訂工具：SDK 支援模型上下文協定（Model Context Protocol, MCP），因此你的代理可以使用任何 MCP 伺服器。你可以在 mcpServers 選項中傳遞伺服器設定。文件展示了標準輸入輸出（stdio）伺服器（一個要執行的指令）、HTTP 和 SSE 伺服器（一個 URL），以及程序內 SDK 伺服器（在你的程式碼中定義的工具）。

以下範例展示了如何透過 HTTP 連接到 Claude Code 文件的 MCP 伺服器。