快速開始
使用 Python 或 TypeScript Agent SDK 開始構建能夠自主工作的 AI 代理
使用 Agent SDK 構建一個 AI 代理，它可以讀取您的代碼、發現錯誤並自動修復它們，無需手動干預。
您將執行的操作：
- 使用 Agent SDK 設置項目
- 創建一個包含一些有缺陷代碼的文件
- 運行一個代理，自動查找並修復錯誤
先決條件
- Node.js 18+ 或 Python 3.10+
- 一個 Anthropic 帳戶。如果您還沒有帳戶，在此註冊。
設定
建立專案資料夾
為此快速入門建立新目錄：
mkdir my-agent
cd my-agent
對於您自己的專案，您可以從任何資料夾執行 SDK；預設情況下，它將能夠存取該目錄及其子目錄中的檔案。
安裝 SDK
為您的語言安裝 Agent SDK 套件：
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
在 package.json 中設定 "type": "module" 可讓您的代理程式指令碼使用頂層 await，而 tsx 可直接執行 TypeScript 檔案。npm 在安裝成功時會列印 added N packages。
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
tsx 可直接執行 TypeScript 檔案。如果您的專案使用 CommonJS，請將代理程式指令碼命名為 agent.mts 而不是 agent.ts。.mts 副檔名使 tsx 將檔案視為 ES 模組，因此頂層 await 可以正常運作，無需將整個專案轉換為 ES 模組。在本快速入門稍後的建立和執行步驟中，使用 agent.mts 代替 agent.ts。
安裝 uv，一個快速的 Python 套件管理器，可自動處理虛擬環境。然後初始化專案並新增 SDK：
uv init
uv add claude-agent-sdk
建立並啟動虛擬環境，然後安裝套件。
在 macOS 或 Linux 上：
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
在 Windows 上：
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk
如果 PowerShell 因執行原則錯誤而阻止 Activate.ps1，請先執行 Set-ExecutionPolicy -Scope Process RemoteSigned。
設定您的 API 金鑰
從 Claude 主控台 取得 API 金鑰，然後在您將執行代理程式的 shell 中將其設定為環境變數：
export ANTHROPIC_API_KEY=your-api-key
$env:ANTHROPIC_API_KEY = "your-api-key"
SDK 從執行您的代理程式的程序環境中讀取金鑰；它不會自動載入 .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 認證
如需詳細資訊，請參閱 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 的設定指南。
創建有缺陷的文件
此快速開始將引導您構建一個可以查找並修復代碼中的錯誤的代理。首先，您需要一個包含一些故意錯誤的文件供代理修復。在 my-agent 目錄中創建 utils.py 並粘貼以下代碼：
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
return user["name"].upper()
此代碼有兩個錯誤：
calculate_average([])因除以零而崩潰get_user_name(None)因 TypeError 而崩潰
建立一個尋找並修復錯誤的代理
如果您使用 Python SDK，請建立 agent.py；如果使用 TypeScript，請建立 agent.ts。如果您現有的專案使用 CommonJS，請改用 agent.mts：
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
# Agentic loop: streams messages as Claude works
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"], # Auto-approve these tools
permission_mode="acceptEdits", # Auto-approve file edits
),
):
# Print human-readable output
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text) # Claude's reasoning
elif hasattr(block, "name"):
print(f"Tool: {block.name}") # Tool being called
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}") # Final result
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
// Agentic loop: streams messages as Claude works
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options: {
allowedTools: ["Read", "Edit", "Glob"], // Auto-approve these tools
permissionMode: "acceptEdits" // Auto-approve file edits
}
})) {
// Print human-readable output
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude's reasoning
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // Tool being called
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // Final result
}
}
此程式碼有三個主要部分：
-
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 完成任務或遇到錯誤時，迴圈就會結束。
迴圈內的訊息處理會篩選出人類可讀的輸出。如果不進行篩選，您會看到原始訊息物件，包括系統初始化和內部狀態，這對除錯很有用，但在其他情況下會很雜亂。
執行您的代理
您的代理已準備好。使用下列命令執行它：
npx tsx agent.ts
如果您將指令碼命名為 agent.mts，請改為執行 npx tsx agent.mts。
uv run agent.py
在您的虛擬環境仍然啟用的情況下：
python agent.py
在執行時，代理會列印其推理和它呼叫的每個工具，最後以 Done: success 結束。執行後，檢查 utils.py。您會看到防禦性程式碼處理空清單和空值使用者。您的代理自主地：
- 讀取
utils.py以了解程式碼 - 分析邏輯並識別會導致當機的邊界情況
- 編輯檔案以新增適當的錯誤處理
這就是 Agent SDK 的不同之處：Claude 直接執行工具，而不是要求您實作它們。
嘗試其他提示
現在您的代理已設定好，請嘗試一些不同的提示：
"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"
自訂您的代理
您可以透過變更選項來修改代理的行為。以下是一些範例：
新增網路搜尋功能：
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
permissionMode: "acceptEdits"
}
};
給 Claude 一個自訂系統提示：
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
}
};
在終端機中執行命令：
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "Bash"],
permissionMode: "acceptEdits"
}
};
啟用 Bash 後，請嘗試："Write unit tests for utils.py, run them, and fix any failures"
每個這些程式碼片段都會在同一個選項物件上設定欄位。如需更多資訊，請參閱設定您的代理。
關鍵概念
工具控制您的代理可以執行的操作：
| 工具 | 代理可以執行的操作 |
|---|---|
Read、Glob、Grep |
只讀分析 |
Read、Edit、Glob |
分析和修改代碼 |
Read、Edit、Bash、Glob、Grep |
完全自動化 |
權限模式控制您想要多少人工監督。SDK 會按照固定順序評估活躍模式以及您的允許和拒絕規則，詳見權限如何被評估。如需完整的模式列表、其行為以及何時使用各個模式，請參閱代理迴圈如何運作中的權限模式。
後續步驟
現在您已建立了第一個代理程式，請了解如何擴展其功能並根據您的使用案例進行客製化：
- 設定您的代理程式：組合選項物件並找到涵蓋每個設定的頁面
- 權限：控制您的代理程式可以執行的操作以及何時需要批准
- Hooks：在工具呼叫之前或之後執行自訂程式碼
- Sessions：建立維持上下文的多輪代理程式
- MCP servers：連接到資料庫、瀏覽器、API 和其他外部系統
- Hosting：將代理程式部署到 Docker、雲端和 CI/CD
- Example agents：查看完整範例：電子郵件助手、研究代理程式等
- Troubleshooting：修復 CLI 無法啟動或退出時的錯誤，或結果未能以結構化輸出形式到達時的問題