Agent SDK 快速上手

用 Agent SDK 构建一个能读你的代码、找出 bug 并修复它们的 AI 智能体，全程无需人工干预。你将：设置一个使用 Agent SDK 的项目；创建一个带有 bug 的文件；运行一个自动找到并修复 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

tsx 直接运行 TypeScript 文件。如果你的项目用 CommonJS，把你的智能体脚本命名为 agent.mts 而不是 agent.ts：.mts 扩展名让 tsx 把该文件当作 ES 模块，所以不必把整个项目转成 ES 模块，顶层 await 也能工作；在本快速开始后面的创建和运行步骤里，用 agent.mts 代替 agent.ts。

Python（uv）： 安装 uv（一个自动处理虚拟环境的快速 Python 包管理器），然后初始化项目并添加 SDK：

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 获取 API key，然后在你要运行智能体的 shell 里把它设为环境变量。macOS / Linux：

export ANTHROPIC_API_KEY=your-api-key

Windows（PowerShell）：

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

SDK 从运行你智能体的进程的环境里读取该密钥；它不会自动加载 .env 文件。如果你把密钥放在 .env 文件里，在调用 SDK 之前自己加载它，例如用 dotenv 包。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 Cloud 的 Agent Platform：设置环境变量 CLAUDE_CODE_USE_VERTEX=1 并配置 Google Cloud 凭据。
• Microsoft Foundry：设置环境变量 CLAUDE_CODE_USE_FOUNDRY=1 并配置 Azure 凭据。

详情见各提供商的设置指南。注意：除非事先获得批准，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：calculate_average([]) 因除以零而崩溃；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 在 Claude 工作时流式接收消息。完整 API 见 Python 或 TypeScript SDK 参考里的 query。
2. prompt：你想让 Claude 做什么。Claude 根据任务自己判断用哪些工具。
3. options：智能体的配置。这个例子用 allowedTools 预先批准 Read、Edit 和 Glob，用 permissionMode: "acceptEdits" 自动批准文件改动；其他选项包括 systemPrompt、mcpServers 等，全部选项见 Python 或 TypeScript 的参考。

async for 循环在 Claude 思考、调用工具、观察结果并决定下一步做什么期间持续运行。每次迭代产出一条消息：Claude 的推理、一次工具调用、一个工具结果，或最终结果。SDK 处理编排、工具执行、上下文管理和重试，所以你只消费这个流；当 Claude 完成任务或遇到错误时循环结束。循环里的消息处理过滤出人类可读的输出：不过滤的话，你会看到原始消息对象，包括系统初始化和内部状态，这对调试有用，但其他时候很嘈杂。

注意：这个例子用流式输出实时展示进度。如果你不需要实时输出（例如后台作业或 CI 流水线），可以一次收集所有消息；详情见「流式输入与单轮模式」。

运行你的智能体

你的智能体准备好了。用下面的命令运行它：

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，你会看到处理空列表和空用户的防御性代码。你的智能体自主地：读取 utils.py 来理解代码；分析逻辑并找出会崩溃的边界情况；编辑文件，加入适当的错误处理。这就是 Agent SDK 的不同之处：Claude 直接执行工具，而不是让你去实现它们。

如果你看到 Not logged in 或 Invalid API key 这样的认证错误，确认你在运行智能体的 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 = 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"。这些片段都是在同一个选项对象上设置字段；更多信息见「配置你的智能体」。

关键概念

工具控制你的智能体能做什么：

权限模式控制你想要多少人工监督。SDK 按固定顺序把当前模式与你的允许和拒绝规则一起评估，见权限页的「权限如何被评估」；完整的模式列表、各自的行为以及何时使用，见智能体循环页的权限模式部分。

下一步

创建了第一个智能体之后，了解如何扩展它的能力并让它适应你的用例：

• 配置你的智能体：组合选项对象，并找到涵盖每个设置的页面。
• 权限：控制你的智能体能做什么以及何时需要批准。
• Hooks：在工具调用之前或之后运行自定义代码。
• 会话：构建保持上下文的多轮智能体。
• MCP 服务器：连接数据库、浏览器、API 和其他外部系统。
• 托管：把智能体部署到 Docker、云和 CI/CD。
• 示例智能体（claude-agent-sdk-demos 仓库）：查看完整示例，如邮件助手、研究智能体等。
• 排障：修复 CLI 启动失败或退出、或结果到达时没有结构化输出时的错误。