- 使用 Agent SDK 設置項目
- 創建一個包含一些有缺陷代碼的文件
- 運行一個代理,自動查找並修復錯誤
先決條件
- Node.js 18+ 或 Python 3.10+
- 一個 Anthropic 帳戶。如果您還沒有帳戶,在此註冊。
設定
1
建立專案資料夾
為此快速入門建立新目錄:對於您自己的專案,您可以從任何資料夾執行 SDK;預設情況下,它將能夠存取該目錄及其子目錄中的檔案。
2
安裝 SDK
為您的語言安裝 Agent SDK 套件:在
- TypeScript (新專案)
- TypeScript (現有專案)
- Python (uv)
- Python (pip)
package.json 中設定 "type": "module" 可讓您的代理程式指令碼使用頂層 await,而 tsx 可直接執行 TypeScript 檔案。npm 在安裝成功時會列印 added N packages。TypeScript 和 Python SDK 都包含原生 Claude Code 二進位檔,因此大多數安裝不需要單獨安裝 Claude Code。某些安裝沒有包含的二進位檔:
- 如果 pip 安裝 Python SDK 的原始碼發行版而不是平台 wheel(例如在 ARM64 Windows 上),則不會包含二進位檔。原生安裝 Claude Code。Python SDK 會在您的
PATH上找到它。 - TypeScript SDK 通過 npm 可選相依性安裝其二進位檔,因此跳過它們的安裝(例如
npm ci --omit=optional)即使在支援的平台上也不會獲得二進位檔。重新安裝而不跳過可選相依性,或原生安裝 Claude Code 並將pathToClaudeCodeExecutable設定為其路徑。
3
設定您的 API 金鑰
從 Claude 主控台 取得 API 金鑰,然後在您將執行代理程式的 shell 中將其設定為環境變數:SDK 從執行您的代理程式的程序環境中讀取金鑰;它不會自動載入
- macOS / Linux
- Windows (PowerShell)
.env 檔案。如果您將金鑰保存在 .env 檔案中,請自行載入它,例如使用 dotenv 套件,然後再呼叫 SDK。SDK 也支援透過第三方 API 提供者進行驗證:- Amazon Bedrock:設定
CLAUDE_CODE_USE_BEDROCK=1環境變數並設定 AWS 認證 - AWS 上的 Claude Platform:設定
CLAUDE_CODE_USE_ANTHROPIC_AWS=1和ANTHROPIC_AWS_WORKSPACE_ID,然後設定 AWS 認證 - Google Cloud 的 Agent Platform:設定
CLAUDE_CODE_USE_VERTEX=1環境變數並設定 Google Cloud 認證 - Microsoft Foundry:設定
CLAUDE_CODE_USE_FOUNDRY=1環境變數並設定 Azure 認證
除非事先獲得批准,否則 Anthropic 不允許第三方開發人員為其產品(包括基於 Claude Agent SDK 建立的 agent)提供 claude.ai 登入或速率限制。請改用本文件中描述的 API 金鑰驗證方法。
創建有缺陷的文件
此快速開始將引導您構建一個可以查找並修復代碼中的錯誤的代理。首先,您需要一個包含一些故意錯誤的文件供代理修復。在my-agent 目錄中創建 utils.py 並粘貼以下代碼:
calculate_average([])因除以零而崩潰get_user_name(None)因 TypeError 而崩潰
建立一個尋找並修復錯誤的代理
如果您使用 Python SDK,請建立agent.py;如果使用 TypeScript,請建立 agent.ts。如果您現有的專案使用 CommonJS,請改用 agent.mts:
-
query:主要進入點,建立代理迴圈。它會傳回非同步迭代器,因此您可以使用async for在 Claude 工作時串流訊息。請參閱 Python 或 TypeScript SDK 參考中的完整 API。 -
prompt:您想讓 Claude 執行的任務。Claude 會根據任務判斷要使用哪些工具。 -
options:代理的設定。此範例使用allowedTools預先核准Read、Edit和Glob,並使用permissionMode: "acceptEdits"自動核准檔案變更。其他選項包括systemPrompt、mcpServers等。請參閱 Python 或 TypeScript 的所有選項。
async for 迴圈會持續執行,因為 Claude 思考、呼叫工具、觀察結果,並決定接下來要做什麼。每次迭代都會產生一條訊息:Claude 的推理、工具呼叫、工具結果或最終結果。SDK 會處理協調、工具執行、內容管理和重試,因此您只需使用串流。當 Claude 完成任務或遇到錯誤時,迴圈就會結束。
迴圈內的訊息處理會篩選出人類可讀的輸出。如果不進行篩選,您會看到原始訊息物件,包括系統初始化和內部狀態,這對除錯很有用,但在其他情況下會很雜亂。
此範例使用串流來即時顯示進度。如果您不需要即時輸出(例如,用於背景工作或 CI 管道),您可以一次收集所有訊息。如需詳細資訊,請參閱串流與單回合模式。
執行您的代理
您的代理已準備好。使用下列命令執行它:- TypeScript
- Python (uv)
- Python (pip)
agent.mts,請改為執行 npx tsx agent.mts。Done: success 結束。執行後,檢查 utils.py。您會看到防禦性程式碼處理空清單和空值使用者。您的代理自主地:
- 讀取
utils.py以了解程式碼 - 分析邏輯並識別會導致當機的邊界情況
- 編輯檔案以新增適當的錯誤處理
如果您看到驗證錯誤,例如
Not logged in 或 Invalid API key,請確保您已在執行代理的 shell 中設定 ANTHROPIC_API_KEY 環境變數。SDK 不會自動載入 .env 檔案。如需這些和其他驗證錯誤的原因和修復方法,請參閱錯誤參考中的驗證錯誤。嘗試其他提示
現在您的代理已設定好,請嘗試一些不同的提示:"Add docstrings to all functions in utils.py""Add type hints to all functions in utils.py""Create a README.md documenting the functions in utils.py"
自訂您的代理
您可以透過變更選項來修改代理的行為。以下是一些範例: 新增網路搜尋功能:Bash 後,請嘗試:"Write unit tests for utils.py, run them, and fix any failures"
每個這些程式碼片段都會在同一個選項物件上設定欄位。如需更多資訊,請參閱設定您的代理。
關鍵概念
工具控制您的代理可以執行的操作:
權限模式控制您想要多少人工監督。SDK 會按照固定順序評估活躍模式以及您的允許和拒絕規則,詳見權限如何被評估。如需完整的模式列表、其行為以及何時使用各個模式,請參閱代理迴圈如何運作中的權限模式。
後續步驟
現在您已建立了第一個代理程式,請了解如何擴展其功能並根據您的使用案例進行客製化:- 設定您的代理程式:組合選項物件並找到涵蓋每個設定的頁面
- 權限:控制您的代理程式可以執行的操作以及何時需要批准
- Hooks:在工具呼叫之前或之後執行自訂程式碼
- Sessions:建立維持上下文的多輪代理程式
- MCP servers:連接到資料庫、瀏覽器、API 和其他外部系統
- Hosting:將代理程式部署到 Docker、雲端和 CI/CD
- Example agents:查看完整範例:電子郵件助手、研究代理程式等
- Troubleshooting:修復 CLI 無法啟動或退出時的錯誤,或結果未能以結構化輸出形式到達時的問題