用 Claude Code Agent SDK 快速构建一个能自动读代码、找 bug 并修复的 AI 代理。本快速开始指导你在 Python 或 TypeScript 项目中安装 SDK、创建带缺陷的代码文件，然后通过几行 streaming API 运行自主修复流程。关键操作包括配置 allowedTools（如 Read、Edit、Glob）和 permissionMode（如 acceptEdits），运行后检查文件即可看到改动。如果遇到 API key 找不到或 Opus 4.7 模型报错，可参考文末排查指引。

Claude Code Agent SDK 快速开始：自动读代码找 Bug 并修复

用 Agent SDK 构建一个能读你的代码、发现 bug 并自动修复的 AI 代理，全程无需手动干预。

你将完成：

1. 用 Agent SDK 初始化一个项目
2. 创建一个带隐式 bug 的代码文件
3. 运行一个能自动发现并修复这些 bug 的代理

前置条件

• Node.js 18+ 或 Python 3.10+
• 一个 Anthropic 账号（点击注册）

安装与配置

创建项目目录

新建一个目录用于本快速开始：

mkdir my-agent && cd my-agent

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

安装 Agent SDK 包

根据你使用的语言安装对应的包：

TypeScript：

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

Python（使用 uv）：

uv init && uv add claude-agent-sdk

Python（使用 venv）：

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

TypeScript SDK 内置了你平台对应的 Claude Code 原生二进制文件作为可选依赖，所以你不需要单独安装 Claude Code。

获取 API 密钥并设置环境变量

从 Claude Console 获取 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 的专项指南。

除非事先获得批准，Anthropic 不允许第三方开发者在其产品（包括基于 Claude Agent SDK 构建的代理）中提供 claude.ai 登录或速率限制。请使用本文档描述的 API 密钥认证方式。

创建一个有 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：

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"],  # 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())

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"], // 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}`); // 最终结果
  }
}

这段代码包含三个主要部分：

1. query：创建代理循环的入口点。它返回一个异步迭代器，所以你可以用 async for 或 for await 流式接收消息。完整 API 请参考 Python SDK 文档 或 TypeScript SDK 文档。

2. prompt：你希望 Claude 执行的任务。Claude 会根据任务自动决定使用哪些工具。

3. options：代理的配置。本例中通过 allowedTools 预批准了 Read、Edit 和 Glob，并通过 permissionMode: "acceptEdits" 自动批准文件更改。其他选项包括 systemPrompt、mcpServers 等。所有选项说明见 Python 或 TypeScript。

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

循环内的消息处理过滤出人类可读的输出。如果不加过滤，你会看到包括系统初始化和内部状态在内的原始消息对象，这在调试时有用，但正常使用会显得杂乱。

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

运行代理

你的代理已经准备好了。用以下命令运行：

Python：

python3 agent.py

TypeScript：

npx tsx agent.ts

运行后检查 utils.py，你会看到添加了防御性代码来处理空列表和空用户。你的代理自动完成了以下工作：

1. 读取 utils.py 理解代码
2. 分析逻辑，找出会崩溃的边界情况
3. 编辑文件，添加适当的错误处理

这就是 Agent SDK 的不同之处：Claude 直接执行工具，而不是让你去实现它们。

如果看到 "API key not found"，请确保在 .env 文件或 shell 环境中设置了 ANTHROPIC_API_KEY 环境变量。更多帮助参见 完整排查指南。

尝试其他提示

代理设置完成后，试试不同的提示：

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

自定义代理

你可以通过修改选项来改变代理的行为。这里有几个示例：

添加网页搜索能力：

Python：

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

TypeScript：

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：

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：

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

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

核心概念

工具（Tools） 控制你的代理能做什么：

工具组合	代理能做什么
Read, Glob, Grep	只读分析
Read, Edit, Glob	分析与修改代码
Read, Edit, Bash, Glob, Grep	完全自动化

权限模式 控制你希望有多少人工监督：

模式	行为	适用场景
acceptEdits	自动批准文件编辑和常见文件系统命令，对其他操作询问	受信任的开发工作流
dontAsk	拒绝任何不在 allowedTools 中的操作	锁定式无头代理
auto（仅 TypeScript）	模型分类器批准或拒绝每个工具调用	带安全护栏的自主代理
bypassPermissions	不提示直接运行所有工具	沙盒 CI、完全受信任环境
default	需要提供 canUseTool 回调来处理批准	自定义批准流程

上面的例子使用了 acceptEdits 模式，自动批准文件操作，代理无需交互提示即可运行。如果你希望提示用户批准，请使用 default 模式并提供 canUseTool 回调 来收集用户输入。更多控制见 权限。

常见错误排查

API 错误：thinking.type.enabled is not supported for this model

Claude Opus 4.7 使用 thinking.type.adaptive 替代了 thinking.type.enabled。较老的 Agent SDK 版本在选中 claude-opus-4-7 时会返回以下 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。

下一步

现在你已经创建了第一个代理，可以学习如何扩展其能力并适配你的使用场景：

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

常见问题

运行代理时提示 "API key not found" 怎么解决？

确保你在项目目录的 .env 文件中设置了 ANTHROPIC_API_KEY=your-api-key，或者在终端中执行 export ANTHROPIC_API_KEY=your-api-key。如果使用 .env 文件，需要确保代码在运行时加载了它（例如通过 dotenv 库）。更多排查详见 完整指南。

能不能用第三方 API 提供商（如 Bedrock、Vertex AI）代替 Anthropic 的 API？

可以。Agent SDK 支持 Amazon Bedrock、Claude Platform on AWS、Google Vertex AI 和 Microsoft Azure，通过设置相应的环境变量并配置提供商凭证即可。具体步骤见各提供商的配置指南（链接在本文安装与配置部分）。使用这些第三方提供商时不需设置 ANTHROPIC_API_KEY。

使用 Claude Opus 4.7 时报 "thinking.type.enabled" 错误怎么办？

这是旧版 Agent SDK 与 Opus 4.7 的兼容问题。升级 SDK 版本至 v0.2.111 或更高即可解决。如果无法升级，请改用其他模型（如 claude-sonnet-4-20250514）。