Claude Agent SDK 使用说明

Claude Agent SDK 让你能够构建可以自主读取文件、运行命令、搜索网络、编辑代码等的 AI Agent。

Claude Agent SDK 将驱动 Claude Code 的工具、Agent 循环和上下文管理能力开放为可编程的 Python 和 TypeScript 库。

简单来说，这是一个把 Claude Code 作为库来使用的 SDK，你可以把它嵌入到自己的应用、CI 流水线或自动化脚本中，构建能自主完成复杂任务的 AI Agent。

---

核心能力

SDK 内置了读取文件、运行命令和编辑代码的工具，你的 Agent 无需自己实现工具执行逻辑，可以立即开始工作。主要能力包括：

能力	说明
内置工具	文件读写、终端命令、代码编辑、Web 搜索等
Hooks	在工具调用前后执行自定义逻辑
子 Agent（Subagents）	将大任务分解，并行交给独立的子 Agent 执行
MCP 服务器	连接数据库、浏览器、外部 API 等
权限控制	精细控制 Agent 能做什么、何时需要用户审批
会话管理（Sessions）	构建保持上下文的多轮对话 Agent

---

前提条件

• Node.js 18+（TypeScript）或 Python 3.10+
• 一个 Anthropic 账号，并获取 API Key（在此注册）

---

第一步：安装 SDK

TypeScript

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

TypeScript SDK 会将适用于你当前平台的 Claude Code 二进制文件作为可选依赖一起打包，无需单独安装 Claude Code。

Python

# 使用 pip
pip install claude-agent-sdk

# 或使用 uv（推荐）
uv add claude-agent-sdk

注意：Claude Code CLI 会自动随包一起安装，无需单独安装！SDK 默认使用打包的 CLI。

如果你希望使用系统级安装或指定版本，可以通过 ClaudeAgentOptions(cli_path="/path/to/claude") 指定路径。

---

第二步：配置 API Key

从 Claude Console 获取 API Key，然后在项目目录创建 .env 文件：

ANTHROPIC_API_KEY=your-api-key-here

或直接设置为环境变量：

export ANTHROPIC_API_KEY=your-api-key-here

支持第三方云平台

SDK 也支持通过第三方 API 提供商进行认证：Amazon Bedrock（设置 CLAUDE_CODE_USE_BEDROCK=1 环境变量并配置 AWS 凭证）、Google Vertex AI（设置 CLAUDE_CODE_USE_VERTEX=1）以及 Microsoft Azure（设置 CLAUDE_CODE_USE_FOUNDRY=1）。

⚠️ 重要：除非事先获得 Anthropic 批准，否则不允许第三方开发者在基于 Claude Agent SDK 构建的产品中提供 claude.ai 登录或速率限制。请使用文档中描述的 API Key 认证方式。

---

第三步：运行你的第一个 Agent

以下示例创建一个 Agent，列出当前目录中的文件：

Python

实例

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

async def main():

    async for message in query(

        prompt="What files are in this directory?",

        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),

    ):

        if hasattr(message, "result"):

            print(message.result)

asyncio.run(main())

TypeScript

实例

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

async function main() {

  for await (const message of query({

    prompt: "What files are in this directory?",

    options: { allowedTools: ["Bash", "Glob"] },

  })) {

    if ("result" in message) {

      console.log(message.result);

    }

  }

}

main();

---

实战：构建一个自动修复 Bug 的 Agent

下面通过一个完整示例，演示 Agent SDK 的核心用法。

准备一个有 Bug 的文件

创建 utils.py，包含两处有意为之的 Bug：

实例

def calculate_average(numbers):

    total = 0

    for num in numbers:

        total += num

    return total / len(numbers)   # Bug: 空列表时除以 0

def get_user_name(user):

    return user["name"].upper()   # Bug: user 为 None 时报 TypeError

编写 Agent

创建 agent.py：

实例

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():

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

运行

python agent.py

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

1. 读取了 utils.py 文件
2. 分析了代码逻辑，识别出可能导致崩溃的边界情况
3. 编辑了文件，添加了完善的错误处理

---

核心概念解析

函数 —— Agent 循环的入口

query 是创建 Agent 循环的主要入口点，返回一个异步迭代器，因此你使用 async for 来实时流式获取 Claude 工作时产生的消息。循环在 Claude 完成任务或遇到错误时结束。SDK 负责编排（工具执行、上下文管理、重试），你只需消费这个消息流。

每次迭代会产生一条消息，可能是：

• Claude 的推理过程
• 一次工具调用
• 工具调用结果
• 最终结果

工具（Tools）—— 控制 Agent 能做什么

工具组合	Agent 能力
Read, Glob, Grep	只读分析
Read, Edit, Glob	分析并修改代码
Read, Edit, Bash, Glob, Grep	完整自动化
加上 WebSearch	加入网络搜索能力

权限模式（Permission Modes）—— 控制人工监督程度

模式	行为	适用场景
acceptEdits	自动批准文件编辑，其他操作仍需确认	受信任的开发工作流
dontAsk	拒绝 allowedTools 之外的所有操作	锁定的无人值守 Agent
auto（仅 TypeScript）	模型分类器自动审批/拒绝每个工具调用	带安全护栏的自主 Agent
bypassPermissions	无需提示直接运行所有工具	沙箱化 CI 环境
default	需提供 canUseTool 回调处理审批	自定义审批流程

---

自定义 Agent 行为

添加 Web 搜索

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

添加自定义系统提示

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

允许执行终端命令

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)
# 可以尝试：
# prompt="Write unit tests for utils.py, run them, and fix any failures"

加载项目配置（CLAUDE.md 等）

SDK 构建于与 Claude Code 相同的基础之上，SDK Agent 可以访问相同的基于文件系统的功能：项目说明（CLAUDE.md 和 rules）、技能、Hooks 等。默认情况下 SDK 不加载任何文件系统设置。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit"],
    # "user" 从 ~/.claude/ 加载，"project" 从 ./.claude/ 加载
    setting_sources=["user", "project"],
)

---

错误处理

from claude_agent_sdk import (
    ClaudeSDKError,      # 基础错误
    CLINotFoundError,    # Claude Code 未安装
    CLIConnectionError,  # 连接问题
    ProcessError,        # 进程失败
    CLIJSONDecodeError,  # JSON 解析失败
)

try:
    async for message in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("请先安装 Claude Code")
except ProcessError as e:
    print(f"进程失败，退出码：{e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"响应解析失败：{e}")

---

Agent SDK vs. 其他 Claude 工具

	Agent SDK	Client SDK（Messages API）	Claude Code CLI
使用方式	Python/TypeScript 库	HTTP API 调用	终端命令行工具
工具执行	内置，自动执行	需手动实现	内置，交互式
适用场景	构建自主 Agent、应用集成	一般 LLM 调用	直接编码辅助
状态管理	有状态，支持会话	无状态	有状态，交互式

---

SDK 功能对照表

SDK 还支持 Claude Code 的基于文件系统的配置。若要使用这些功能，需在选项中设置 setting_sources=["project"]（Python）或 settingSources: ['project']（TypeScript）。

功能	说明	位置
Skills（技能）	用 Markdown 定义的专项能力	.claude/skills/*/SKILL.md
Slash Commands	常用任务的自定义命令	.claude/commands/*.md
Memory（记忆）	项目上下文和指令	CLAUDE.md
Plugins（插件）	通过 plugins 选项扩展	通过代码配置

AI 思考中...

JetBrains IDEs 中使用 Claude Code

Claude Code 开发配置