快速开始¶

本指南带你用 Agent SDK 构建一个能自主读取代码、发现 Bug 并修复的 AI Agent。整个过程中你不需要手动实现任何工具逻辑——Agent SDK 已经帮你做好了。

前置条件¶

开始之前，确保你已准备好：

• Node.js 18+ 或 Python 3.10+
• 一个 **Anthropic 账户**和 API Key（在 Claude 控制台获取）

安装 SDK¶

TypeScript¶

1

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

Python（推荐使用 uv）¶

1

uv init && uv add claude-agent-sdk

Python（使用 pip）¶

1
2

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

TypeScript SDK 会为你的平台捆绑一个本地 Claude Code 二进制文件作为可选依赖项，无需单独安装 Claude Code。

设置 API Key¶

在项目目录中创建 .env 文件：

1

ANTTHROPIC_API_KEY=your-api-key

SDK 还支持通过第三方 API 提供商进行认证：

• Amazon Bedrock：设置 CLAUDE_CODE_USE_BEDROCK=1 并配置 AWS 凭证
• Google Vertex AI：设置 CLAUDE_CODE_USE_VERTEX=1 并配置 Google Cloud 凭证
• Microsoft Azure：设置 CLAUDE_CODE_USE_FOUNDRY=1 并配置 Azure 凭证

准备一个有 Bug 的文件¶

我们的 Agent 要修复代码中的 Bug，所以先需要一个「靶子」。创建 utils.py：

1
2
3
4
5
6
7
8
9

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()

这段代码有两个 Bug：

• calculate_average([]) 会因为除以零而崩溃
• get_user_name(None) 会因为 TypeError 而崩溃

构建你的第一个 Agent¶

TypeScript 版本¶

创建 agent.ts：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import { query } from "@anthropic-ai/claude-agent-sdk";

// Agent 循环：流式输出 Claude 的工作过程
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"], // 允许 Claude 使用的工具
    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}`); // 最终结果
  }
}

Python 版本¶

创建 agent.py：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Agent 循环：流式输出 Claude 的工作过程
    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"],  # 允许 Claude 使用的工具
            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())

代码解读¶

这段代码有三个关键部分：

• query——创建 Agent 循环的主入口。它返回一个异步迭代器，用 async for 流式传输 Claude 工作时的消息
• prompt——告诉 Claude 你想让它做什么。Claude 会根据任务自行决定使用哪些工具
• options——Agent 的配置。allowedTools 预先批准指定工具，permissionMode: "acceptEdits" 自动批准文件修改

async for 循环在 Claude 思考、调用工具、观察结果、决定下一步的过程中持续运行。每次迭代产生一条消息：Claude 的推理、工具调用、工具结果或最终结果。SDK 处理编排（工具执行、上下文管理、重试），你只需要消费这个流。当 Claude 完成任务或遇到错误时，循环结束。

运行 Agent¶

TypeScript：

1

npx tsx agent.ts

Python：

1

python3 agent.py

运行后检查 utils.py，你会看到 Claude 自主完成了以下操作：

• 读取 utils.py 理解代码逻辑
• 分析 边界情况，识别出会导致崩溃的 Bug
• 编辑 文件，添加了处理空列表和空用户的防御性代码

这就是 Agent SDK 的核心价值：Claude 直接执行工具，而不是要求你来实现工具。

基本概念¶

工具（Tools）¶

工具控制 Agent 能做什么。根据你开放的工具组合，Agent 的能力范围也不同：

权限模式（Permission Modes）¶

权限模式控制你希望多大程度的人工监督：

上面的示例使用了 acceptEdits 模式，让 Agent 可以在没有交互式确认的情况下运行。如果你想在运行时让用户确认操作，使用 default 模式并提供一个 canUseTool 回调。

自定义你的 Agent¶

添加网络搜索能力¶

1
2
3
4

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

1
2
3
4

const options = {
  allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
  permissionMode: "acceptEdits"
};

自定义系统提示¶

1
2
3
4
5

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

1
2
3
4
5

const options = {
  allowedTools: ["Read", "Edit", "Glob"],
  permissionMode: "acceptEdits",
  systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
};

启用终端命令执行¶

1
2
3
4

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)

1
2
3
4

const options = {
  allowedTools: ["Read", "Edit", "Glob", "Bash"],
  permissionMode: "acceptEdits"
};

启用 Bash 后，你可以让 Agent 做更复杂的事情，比如 "Write unit tests for utils.py, run them, and fix any failures"。

更多提示词灵感¶

Agent 构建好之后，试试这些不同的提示：

• "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"

故障排除¶

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

Claude Opus 4.7 使用 thinking.type.adaptive 替换了 thinking.type.enabled。如果你选择了 claude-opus-4-7 模型但 SDK 版本较旧，会看到这个错误：

1

API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model..."}

解决方法：升级到 Agent SDK v0.2.111 或更高版本。

API Key not found¶

确保你已在 .env 文件或 shell 环境中设置了 ANTHROPIC_API_KEY 环境变量。

下一步¶

你已经构建了第一个 Agent，接下来可以探索更强大的功能：

• 权限控制 — 精确控制 Agent 的能力边界和审批流程
• Hooks — 在工具调用前后插入自定义逻辑（日志、审计、拦截）
• 会话管理 — 构建多轮对话，恢复和分叉会话
• MCP 服务器 — 连接数据库、浏览器、API 等外部系统
• 配置与部署 — 系统提示、环境变量、生产环境部署