快速開始
使用 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 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 套件管理器，可自動處理虛擬環境：
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 認證 - Claude Platform on AWS：設定
CLAUDE_CODE_USE_ANTHROPIC_AWS=1和ANTHROPIC_AWS_WORKSPACE_ID，然後設定 AWS 認證 - Google Cloud 的 Agent Platform：設定
CLAUDE_CODE_USE_VERTEX=1環境變數並設定 Google Cloud 認證 - Microsoft Azure：設定
CLAUDE_CODE_USE_FOUNDRY=1環境變數並設定 Azure 認證
如需詳細資訊，請參閱 Amazon Bedrock、Claude Platform on AWS、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：創建 agentic 循環的主要入口點。它返回一個異步迭代器，因此您使用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
運行後，檢查 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 |
完全自動化 |
權限模式控制您想要多少人工監督：
| 模式 | 行為 | 用例 |
|---|---|---|
acceptEdits |
自動批准文件編輯和常見文件系統命令，詢問其他操作 | 受信任的開發工作流 |
plan |
運行只讀工具；文件編輯永遠不會自動批准，並到達您的 canUseTool 回調 |
在批准執行前確定任務範圍 |
dontAsk |
拒絕不在 allowedTools 中的任何內容；連接器工具您的組織設定為 ask和需要用戶互動的工具即使您已列出它們也會被拒絕 |
鎖定的無頭代理 |
auto |
模型分類器批准或拒絕每個工具調用 | 具有安全防護的自主代理 |
bypassPermissions |
運行每個工具而不提示，除了明確的 ask 規則符合的工具、連接器工具您的組織設定為 ask和需要用戶互動的工具 |
沙箱 CI、完全受信任的環境 |
default |
需要 canUseTool 回調來處理批准 |
自定義批准流程 |
上面的示例使用 acceptEdits 模式，它自動批准文件操作，以便代理可以無需交互提示地運行。如果您想提示用戶批准，請使用 default 模式並提供一個 canUseTool 回調來收集用戶輸入。如需更多控制，請參閱權限。
後續步驟
現在您已創建了第一個代理，了解如何擴展其功能並根據您的用例進行定制：