Agent SDK 概述

安裝

npm install @anthropic-ai/claude-agent-sdk

pip install claude-agent-sdk

SDK 選項

Claude Agent SDK 提供多種形式，以適應不同的使用案例：

• TypeScript SDK - 適用於 Node.js 和網頁應用程式
• Python SDK - 適用於 Python 應用程式和資料科學
• 串流模式與單一模式 - 了解輸入模式和最佳實踐

為什麼使用 Claude Agent SDK？

Claude Agent SDK 建立在驅動 Claude Code 的代理框架之上，提供了建立生產就緒代理所需的所有構建塊。

利用我們在 Claude Code 上所做的工作，包括：

• 上下文管理：自動壓縮和上下文管理，確保您的代理不會耗盡上下文。
• 豐富的工具生態系統：檔案操作、程式碼執行、網路搜尋和 MCP 可擴展性
• 進階權限：對代理功能的細粒度控制
• 生產必需品：內建錯誤處理、工作階段管理和監控
• 最佳化的 Claude 整合：自動提示快取和效能最佳化

您可以使用 SDK 建立什麼？

以下是您可以建立的一些代理類型範例：

編碼代理：

• SRE 代理，診斷和修復生產問題
• 安全審查機器人，審計程式碼中的漏洞
• 值班工程助手，進行事件分類
• 程式碼審查代理，強制執行風格和最佳實踐

業務代理：

• 法律助手，審查合約和合規性
• 財務顧問，分析報告和預測
• 客戶支援代理，解決技術問題
• 行銷團隊的內容建立助手

核心概念

驗證

對於基本驗證，請從 Claude 控制台 檢索 Claude API 金鑰，並設定 ANTHROPIC_API_KEY 環境變數。

SDK 也支援透過第三方 API 提供者進行驗證：

• Amazon Bedrock：設定 CLAUDE_CODE_USE_BEDROCK=1 環境變數並設定 AWS 認證
• Google Vertex AI：設定 CLAUDE_CODE_USE_VERTEX=1 環境變數並設定 Google Cloud 認證

如需第三方提供者的詳細設定說明，請參閱 Amazon Bedrock 和 Google Vertex AI 文件。

完整 Claude Code 功能支援

SDK 提供對 Claude Code 中所有預設功能的存取，利用相同的檔案系統型設定：

• 子代理：啟動儲存為 ./.claude/agents/ 中 Markdown 檔案的專門代理
• 代理技能：透過儲存在 ./.claude/skills/ 中的 SKILL.md 檔案擴展 Claude 的專門功能
• 鉤子：執行在 ./.claude/settings.json 中設定的自訂命令，以回應工具事件
• 斜線命令：使用定義為 ./.claude/commands/ 中 Markdown 檔案的自訂命令
• 外掛程式：使用 plugins 選項以程式設計方式載入自訂外掛程式，以使用自訂命令、代理、技能、鉤子和 MCP 伺服器擴展 Claude Code。如需詳細資訊，請參閱外掛程式。
• 記憶體 (CLAUDE.md)：透過專案目錄中的 CLAUDE.md 或 .claude/CLAUDE.md 檔案，或 ~/.claude/CLAUDE.md 用於使用者級別的說明，維護專案上下文。若要載入這些檔案，您必須在選項中明確設定 settingSources: ['project']（TypeScript）或 setting_sources=["project"]（Python）。如需詳細資訊，請參閱修改系統提示。

這些功能的運作方式與其 Claude Code 對應項相同，透過從相同的檔案系統位置讀取。

系統提示

系統提示定義您的代理的角色、專業知識和行為。這是您指定要建立的代理類型的地方。

工具權限

使用細粒度權限控制您的代理可以使用哪些工具：

• allowedTools - 明確允許特定工具
• disallowedTools - 封鎖特定工具
• permissionMode - 設定整體權限策略

模型上下文協議 (MCP)

透過 MCP 伺服器使用自訂工具和整合擴展您的代理。這允許您連接到資料庫、API 和其他外部服務。

報告錯誤

如果您在 Agent SDK 中遇到錯誤或問題：

• TypeScript SDK：在 GitHub 上報告問題
• Python SDK：在 GitHub 上報告問題

變更日誌

查看 SDK 更新、錯誤修復和新功能的完整變更日誌：

• TypeScript SDK：檢視 CHANGELOG.md
• Python SDK：檢視 CHANGELOG.md

相關資源

• CLI 參考 - 完整的 CLI 文件
• GitHub Actions 整合 - 自動化您的 GitHub 工作流程
• MCP 文件 - 使用自訂工具擴展 Claude
• 常見工作流程 - 逐步指南
• 疑難排解 - 常見問題和解決方案