Claude Agent SDK 深度入门指南

Geek技术前线
0 阅读27分钟

从零基础到精通掌握，利用 Claude Code 能力构建生产级 AI Agent 应用

前言

telegram-cloud-photo-size-5-6240098508111285629-y.jpg

当你读到这份文档的时候，很可能已经对大语言模型（LLM）有了一定的了解，甚至已经在使用 Claude、ChatGPT 或者其他 AI 工具来辅助日常工作和编程开发。你或许已经体验过让 AI 帮你写代码、润色文章、解答问题的便利。但如果你希望更进一步——不只是单次问答，而是让 AI 能够像一位真正的助手一样，自主地完成复杂任务：阅读你的代码库，理解项目结构、执行命令、修改文件、调用外部工具、甚至与其他 AI Agent 协作完成更大规模的任务——那么，你需要的不仅仅是聊天界面，而是一套完整的 Agent 开发框架。

这正是 Claude Agent SDK 存在的意义。

Claude Agent SDK（全称 Anthropic Claude Agent SDK，发布时原名为 Claude Code SDK，后正式更名）是由 Anthropic 公司官方推出的开发工具包，它的核心思想非常简单但极其强大：将 Claude Code——那个能够自主操作代码库、自动化完成编程任务的 CLI 工具——的能力，以编程库的形式开放给所有开发者。你可以把 SDK 理解为 Claude Code 的"编程接口"，它让你能够在自己的应用程序中，像使用 Claude Code 一样，驱动 Claude 完成各种复杂的工作。

这份文档的目标，是带领你从完全不了解 Claude Agent SDK，到能够熟练地使用它构建各种实用的 AI Agent 应用。我会从最基础的概念讲起，逐步深入到高级特性——包括 Hooks 钩子系统、子 Agent、Model Context Protocol（MCP）集成、权限管理等。每个章节都配有详细的解释、适用场景分析和实践建议。无论你是一位想构建自动化工作流的工程师，还是希望将 AI 能力集成到自己产品中的开发者，这篇文章都将为你提供系统化的指导。

在开始之前，让我先说明一下这份文档的阅读建议。Claude Agent SDK 同时支持 TypeScript（JavaScript）和 Python 两种语言，两者在 API 设计上高度一致，只是语法风格不同。我会在关键章节同时展示两种语言的示例，帮助你理解其中的对应关系。在行文中，除非特别说明，两种语言的 API 名称和参数含义基本一致，可以类比迁移。这份文档不预设你的语言偏好，但默认以 TypeScript 作为主要示例语言，因为 SDK 最初就是以 TypeScript 形态发布的。

第一部分：基础入门

第一章：Claude Agent SDK 是什么

1.1 背景与动机

在 Claude Agent SDK 出现之前，开发者如果想在程序中调用 Claude 的能力，主要依赖两种方式。第一种是直接调用 Messages API，通过 HTTP 请求向 Claude 的服务端点发送一个包含消息历史的对话请求，然后接收一个完整的文本回复。这是一种"问答式"的交互模式——你问一句，AI 答一句，没有状态保留，没有工具调用，也谈不上真正的"自动化"。

第二种是利用 Function Calling（函数调用）功能，它允许模型在回复中输出结构化的工具调用指令，开发者需要自己解析这些指令、执行相应的操作（如读取文件、执行 Shell 命令等），然后将结果反馈给模型，进入下一轮对话。这比纯问答模式进了一步，但仍然需要开发者自己实现整个循环的 orchestration（编排）逻辑，包括：如何管理对话历史、如何处理工具调用的超时和错误、如何在多轮对话中维护上下文窗口的预算、如何实现流式输出让用户看到实时的进度——这些工作既繁琐又容易出错，每做一次都要重复造轮子。

Claude Agent SDK 的诞生，正是为了解决这个根本性的问题。它将 Claude Code 在命令行环境中积累多年的 Agent 框架能力，抽象成一套简洁的编程接口，让开发者无需关心底层编排的细节，就能轻松拥有完整的 Agent 能力。

1.2 与其他 Claude 开发工具的关系

Anthropic 为开发者提供了多个不同层次的工具，理解它们之间的关系，有助于你判断什么时候该用 Agent SDK，什么时候用其他工具更合适。

Messages API 是最底层的接口，它只负责发送消息和接收回复，不包含任何 Agent 逻辑。你可以把 Messages API 理解为"裸的"语言模型接口——它给你原始的 token 输出，剩下的全部交给你自己组织。

Client SDK（如官方 Python SDK anthropic 和 JavaScript SDK @anthropic-ai/sdk）在 Messages API 之上做了一层封装，提供了客户端请求处理、流式响应、认证管理等功能，但同样不包含 Agent 循环。你仍然需要自己管理对话历史、自己实现工具调用的解析逻辑。

Claude Agent SDK 则在 Client SDK 基础上，进一步封装了完整的 Agent 循环逻辑，包括：内置工具的执行环境、上下文字符窗口的自动管理（自动压缩、自动遗忘策略）、流式消息的标准化输出，子 Agent 的调度机制、Hook 钩子系统、MCP 工具的集成能力，以及会话的持久化和恢复功能。这些能力在 Messages API 和 Client SDK 中是完全不存在的。

用一句话来概括它们的关系：Messages API 给你"大脑"，Client SDK 给你"神经网络"，而 Agent SDK 给你一个完整的"智能体"。Messages API 告诉你"怎么说"，Client SDK 帮你"说出来"，Agent SDK 则让 AI 真正"做起来"。

1.3 核心设计哲学

Claude Agent SDK 在设计上遵循了几个重要的原则，理解这些原则能帮助你更好地使用这个工具。

第一是"工具优先"的设计理念。 在 Agent SDK 中，工具（Tools）不是可选项，而是整个框架的核心。每个 Agent 的能力边界，很大程度上由它可用的工具集合决定。SDK 内置了大量实用工具（文件读写、命令执行、网络搜索等），同时支持通过 MCP 协议接入无限扩展的外部工具生态。

