快速開始
使用 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 install @anthropic-ai/claude-agent-sdk
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 金鑰，然後在您的項目目錄中建立一個 .env 檔案：
ANTHROPIC_API_KEY=your-api-key
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 Vertex AI：設定
CLAUDE_CODE_USE_VERTEX=1環境變數並設定 Google Cloud 認證 - Microsoft Azure：設定
CLAUDE_CODE_USE_FOUNDRY=1環境變數並設定 Azure 認證
如需詳細資訊，請參閱 Bedrock、Claude Platform on AWS、Vertex AI 或 Azure AI 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：
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
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 |
自動批准文件編輯和常見文件系統命令，詢問其他操作 | 受信任的開發工作流 |
dontAsk |
拒絕不在 allowedTools 中的任何內容 |
鎖定的無頭代理 |
auto（僅 TypeScript） |
模型分類器批准或拒絕每個工具調用 | 具有安全防護的自主代理 |
bypassPermissions |
運行每個工具而不提示，除非明確的 ask 規則 符合 |
沙箱 CI、完全受信任的環境 |
default |
需要 canUseTool 回調來處理批准 |
自定義批准流程 |
上面的示例使用 acceptEdits 模式，它自動批准文件操作，以便代理可以無需交互提示地運行。如果您想提示用戶批准，請使用 default 模式並提供一個 canUseTool 回調來收集用戶輸入。如需更多控制，請參閱權限。
故障排除
API 錯誤 `thinking.type.enabled` 不支持此模型
Claude Opus 4.7 將 thinking.type.enabled 替換為 thinking.type.adaptive。當您選擇 claude-opus-4-7 時，較舊的 Agent SDK 版本會失敗並出現以下 API 錯誤：
API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}
升級到 Agent SDK v0.2.111 或更高版本以使用 Opus 4.7。
後續步驟
現在您已創建了第一個代理，了解如何擴展其功能並根據您的用例進行定制：