Agent SDK 快速入门：5 分钟构建修 Bug 智能体

本文是对 Claude Agent SDK 官方文档「Quickstart」页面的中文整理，完整与最新内容以原文为准：https://code.claude.com/docs/en/agent-sdk/quickstart

概述

使用 Agent SDK 构建一个能够读取代码、发现 Bug 并自动修复的 AI 智能体，全程无需人工干预。

本教程将完成：

1. 搭建一个包含 Agent SDK 的项目
2. 创建一个含有 Bug 的代码文件
3. 运行一个能自动发现并修复 Bug 的智能体

前置条件

• Node.js 18+ 或 Python 3.10+
• 一个 Anthropic 账号。如果还没有，可在 platform.claude.com 注册。

环境搭建

1. 创建项目目录

mkdir my-agent
cd my-agent

对于你自己的项目，SDK 可以在任意目录下运行；默认情况下它可以访问该目录及其子目录下的文件。

2. 安装 SDK

根据所使用的语言安装对应的 Agent SDK 包：

TypeScript（新项目）

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。

TypeScript（已有项目）

npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

如果项目使用 CommonJS，请将智能体脚本命名为 agent.mts 而非 agent.ts。.mts 后缀会让 tsx 将该文件当作 ES 模块处理，从而无需把整个项目转换为 ES 模块也能使用顶层 await。后续步骤中用 agent.mts 代替 agent.ts。

Python（使用 uv）

uv 是一个能自动管理虚拟环境的快速 Python 包管理器：

uv init
uv add claude-agent-sdk

Python（使用 pip）

创建并激活虚拟环境，然后安装包。

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。

说明：TypeScript 和 Python SDK 都内置了原生的 Claude Code 二进制文件，因此大多数安装无需单独安装 Claude Code。但以下情况不会带有内置二进制：

• 如果 pip 安装的是 Python SDK 的源码分发包而非平台 wheel 包（例如在 ARM64 Windows 上），则不会内置二进制。此时需要原生安装 Claude Code,Python SDK 会在 PATH 中找到它。
• TypeScript SDK 通过 npm 的可选依赖安装其二进制文件，如果安装时跳过了可选依赖（例如 npm ci --omit=optional），即便平台受支持也不会获得二进制文件。此时应在不跳过可选依赖的情况下重新安装，或原生安装 Claude Code 并将其路径设置到 pathToClaudeCodeExecutable。

3. 设置 API Key

从 Claude Console（platform.claude.com）获取一个 API Key，并在运行智能体的 shell 中将其设为环境变量：

macOS / Linux:

export ANTHROPIC_API_KEY=your-api-key

Windows(PowerShell):

$env:ANTHROPIC_API_KEY = "your-api-key"

SDK 会从运行智能体的进程环境中读取该 Key，不会自动加载 .env 文件。如果你把 Key 存放在 .env 文件中，需要在调用 SDK 之前自行加载（例如使用 dotenv 包）。

SDK 还支持通过第三方 API 提供方进行鉴权：

详情参见对应的搭建指南：Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform、Microsoft Foundry。

说明：除非事先获得批准，Anthropic 不允许第三方开发者在其产品（包括基于 Claude Agent SDK 构建的智能体）中提供 claude.ai 登录或其速率限制。请使用本文所述的 API Key 鉴权方式。

创建一个含 Bug 的文件

本教程将带你构建一个能发现并修复代码 Bug 的智能体。首先需要一个含有若干故意留下的 Bug 的文件供智能体处理。在 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()

这段代码存在两个 Bug:

1. calculate_average([]) 会因除以零而崩溃
2. get_user_name(None) 会因 TypeError 而崩溃

构建一个能发现并修复 Bug 的智能体

如果使用 Python SDK，创建 agent.py；如果使用 TypeScript，创建 agent.ts（若现有项目使用 CommonJS，则使用 agent.mts）：

Python

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


async def main():
    # 智能体循环:在 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"],  # 自动批准这些工具
            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())

TypeScript

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

// 智能体循环:在 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"], // 自动批准这些工具
    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：创建智能体循环的主入口。它返回一个异步迭代器，因此使用 async for(Python)/ for await（TypeScript）来流式接收 Claude 工作过程中的消息。完整 API 参见 Python 或 TypeScript SDK 参考。
2. prompt：希望 Claude 完成的任务。Claude 会根据任务自行判断使用哪些工具。
3. options：智能体的配置项。本例中用 allowedTools/allowed_tools 预先批准 Read、Edit、Glob，并用 permissionMode: "acceptEdits" / permission_mode="acceptEdits" 自动批准文件改动。其他可用选项还包括 systemPrompt、mcpServers 等，完整列表参见 Python 或 TypeScript。

async for / for await 循环会在 Claude 思考、调用工具、观察结果、决定下一步的过程中持续运行。每次迭代产出一条消息：可能是 Claude 的推理、一次工具调用、一次工具结果，或最终结果。SDK 负责编排调度、工具执行、上下文管理与重试，你只需消费消息流。当 Claude 完成任务或遇到错误时循环结束。

示例中对消息做了过滤，只展示人类可读的输出。如果不过滤，会看到原始的消息对象，包括系统初始化和内部状态信息——这些信息调试时有用，但平时会显得冗余。

说明：本例使用流式输出以实时展示进度。如果不需要实时输出（例如用于后台任务或 CI 流水线），也可以一次性收集所有消息。详见流式 vs. 单轮模式。

运行智能体

智能体已经就绪，使用以下命令运行：

TypeScript

npx tsx agent.ts

如果脚本名为 agent.mts，则运行 npx tsx agent.mts。

Python(uv)

uv run agent.py

Python(pip)

虚拟环境仍处于激活状态下：

python agent.py

运行过程中，智能体会打印它的推理过程和每一次工具调用，最终以 Done: success 结束。运行完成后查看 utils.py，会看到已添加了处理空列表和空用户的防御性代码。你的智能体自主完成了：

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

这正是 Agent SDK 的不同之处：Claude 直接执行工具，而不是要求你自己去实现这些工具调用逻辑。

说明：如果看到「API key not found」错误，请确认已在运行智能体的 shell 中设置了 ANTHROPIC_API_KEY 环境变量。SDK 不会自动加载 .env 文件。更多帮助参见完整故障排查指南。

尝试其他提示词

智能体搭建完成后，可以尝试不同的提示词：

• "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 来调整智能体的行为，以下是几个示例。

添加网络搜索能力：

Python:

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

TypeScript:

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

给 Claude 指定自定义系统提示词：

Python:

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

TypeScript:

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

在终端中运行命令：

Python:

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

TypeScript:

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

开启 Bash 后，可以尝试："Write unit tests for utils.py, run them, and fix any failures"

核心概念

工具（Tools） 决定了智能体能做什么：

权限模式（Permission modes） 决定了你希望有多少人工监督。SDK 会按固定顺序综合评估当前生效的模式以及你设置的允许/拒绝规则，具体顺序见权限评估方式。完整的模式列表、行为说明及使用场景，参见智能体循环工作原理中的 Permission mode 一节。

下一步

创建完第一个智能体后，可以继续学习如何扩展其能力并按需求定制：

• Permissions（权限）：控制智能体能做什么，以及何时需要人工批准
• Hooks（钩子）：在工具调用前后运行自定义代码
• Sessions（会话）：构建能维持上下文的多轮对话智能体
• MCP servers（MCP 服务器）：连接数据库、浏览器、API 等外部系统
• Hosting（托管部署）：将智能体部署到 Docker、云平台和 CI/CD
• 示例智能体：查看完整示例，如邮件助手、研究智能体等