第二是"流式输出"作为默认交互模式。 Agent SDK 的核心入口函数 query() 返回的是一个异步生成器（AsyncGenerator），它以流式的方式逐步输出 Agent 执行过程中的各类消息——包括模型正在进行的推理思考、工具调用的请求和结果、错误警告、以及最终的成功或失败结论。这种设计让实时观察 Agent 的工作状态成为可能，也为构建具有良好用户体验的应用提供了基础。

第三是"安全第一"的权限模型。 Claude Agent SDK 继承了 Claude Code 在 CLI 环境中积累的安全设计经验，提供了一套多层次的权限评估机制。默认情况下，任何可能产生副作用的操作（写文件、执行命令、网络请求等）都需要明确的授权。开发者可以精细地配置允许和禁止的工具范围，也可以在完全不干扰 Agent 工作的前提下，通过 Hook 系统对关键操作进行监控和审计。

第四是"渐进式复杂度"的配置理念。 Agent SDK 鼓励从小处着手，逐步增加复杂性。一个最简单的 Agent 可能只需要三行代码就能运行——传入一个提示词和几个基本配置。随着需求的增长，你可以逐步添加 MCP 服务器，子 Agent、自定义 Hook、权限规则、会话持久化等高级功能。每一个高级特性都是可选的，不会增加简单场景下的使用成本。

1.4 SDK 的技术架构

从技术实现的角度，Claude Agent SDK 的架构可以大致分为四个层次。

最底层是 Claude 官方的 Messages API（由 Client SDK 封装），负责与 Claude 的大语言模型进行通信，包括认证、超时重试、流量控制等底层细节。

在它之上是 Agent 循环引擎（Agent Loop Engine），这是 SDK 的核心。它负责管理多轮对话的执行流程：发送请求给模型、接收模型输出、解析工具调用、执行工具、将结果反馈给模型，直到任务完成或达到某个终止条件。循环引擎还负责管理上下文窗口的压缩（Compaction）逻辑——当对话历史变得太长时，引擎会自动对历史进行摘要，腾出空间给新的交互。

第三层是 工具系统（Tools System）。工具系统管理所有可用工具的定义和执行，包括 SDK 内置的 Built-in Tools（Read、Edit、Bash、Glob、Grep、WebSearch 等），以及通过 MCP 协议接入的外部工具。工具系统还负责工具调用结果的格式化——无论工具执行成功还是失败，结果都会被标准化为结构化的内容块（Content Block），无缝地插入到 Agent 的对话历史中。

最顶层是 开发者接口层（Developer Interface），也就是你直接打交道的那些函数和类，包括 query() 函数、SDKSession 接口、各种配置选项（Options）、Hook 回调接口，以及会话管理相关的工具函数。

1.5 版本与发布状态

根据本文档撰写时的最新信息，Claude Agent SDK 的稳定版本为 0.2.x（以 npm 上的 @anthropic-ai/claude-agent-sdk 为准），同时存在一个标记为 unstable_v2 的新一代 API 预览版本（V2 Session API）。V2 版本重新设计了会话管理接口，将原来单一的 query() 生成器拆分为独立的 send() 和 stream() 方法，支持多轮对话和更细粒度的会话控制。

稳定版和 V2 预览版可以共存于同一个项目中，你可以在简单场景下使用稳定的 query() 函数，在需要更复杂会话管理的场景下尝试 V2 API。需要注意的是，V2 API 带有 @alpha 标记，意味着它的接口可能在未来版本中发生变化，生产环境使用前请仔细评估。

SDK 的发布节奏与 Claude 模型本身的更新紧密相关。每当 Anthropic 发布新的模型版本（如从 Claude 3.5 升级到 Claude 3.7，再到 Claude 4.6），SDK 通常会随之更新以支持新模型的特性（如 Extended Thinking 自适应思考、新的 Token 预算控制等）。

第二章：快速上手——你的第一个 Agent

2.1 环境准备

在开始编写代码之前，你需要确保开发环境中满足以下基本要求。

操作系统方面，SDK 可以在 macOS、Linux 和 Windows（通过 WSL 或 PowerShell）上运行。建议使用 macOS 或主流 Linux 发行版以获得最佳兼容性。

运行时环境方面，TypeScript SDK 需要 Node.js 18 或更高版本，或者 Bun 运行时。Python SDK 需要 Python 3.10 或更高版本。Node.js 的版本管理推荐使用 nvm（Node Version Manager），这样可以方便地在不同项目间切换不同的 Node.js 版本。

包管理工具方面，TypeScript 项目可以使用 npm、yarn 或 pnpm。Python 项目可以使用 pip、uv 或 poetry。Anthropic 官方推荐使用 uv 作为 Python 包管理器，因为它的安装速度和依赖解析效率都明显优于传统的 pip。

代码编辑器方面，推荐使用 VS Code 或 Cursor，并安装相应的语言扩展（TypeScript/Python）。这些编辑器能够提供良好的类型提示和代码补全功能，提升开发体验。

最后，你需要有一个 Anthropic API Key。访问 Anthropic Console（console.anthropic.com），注册一个账号（如果还没有的话），然后在 API Keys 页面创建一个新的 API Key。创建完成后，将密钥妥善保存，不要泄露给他人，也不要将其提交到代码仓库中。

2.2 安装 SDK

以 npm 项目为例，在你的项目目录中执行以下命令来安装 SDK。

对于 TypeScript 项目：

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

对于 Python 项目：

pip install anthropic-agent-sdk

或者使用 uv：

uv add anthropic-agent-sdk

安装完成后，你可以通过查看 package.json（TypeScript）或 pyproject.toml（Python）来确认 SDK 的版本。

2.3 配置 API 密钥

Claude Agent SDK 需要通过环境变量或配置选项来获取 API 密钥。最安全、最推荐的方式是将 API 密钥设置为环境变量，这样密钥不会出现在源代码中。

在 macOS 或 Linux 上，你可以将以下内容添加到 ~/.bashrc 或 ~/.zshrc 文件中：

export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx-xxxxxxxxxxxxxxxx"

如果你是在项目中管理环境变量（推荐使用 .env 文件配合 python-dotenv 或 dotenv 包），创建一个 .env 文件：

ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxx-xxxxxxxxxxxxxxxx

