快速开始

使用 Python 或 TypeScript Agent SDK 开始构建能够自主工作的 AI 代理

使用 Agent SDK 构建一个 AI 代理，它可以读取你的代码、发现错误并修复它们，所有这一切都无需手动干预。

你将做什么：

1. 使用 Agent SDK 设置一个项目
2. 创建一个包含一些有缺陷代码的文件
3. 运行一个代理，自动查找并修复错误

前置条件

• Node.js 18+ 或 Python 3.10+
• 一个 Anthropic 账户（在此注册）

设置

mkdir my-agent
cd my-agent

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

uv init
uv add claude-agent-sdk

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

ANTHROPIC_API_KEY=your-api-key

创建一个有缺陷的文件

此快速开始将引导你构建一个可以查找和修复代码中错误的代理。首先，你需要一个包含一些有意错误的文件供代理修复。在 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()

此代码有两个错误：

1. calculate_average([]) 会因除以零而崩溃
2. 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"],  # 自动批准这些工具
permission_mode="acceptEdits",  # 自动批准文件编辑
),
):
# 打印人类可读的输出
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)  # Claude 的推理
elif hasattr(block, "name"):
print(f"Tool: {block.name}")  # 正在调用的工具
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}")  # 最终结果


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"], // 自动批准这些工具
permissionMode: "acceptEdits" // 自动批准文件编辑
}
})) {
// 打印人类可读的输出
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude 的推理
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // 正在调用的工具
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // 最终结果
}
}

此代码有三个主要部分：

1. query：创建 agentic 循环的主入口点。它返回一个异步迭代器，所以你使用 async for 来流式传输 Claude 工作时的消息。查看 Python 或 TypeScript SDK 参考中的完整 API。

2. prompt：你想让 Claude 做什么。Claude 根据任务确定要使用哪些工具。

3. 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。你会看到处理空列表和空用户的防御性代码。你的代理自主地：

1. 读取 utils.py 以理解代码
2. 分析了逻辑并识别了会导致崩溃的边界情况
3. 编辑了文件以添加适当的错误处理

这就是 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"

关键概念

工具控制你的代理可以做什么：

权限模式控制你想要多少人工监督：

上面的示例使用 acceptEdits 模式，它自动批准文件操作，以便代理可以在没有交互式提示的情况下运行。如果你想提示用户批准，使用 default 模式并提供一个 canUseTool 回调来收集用户输入。为了获得更多控制，请参阅权限。

故障排除

API 错误 `thinking.type.enabled` 不支持此模型

Claude Opus 4.7 用 thinking.type.adaptive 替换了 thinking.type.enabled。当你选择 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。

后续步骤

现在你已经创建了你的第一个代理，学习如何扩展其功能并将其定制到你的用例：

• 权限：控制你的代理可以做什么以及何时需要批准
• Hooks：在工具调用之前或之后运行自定义代码
• 会话：构建维护上下文的多轮代理
• MCP 服务器：连接到数据库、浏览器、API 和其他外部系统
• 托管：将代理部署到 Docker、云和 CI/CD
• 示例代理：查看完整示例：电子邮件助手、研究代理等