然后在项目代码的入口处加载它。在 TypeScript 项目中，可以使用 dotenv 包：

import dotenv from "dotenv";
dotenv.config();

在 Python 项目中：

from dotenv import load_dotenv
load_dotenv()

2.4 第一个示例：自动化代码审查

让我们用一个具体的例子来感受 Agent SDK 的工作方式。假设你的项目里有一个 Python 文件 utils.py，其中包含一些隐藏的 bug。作为第一个 Agent，我们让它来审查这个文件，找出并修复这些问题。

首先，在项目目录下创建 utils.py 并写入以下有 bug 的代码：

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

这段代码有两个问题：calculate_average([]) 会因为除数为零而崩溃，get_user_name(None) 会因为尝试访问 None 的属性而抛出 TypeError。

接下来，创建 agent.ts（TypeScript）或 agent.py（Python），内容如下：

import { query, ClaudeAgentOptions, AssistantMessage, ResultMessage } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  async for (const message of query({
    prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
    options: new ClaudeAgentOptions({
      allowedTools: ["Read", "Edit", "Glob"],
      permissionMode: "acceptEdits",
    }),
  })) {
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if (block.type === "text") {
          console.log(block.text);
        }
        if (block.type === "tool_use") {
          console.log(`Tool: ${block.name}`);
        }
      }
    }
    if (message.type === "result" && message.subtype === "success") {
      console.log("Done!");
    }
  }
}

main().catch(console.error);

Python 版本的逻辑完全相同，只是语法上的差异：

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(
            allowedTools=["Read", "Edit", "Glob"],
            permissionMode="acceptEdits"
        )
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print("Done!")

asyncio.run(main())

运行这个 Agent：

npx tsx agent.ts    # TypeScript
python agent.py     # Python

你会看到 Agent 逐步输出的过程——它先读取 utils.py，分析代码逻辑，识别出两个 bug，然后依次修改代码。最后，检查修复后的文件，你会看到 Agent 添加了对空列表和 None 值的处理逻辑。

2.5 运行结果的解读

当你运行上面的示例时，query() 返回的异步生成器会按顺序产出一系列消息。理解这些消息的类型和含义，是掌握 Agent SDK 的基础。

AssistantMessage 是最常见的一类消息，它代表 Claude 的回复内容。当消息类型为 "assistant" 时，message.content 中包含了多个内容块（Content Block），可能是文本（text）、工具调用（tool_use）或思考内容（thinking_block）等。

ResultMessage 则在 Agent 完成任务后发出，其 subtype 可以是 "success" 或 "error"，分别表示任务成功完成或遇到了错误。

除了这两类主要消息外，还有系统消息（SDKSystemMessage）报告初始化状态、权限请求消息（SDKPermissionRequest）请求用户批准某项操作、Hook 消息（SDKHookProgressMessage）反映钩子函数的执行进度等。在实际开发中，你通常只需要关心几类关键消息，其他消息可以按需过滤或忽略。

第三章：核心配置项详解

3.1 query() 函数的完整签名

query() 是 Agent SDK 的核心入口函数，它负责启动一个完整的 Agent 执行循环。理解它的所有配置项，是用好 SDK 的关键。

query() 的核心参数分为两个部分：prompt（提示词）和 options（配置选项）。提示词是你给 Agent 的任务描述，可以是一个简单的句子，也可以是一段详细的指令。Agent 会根据提示词来决定使用哪些工具、按照什么顺序执行操作。

options 参数是一个配置对象，包含数十个可选的配置项。下面我们逐一详解最重要的配置项。

3.2 allowedTools 和 disallowedTools

allowedTools 是最常用的配置项之一，它定义了一份"白名单"，告诉 Agent 哪些工具可以使用。当你在配置中指定 allowedTools: ["Read", "Edit", "Glob"] 时，Agent 就只会看到和使用这三个工具，其他工具（如 Bash、WebSearch 等）对它来说是不可见的。

这个设计看似限制，实际上非常有价值。在很多应用场景中，你不希望 Agent 执行某些高风险操作（如删除文件、执行系统命令），通过 allowedTools 你可以精确控制 Agent 的能力边界。只给它必要的工具，不要给它多余的权力——这是 Agent 安全设计的基本原则。

与白名单对应的是 disallowedTools，它定义了一份"黑名单"，明确禁止 Agent 使用某些工具。黑名单的优先级高于白名单，即使某个工具出现在 allowedTools 中，只要它也出现在 disallowedTools 中，就一定会被阻止。这个机制在有多层安全要求的场景下特别有用。

特别值得注意的是，allowedTools 和 disallowedTools 控制的是工具的"可用性"，但并不等于"自动授权"。即使一个工具出现在 allowedTools 中，它在执行前仍然可能需要用户授权（除非配合 permissionMode 使用）。这与权限评估流程中的多个检查点有关。

3.3 permissionMode 权限模式

permissionMode 控制 Agent 执行工具时如何获取权限。Claude Agent SDK 提供了五种权限模式，每种模式有不同的适用场景。

模式说明适用场景
"default"标准权限行为，未授权工具通过 canUseTool 回调请求授权需要用户确认的开发测试场景
"acceptEdits"自动批准所有文件编辑操作受信任代码库中的快速自动化重构
"bypassPermissions"绕过所有权限检查完全隔离的沙盒环境，谨慎使用
"dontAsk"所有未预授权的工具直接拒绝固定功能的自动化 Agent
"plan"禁止任何工具执行，Agent 只分析不修改只读分析场景（代码审查）
"auto"实验性，模型自主分类决定批准或拒绝特定 Enterprise 客户场景

3.4 cwd 和 additionalDirectories

cwd 参数指定 Agent 的工作目录。在没有特殊设置的情况下，Agent 只能访问这个目录及其子目录中的文件。additionalDirectories 则可以额外扩展 Agent 可访问的目录范围。

这两个参数的组合使用，可以实现灵活的目录隔离策略。例如，你可以把工作目录设置为一个专门的沙盒目录，同时通过 additionalDirectories 授予 Agent 只读访问某些敏感目录（如系统配置文件）的权限。

3.5 systemPrompt 和系统提示词

systemPrompt 允许你为 Agent 设置额外的系统级提示词。系统提示词的内容会插入到 Claude 的系统提示中，影响它的行为模式、角色设定和专业领域定位。

一个常见的用法是给 Agent 设定特定的角色或行为规范。例如，如果你的 Agent 是用来审查代码安全的，可以在 systemPrompt 中强调它应该特别关注SQL注入、跨站脚本等安全漏洞；如果 Agent 是用来写测试用例的，可以在提示词中规定测试覆盖率的标准和测试命名规范。

与 systemPrompt 相关的还有一个 initialPrompt 配置项，它用于在 Agent 启动时自动注入一段初始的用户消息。这在需要 Agent 以某个特定状态开始执行的场景中很有用。

3.6 maxTurns 最大回合数

maxTurns 控制 Agent 的最大"回合数"。一个回合（Turn）指的是 Agent 调用一次工具并获得结果的过程。如果达到了最大回合数，Agent 会停止工作并返回当前状态，即使任务还没有完成。

这个参数是防止 Agent 进入"无限循环"或"过度工作"的重要保护机制。在实际生产环境中，建议始终设置一个合理的 maxTurns 上限，根据任务的预期复杂度来估算。

3.7 maxBudgetUsd 成本预算

maxBudgetUsd 为单次查询设置一个以美元为单位的最大预算。当累计的 API 费用接近这个预算时，Agent 会优雅地停止工作。

在实际应用中，maxBudgetUsd 和 maxTurns 通常需要配合使用。maxTurns 防止 Agent 在工具调用层面无限循环，maxBudgetUsd 防止在 Token 消耗层面失控。

3.8 effort 努力程度

effort 参数控制 Agent 在响应时的"努力程度"，可以设置为 "low"、"medium"、"high" 或 "max"。这个参数与 Claude 模型自身的 Adaptive Thinking（自适应思考）能力相结合，指导模型在推理过程中投入多少深度思考。

设置为 "low" 时，Agent 会快速做出决策，适合简单明确的任务。设置为 "max" 时，Agent 会在每个决策点进行更深入的分析和自我反思，适合复杂、需要谨慎判断的任务。

3.9 env 环境变量传递

env 参数允许你向 Agent 运行时环境传递额外的环境变量。这些变量对 Agent 是可见的（通过 process.env 在 TypeScript 中，或 os.environ 在 Python 中），Agent 可以像在正常 Shell 环境中一样读取它们。

这个机制的一个典型应用场景是传递外部服务的 API 密钥。例如，Agent 在分析 GitHub 仓库时需要访问 GitHub API，你就可以通过 env 传入 GITHUB_TOKEN。

3.10 mcpServers MCP 服务器配置

mcpServers 参数用于配置 Model Context Protocol（MCP）服务器。MCP 是一种让 Agent 与外部工具和服务进行标准化交互的协议。

3.11 hooks 钩子回调配置

hooks 参数允许你在 Agent 执行过程中的特定"钩子点"插入自定义逻辑。Agent SDK 定义了数十种钩子事件，覆盖了从工具调用前后的审查、用户提示词的注入、Agent 启动和停止的生命周期事件、会话压缩时机等方方面面。

第二部分：核心概念深度解析

第四章：Agent 循环的工作原理

4.1 什么是 Agent 循环

当你向 Agent SDK 发送一个提示词并启动查询时，背后发生的事情远比"发送请求、等待回复"要复杂得多。Agent SDK 的核心是一个持续运转的循环系统——这就是我们常说的"Agent 循环"（Agent Loop）。

理解 Agent 循环的工作原理，是掌握 Agent SDK 的关键所在。它不仅能帮助你更好地设计提示词和配置选项，还能在调试和优化 Agent 行为时提供重要的思路。

4.2 循环的七个阶段

一个典型的 Agent 循环执行周期，可以分为以下七个阶段：

第一阶段：初始化（Initialization）

当你调用 query() 时，SDK 首先进行初始化工作。这包括：加载配置参数、解析工具定义，建立与 Claude API 的连接（如有必要还会初始化 MCP 服务器）。

第二阶段：决策（Decision Making）

Claude 模型分析当前收到的所有信息——包括用户的提示词、对话历史、可用工具的定义和描述——然后决定下一步应该做什么。模型的输出有两种可能：一是直接生成一个文本回复并结束，二是生成一个或多个工具调用请求（Tool Use）。

第三阶段：工具调用解析（Tool Call Parsing）

如果模型决定调用工具，SDK 会解析模型输出中的工具调用请求。解析的内容包括：要调用哪个工具、传递给工具的参数是什么。SDK 还会检查是否存在多个工具并行调用的情况。

第四阶段：权限检查（Permission Check）

在真正执行工具之前，SDK 需要确认这次调用是被允许的。权限检查按照明确的优先级顺序进行：Hooks → Deny 规则 → 权限模式 → Allow 规则 → canUseTool 回调。

第五阶段：工具执行（Tool Execution）

权限检查通过后，SDK 执行实际的工具逻辑。内置工具由 SDK 内置的执行引擎完成；MCP 工具由对应的 MCP 服务器处理。

第六阶段：结果反馈（Result Feedback）

工具执行完成后，结果被包装成标准化的内容块，追加到对话历史中。然后，控制权交回给 Claude 模型，进入下一个决策周期。

第七阶段：终止判断（Termination Check）

每次循环结束时，SDK 都会检查是否应该终止 Agent 的运行。可能触发终止的条件包括：模型输出了结束标记、达到了最大回合数 maxTurns、触发了成本预算上限 maxBudgetUsd、用户主动取消了操作、或者某个 Hook 回调返回了阻止继续执行的指令。

如果没有任何终止条件满足，循环回到第二阶段，继续下一轮迭代。

4.3 上下文窗口与自动压缩

上下文窗口（Context Window）是 Agent 循环中一个特别需要关注的概念。Claude 模型有一个最大可以处理的 Token 数量（取决于具体模型，通常在 20 万到 200 万 Token 之间）。

当上下文窗口快被填满时，Claude Agent SDK 会执行一个"压缩"（Compaction）操作。压缩的逻辑是对历史消息进行摘要，保留最重要的信息，而压缩掉中间过程中的详细推理步骤。

SDK 提供了多种 Hook 事件与压缩机制交互。PreCompact 钩子在压缩发生之前触发，PostCompact 钩子在压缩完成后触发。

4.4 流式消息的实时感知

Claude Agent SDK 的 query() 返回的是一个异步生成器（AsyncGenerator），这意味着消息不是等到整个 Agent 任务完成后才一次性返回，而是实时地、逐条地推送给调用方。

第五章：内置工具系统

5.1 工具在 Agent 系统中的地位

如果把 Agent 循环比作一个人类助手的工作流程，那么工具就是这位助手的"手"和"感官"。正是工具系统让 Agent 具备了行动能力——它可以读取文件了解现状，可以执行命令采取行动，可以搜索网络获取信息，可以向外部系统发送消息。

5.2 Read 工具

Read 工具是最基础也最常用的工具之一。它允许 Agent 读取指定路径的文件内容。当 Agent 需要分析一个代码文件时，它通常首先使用 Read 来获取文件内容。

5.3 Edit 和 Write 工具

Edit 工具用于对已有文件进行局部修改，而 Write 工具用于创建新文件或完全覆盖一个已有文件的内容。

Edit 是更精细的操作工具。当你知道目标文件的大致内容，只需要修改其中一小部分时，Edit 是更安全的选择。Write 用于全新的文件创建，或者对文件进行完全重写。

5.4 Glob 和 Grep

Glob 根据文件名模式（glob pattern，如 **/*.ts 查找所有 TypeScript 文件）来查找匹配的文件。Grep 在文件内容中进行正则表达式或文本搜索。

这两个工具通常被归类为"只读"工具——因为它们只查询信息，不修改任何内容。

5.5 Bash 工具

Bash 工具是所有内置工具中能力最强大、同时也是风险最高的工具。通过 Bash，Agent 可以执行任意操作系统命令。

正因如此，Bash 工具的权限配置需要格外谨慎。应该结合 disallowedTools 禁止某些高危命令（如 rm -rf /）。

5.6 WebSearch 和 WebFetch

WebSearch 工具执行网络搜索。WebFetch 工具根据 URL 获取特定网页的内容。它们使 Agent 能够获取最新的网络信息，突破了模型训练数据的时间局限性。

5.7 Agent 工具

Agent 工具是一个特殊的存在——通过它，一个 Agent 可以"召唤"另一个 Agent（称为"子 Agent"）来执行特定任务。这不是工具调用的传统含义，而是创建一个独立运行的 Agent 实例，完成后再将结果返回给父 Agent。

第六章：消息系统与类型

6.1 SDKMessage 类型体系概述

Claude Agent SDK 定义了一套完整的消息类型体系，覆盖了 Agent 执行过程中可能出现的所有情况。

从大类上分，SDK 消息可以分为：Assistant 消息（Claude 的回复）、User 消息（用户输入）、System 消息（系统状态报告）、Result 消息（任务结果）、Error 消息（错误报告）、Hook 相关消息（钩子回调相关）、Permission 消息（权限请求）等。

6.2 AssistantMessage 的内部结构

AssistantMessage 是最核心的一类消息，它代表 Claude 模型的一次完整回复。其中最关键的是 message.content 字段——它是一个内容块数组，包含多种不同类型的内容：

  • 文本内容块（text 类型）：Claude 输出的纯文本内容
  • 工具调用内容块（tool_use 类型）：出现在 Claude 请求调用某个工具时
  • 思考内容块（thinking_block 类型）：Claude 进行深度推理时的中间步骤

6.3 ResultMessage 与任务完成状态

当 Agent 循环终止时，SDK 会发出一个 ResultMessage。这个结果消息有两种子类型：success 和 error。

success 子类型表示任务正常完成。error 子类型表示任务异常终止——可能的原因包括：达到了 maxTurns 上限、API 调用失败、工具执行过程中发生了未捕获的异常等。

第三部分：高级特性详解

第七章：Hooks 钩子系统——Agent 行为的精准控制

7.1 Hook 系统的设计理念

Hooks（钩子）是 Claude Agent SDK 中最强大、最灵活的高级特性之一。它提供了一种在不修改 SDK 核心代码的情况下，在 Agent 执行过程中的特定"挂钩点"（Hook Point）插入自定义逻辑的能力。

如果你熟悉 Web 开发中的"中间件"（Middleware）概念，Hooks 在某种程度上是类似的——它们在请求和响应的流程中占据特定的位置，允许你在信息经过时进行检查、修改、记录或拦截。

7.2 完整的钩子事件类型

Claude Agent SDK 定义了超过 30 种不同的钩子事件，覆盖了 Agent 生命周期的几乎所有关键节点。

工具相关钩子：

  • PreToolUse：在 Agent 调用工具之前触发，可以返回 permissionDecision 控制是否执行
  • PostToolUse：在工具执行完成后触发，可用于记录操作日志
  • PostToolUseFailure：在工具执行抛出异常时触发

会话生命周期钩子：

  • SessionStart：在 Agent 会话开始时触发
  • SessionEnd：在 Agent 会话结束时触发

子 Agent 钩子：

  • SubagentStart 和 SubagentStop：分别在子 Agent 启动和停止时触发

上下文管理钩子：

  • PreCompact 和 PostCompact：在上下文窗口压缩操作之前和之后触发

7.3 Hook 的实际应用场景

场景一：安全审计与操作拦截

hooks: {
  PreToolUse: [{
    matcher: "Bash",
    callback: async ({ toolInput }) => {
      const command = toolInput.command;
      if (command.includes("rm -rf") || command.includes("chmod 777")) {
        return {
          hookSpecificOutput: {
            permissionDecision: "deny",
            permissionDecisionReason: "Dangerous command detected"
          }
        };
      }
      return {};
    }
  }]
}

场景二：文件写入路径重定向

{
  matcher: "Write|Edit",
  callback: async ({ toolInput }) => {
    if (toolInput.file_path) {
      return {
        hookSpecificOutput: {
          permissionDecision: "allow",
          updatedInput: {
            ...toolInput,
            file_path: `/sandbox${toolInput.file_path}`
          }
        }
      };
    }
    return {};
  }
}

场景三：操作日志与外部系统集成

{
  matcher: "Write|Edit|Delete",
  callback: async ({ toolName, toolInput, sessionId }) => {
    await sendToAuditLog({
      sessionId,
      action: toolName,
      target: toolInput.file_path || toolInput.command,
      timestamp: Date.now()
    });
    return {};
  }
}

第八章：子 Agent 体系——多智能体协作

8.1 为什么需要子 Agent

在很多复杂场景中，单一 Agent 的能力可能不足以高效地完成任务。更合理的做法是：创建一个"总览 Agent"负责规划和协调，同时启动多个专门化的子 Agent——让它们并行工作，各自从专业角度深入分析，完成后将结果汇总给总览 Agent。

这就是子 Agent 体系的核心价值：通过任务分解，专业分工和并行执行，让原本复杂的任务变得可管理。

8.2 子 Agent 的创建方式

编程式定义（推荐方式）：

const options = new ClaudeAgentOptions({
  allowedTools: ["Agent", "Read", "Write", "Bash"],
  agents: {
    "code-reviewer": {
      description: "Expert at finding bugs, security issues, and code quality problems.",
      prompt: "You are a code review expert. Analyze code for bugs, security vulnerabilities, and quality issues.",
      tools: ["Read", "Grep", "Glob"]
    },
    "test-runner": {
      description: "Runs test suites and analyzes test coverage.",
      prompt: "You are a testing expert. Execute test suites and report coverage metrics.",
      tools: ["Bash", "Read"]
    }
  }
});

8.3 子 Agent 的上下文隔离

子 Agent 最重要的设计原则之一是"上下文隔离"。每个子 Agent 在启动时，都会获得一个全新的、独立的对话上下文——它看不到父 Agent 的对话历史，也不受父 Agent 当前正在进行的其他任务的影响。

子 Agent 只能通过两种有限的方式接收来自父 Agent 的信息：一是 AgentDefinition.prompt 中直接书写的提示词内容，二是 Agent 工具调用时传入的任务描述字符串。

8.4 子 Agent 的工具继承与限制

默认情况下，如果子 Agent 的 AgentDefinition 中没有指定 tools 字段，它会继承父 Agent 的全部可用工具。

但更安全的做法是，为每个子 Agent 明确限定它能使用的工具集合。最小权限原则在 Agent 系统中同样适用。

第九章：Model Context Protocol（MCP）集成

9.1 MCP 协议概述

Model Context Protocol（MCP）是 Anthropic 推出的一种标准化协议，旨在解决 AI 模型与外部工具和数据源之间的连接问题。

MCP 通过定义一套统一的通信规范，将这个问题大大简化了。在 MCP 的框架下，提供外部能力的"服务端"和消费这些能力的"客户端"（也就是 Agent SDK）之间，只需要遵循同一个协议，就能无缝地互操作。就像 USB 接口统一了各种外设的连接方式一样，MCP 试图成为 AI 工具生态的"USB 接口"。

9.2 MCP 服务器的配置方式

代码内配置：

const options = new ClaudeAgentOptions({
  mcpServers: {
    github: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-github"],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN }
    }
  },
  allowedTools: ["mcp__github__list_issues", "mcp__github__search_code"]
});

配置文件方式：

在项目根目录创建 .mcp.json 文件：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

9.3 MCP 工具的命名与调用

当 MCP 服务器通过 SDK 连接时，它提供的每个工具都会被赋予一个标准化的名称，格式为 mcp__服务器名称__工具名称。

例如，如果一个名为 github 的 MCP 服务器提供了一个名为 list_issues 的工具，那么它在 Agent 眼中的完整名称就是 mcp__github__list_issues。

9.4 MCP 的传输类型

stdio 传输：最常用的传输方式，适用于在本地运行的 MCP 服务器。

mcpServers: {
  filesystem: {
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
  }
}

HTTP/SSE 传输：适用于远程托管的 MCP 服务器。

mcpServers: {
  "claude-docs": {
    type: "http",
    url: "https://code.claude.com/docs/mcp"
  }
}

第十章：权限系统深度剖析

10.1 权限评估的完整流程

当 Agent 请求调用一个工具时，权限评估按照以下顺序执行六个检查步骤：

  1. Hooks 检查：所有已注册的 PreToolUse Hook 回调首先执行
  2. Deny 规则检查：检查该工具是否出现在 disallowedTools 黑名单中
  3. 权限模式检查：根据当前的 permissionMode 判断
  4. Allow 规则检查：检查该工具是否出现在 allowedTools 白名单中
  5. canUseTool 回调检查：通过回调函数向应用程序请求决策
  6. 默认拒绝：如果没有任何检查通过，默认拒绝操作

10.2 权限模式的应用场景对比

模式适用场景
"default"需要用户确认的开发测试场景
"acceptEdits"在受信任的代码库中进行快速的自动化重构
"bypassPermissions"完全隔离的沙盒环境，绝不用于生产环境
"dontAsk"构建"固定功能"的自动化 Agent
"plan""只读分析"场景——让 Agent 研究代码库但不会执行任何修改

第十一章：会话管理与持久化

11.1 SDKSession 接口

对于需要长时间运行或多次交互的 Agent 应用，会话管理是不可或缺的能力。Claude Agent SDK 提供了完整的会话管理 API，核心是 SDKSession 接口。

通过它，你可以：

  • 发送消息（send()）向会话中提交用户输入
  • 流式获取响应（stream()）接收 Agent 的实时输出
  • 恢复会话（resume()）在已有的会话中继续工作
  • 挂起和恢复（suspend()/restore()）在进程重启之间保存和恢复会话的完整状态

11.2 V2 Session API

SDK 提供了一个新的 V2 Session API（通过 unstable_v2_* 函数访问），它在接口设计上更加现代化和灵活。V2 API 将原来单一的 query() 生成器拆分为独立的操作方法，提供更细粒度的控制。

  • unstable_v2_createSession()：创建一个新的持久会话
  • unstable_v2_prompt()：便捷函数，用单次调用启动一个 Agent 任务
  • unstable_v2_resumeSession()：根据会话 ID 恢复一个已有的会话

11.3 会话元数据管理

  • listSessions()：列出所有会话，可以按项目目录过滤
  • getSessionInfo()：获取单个会话的详细信息
  • renameSession()：为会话设置一个自定义的标题
  • tagSession()：为会话打标签
  • forkSession()：从一个已有会话创建分支

第四部分：实战与进阶

第十二章：认证与第三方平台

12.1 Anthropic 官方 API 认证

使用 Anthropic 官方 API 是最直接的认证方式。你只需要获取一个 API Key（从 console.anthropic.com 的 API Keys 页面创建），然后通过环境变量 ANTHROPIC_API_KEY 或在 options 中直接传入。

最佳实践：

  • 永远将 API Key 保存在环境变量或安全的密钥管理服务中
  • 将包含占位符的 .env.example 文件提交到代码仓库作为参考，但不包含真实密钥
  • 在生产环境中使用专门的密钥管理服务而非直接在环境变量中硬编码

12.2 Amazon Bedrock 集成

Amazon Bedrock 是 AWS 提供的托管式 AI 服务，它允许你通过 AWS 的基础设施访问 Claude 模型。

要通过 Claude Agent SDK 使用 Bedrock，需要做以下配置：

  • 设置 CLAUDE_CODE_USE_BEDROCK=1 环境变量
  • 配置 AWS 凭证（通过 aws configure 或环境变量 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY）

12.3 Google Vertex AI 集成

Google Vertex AI 是 Google Cloud 提供的机器学习平台。配置方式与 Bedrock 类似：设置 CLAUDE_CODE_USE_VERTEX=1 环境变量，并配置 Google Cloud 凭证。

12.4 Microsoft Azure AI Foundry 集成

配置需要设置 CLAUDE_CODE_USE_FOUNDRY=1 环境变量，并通过 Azure 的标准认证机制提供访问凭证。

第十三章：实用案例深度解析

13.1 邮件助手 Agent

邮件助手是一个典型的"自动化工作流 Agent"应用场景。邮件助手 Agent 的核心功能包括：显示收件箱内容、根据自然语言查询搜索邮件、对邮件进行分类和归档、辅助撰写回复等。

构建邮件助手的关键设计决策之一是"操作粒度"。一个过于"能干"的 Agent 可能被诱导执行意外的邮件操作。解决方案是：只赋予 Agent 只读工具的访问权限，将写入操作留给用户确认。

13.2 调研 Agent

调研 Agent 是另一个具有代表性的 Agent 应用类型。这个调研系统的工作流程是：

  1. 接收用户的研究主题
  2. 由一个"协调 Agent"分析主题、制定调研计划
  3. 将任务分解为多个子主题
  4. 并行启动多个"调研 Agent"分别深入研究每个子主题
  5. 最后由协调 Agent 汇总所有调研结果，生成结构化的调研报告

这个系统的设计亮点在于多 Agent 的并行化——如果启动多个并行的调研 Agent，总耗时接近最耗时的那个子主题的时间。

13.3 代码审查自动化 Agent

代码审查是 Agent SDK 最为自然的用例之一。

一个实用的代码审查 Agent 通常包含以下组件：

  • 多个专门的审查子 Agent，分别负责不同维度（逻辑正确性、安全漏洞、代码风格、性能问题、测试覆盖）
  • 通过 Git MCP 服务器接入代码仓库的变更历史
  • 通过 WebSearch 工具查询不熟悉的第三方库的安全公告
  • 通过 Hook 系统将审查结果写入审查报告或直接作为 Pull Request 评论提交

13.4 持续集成中的 Agent 集成

将 Claude Agent SDK 集成到 CI/CD 流水线中，是实现"自动化质量门禁"的强大方式。在每次构建或部署之前，Agent 可以自动检查代码变更：

  • 确保变更符合项目的编码规范
  • 自动化运行测试套件并分析失败原因
  • 检查是否有遗漏的依赖更新
  • 验证文档是否与代码同步更新

第十四章：从 Claude Code SDK（旧版）迁移

14.1 主要变更内容

命名变更：

  • 包名从 @anthropic-ai/claude-code-sdk 更改为 @anthropic-ai/claude-agent-sdk
  • Python 包名从 claude-code-sdk 更改为 anthropic-agent-sdk

子 Agent 工具重命名：

  • 旧版中调用子 Agent 的工具叫 "Task"，新版中统一重命名为 "Agent"

新增 V2 API：

  • 新版 SDK 引入了 V2 Session API（unstable_v2_* 函数），但保留了原有的 API 兼容模式

14.2 迁移检查清单

  1. 确认 npm 包或 pip 包已更新到新版本
  2. 更新所有导入语句中的包名和模块路径
  3. 检查 allowedTools 和 disallowedTools 中是否使用了 "Task" 工具名，如有则替换为 "Agent"
  4. 逐一审查代码中的类型使用，确保与新版的类型定义一致
  5. 测试原有功能的兼容性，关注是否出现行为变化
  6. 如使用 MCP 服务器，检查配置格式是否有变化
  7. 如使用 Hook 系统，确认新版的 Hook 输入输出结构与旧版一致

第十五章：成本管理与性能优化

15.1 Token 消耗的来源

Claude Agent SDK 的使用成本主要来自两个方面：输入 Token（发送给模型的上下文信息）和输出 Token（模型生成的回复内容）。

在 Agent 循环中，每一次工具调用的请求和响应都会作为上下文的一部分累积。当一个 Agent 运行了很长时间、进行了大量工具调用后，上下文可能达到非常大的规模。

15.2 成本控制的策略

策略一：精简提示词

提示词不是越长越好。一个简洁、明确、直指目标的提示词，往往比一篇冗长的背景介绍更能引导 Agent 高效地完成任务。

策略二：限制工具集

在 allowedTools 中只包含任务必需的工具。减少工具数量不仅降低了权限风险，也减少了 Agent 在决策时的"选择负担"。

策略三：设置多层成本防线

通过 maxThinkingTokens（控制推理Token预算）、maxTurns（控制工具调用轮次上限）和 maxBudgetUsd（控制总体成本上限）三个参数，建立多层成本防线。

策略四：选择性启用高级特性

只在真正需要深度推理的任务中启用高努力程度（effort: "high" 或 "max"），对于简单任务使用 "low" 努力程度以节省成本。

第十六章：生产环境部署最佳实践

16.1 安全部署检查清单

在将基于 Agent SDK 的应用部署到生产环境之前，以下安全检查清单值得逐项核对：

  • API 密钥必须存储在安全的地方，绝不能出现在代码仓库或容器镜像中
  • 最小权限原则应该贯穿整个系统的设计
  • 敏感操作（文件删除、数据库写入、外部网络请求）应该总是需要明确授权
  • Hook 系统应该记录所有高风险操作，供事后审计追溯

16.2 错误处理与重试机制

健壮的生产应用需要针对不同错误类型设计不同的处理策略：

  • 对于瞬时的网络错误（如超时），应该实现指数退避重试
  • 对于认证错误，不应该无限重试，而是应该告警并人工介入
  • 对于工具执行错误，可以分析错误原因并决定是否重试或跳过
  • 对于资源耗尽错误，应该优雅地停止任务并报告当前进度

16.3 监控与可观测性

建议监控的关键指标：

指标说明
任务成功率Agent 完成任务的成功率比例
平均任务时长从任务启动到完成的时间
Token 消耗量每次任务的平均 Token 消耗和成本
工具调用频率每种工具被调用的次数和成功率
成本趋势按日/周/月维度的成本变化趋势

16.4 容器化部署

将 Agent SDK 应用容器化（使用 Docker）是部署到生产环境的常见选择。

基础镜像选择：推荐使用 Node.js 或 Python 的官方 Alpine 镜像，它们体积小、安全性好。

多阶段构建（Multi-stage Build）能够减小最终镜像体积。

资源限制（CPU、内存）是必须的。Agent 进程可能因为异常长的上下文或失控的循环而消耗大量资源，合理的 cgroup 限制可以防止单一任务影响整台主机。

附录

附录一：SDK 完整配置项参考

配置项类型默认值说明
allowedToolsstring[][]允许使用的工具名称列表
disallowedToolsstring[][]明确禁止的工具名称列表
permissionModePermissionMode"default"权限模式，控制工具调用的授权行为
cwdstringprocess.cwd()当前工作目录
additionalDirectoriesstring[][]额外的可访问目录
systemPromptstringundefined额外的系统提示词
initialPromptstringundefined初始用户消息（自动注入）
maxTurnsnumberundefined最大工具调用轮次上限
maxBudgetUsdnumberundefined最大 API 成本预算（美元）
thinkingThinkingConfigundefined思考配置（adaptive/enabled/disabled）
effortEffortLevel"high"努力程度（low/medium/high/max）
envRecord<string, string | undefined>process.env传递给 Agent 环境的环境变量
mcpServersRecord<string, McpServerConfig>{}MCP 服务器配置
agentsRecord<string, AgentDefinition>{}子 Agent 定义
hooksPartial<Record<HookEvent, HookCallbackMatcher[]>>{}钩子回调配置
modelstringundefined指定使用的模型

附录二：消息类型速查

消息类型subtype说明
SDKAssistantMessage—Claude 模型的回复，包含文本和工具调用
SDKUserMessage—用户发送的消息
SDKSystemMessageinit系统初始化完成，报告 MCP 服务器连接状态
SDKSystemMessagecompact上下文压缩事件
SDKSystemMessagerate_limitAPI 速率限制事件
ResultMessagesuccess任务成功完成
ResultMessageerror任务异常终止

附录三：常见问题与解决方案

问题一：Agent 不断重复相同的操作，不推进任务。

这是 Agent "循环"问题的典型表现，通常原因是：提示词不够明确、工具返回的结果不足以让 Agent 做出有效决策、或者达到了某个内部限制。解决思路：简化提示词、提供更具体的目标描述、检查是否需要补充额外工具或上下文。

问题二：Agent 可以看到某个 MCP 工具，但在调用时失败。

这类问题通常出在权限配置上。MCP 工具需要明确在 allowedTools 中授权。还要检查 MCP 服务器的连接状态（通过 init 系统消息中的 mcp_servers 字段）。

问题三：上下文窗口很快耗尽，压缩频繁发生。

如果 Agent 在长会话中频繁触发压缩，可能是因为提示词本身太大、工具调用返回的结果过于冗长。解决思路：在 Hook 中精简工具返回的结果粒度、使用 PreCompact 钩子保护关键上下文、考虑在适当时候手动启动新会话而非无限制地延续一个会话。

问题四：API 调用遇到速率限制（rate_limit）。

当遇到 429 错误时，SDK 内置了指数退避重试机制。如果持续遇到速率限制，考虑在应用层实现请求队列，或升级 API 使用计划。

结语

走到这里，你已经完成了从零基础到深入理解 Claude Agent SDK 的完整学习旅程。

Claude Agent SDK 不是一个简单的"包装器"——它凝聚了 Anthropic 在 Claude Code 产品化过程中积累的多年经验，将 Agent 系统的复杂性封装成了一套简洁但强大的接口。这种"简洁入口、复杂内在"的设计哲学，让入门者能够快速上手，也让深度用户能够通过各种高级特性实现极为复杂的功能。

AI Agent 的时代才刚刚开始。随着模型能力的持续增强、工具生态的不断丰富、以及开发者对 Agent 系统理解的深入，我们将会看到越来越多令人惊叹的 Agent 应用出现——从自动化工作流到智能助手，从代码生成到科学研究，AI Agent 正在成为数字世界中越来越重要的参与者。

avatar
文章
阅读
粉丝