使用 Claude Code SDK 构建自主 Agent：开发者实战指南

使用 Claude Code SDK 构建自主 Agent：开发者实用指南

Claude Code SDK ——正式名称为 Agent SDK ——是一个 Python 和 TypeScript 库，让你能够以编程方式驱动 Claude Code 的完整 agent 引擎：无需终端，无需人工在键盘前操作，只需你的应用程序调用异步的 query() 函数，并流式接收 agent 工作的每一步。如果你曾经交互式地使用过 Claude Code，那么 SDK 提供的正是同样的读文件 / 改代码 / 跑命令循环，只不过变成了一个可组合的库，你可以将其嵌入到 CI 流水线、代码审查机器人、多 agent 编排器，或任何后端服务中。

Agent SDK 是什么——以及它存在的原因

Claude Code 作为一款终端工具广为人知。你输入一个提示词，agent 对你的代码库进行推理，调用内置工具（Read、Edit、Bash、Grep 等），并将结果写回给你。但一旦你想要自动化这个循环——在每个 pull request 上触发审查、分派给多个专门的子 agent，或在其之上构建产品——交互式 CLI 就不再是合适的抽象层了。你需要一个库。

Agent SDK 填补了这一空白。根据 Anthropic 官方文档 所述，它公开了"驱动 Claude Code 的同一套工具、agent 循环和上下文管理机制，可通过 Python 和 TypeScript 编程调用"。这并非营销措辞——而是字面意义上的架构。SDK 将 Claude Code 的 CLI 二进制文件作为受管理的子进程启动，通过 stdio 与其通信，并将一切以类型化消息对象的异步流形式呈现出来，供你的代码消费和响应。

这一区别之所以重要，有以下几个原因：

引擎相同，接口不同。 当你从 CLI 切换到 SDK 时，你并没有转向一个功能较弱或更简化的工具。SDK 继承了 CLI 中的每一项能力——MCP 服务器连接、hooks 生命周期、skill 文件、CLAUDE.md 记忆、子 agent 委派，以及完整的工具清单。

SDK 会替你完成工具执行。 如果你使用 Anthropic Client SDK（更底层的 anthropic Python/JS 包）并希望 Claude 调用工具，你必须自行实现工具循环：调用 API、检测工具使用响应、执行工具、将结果反馈回去，如此重复直到 Claude 停止。Agent SDK 将整个循环压缩成一行 async for message in query(...)——由 Claude 决定调用哪些工具，在其子进程内执行，并持续循环直到任务完成。你只需消费这个消息流即可。

天生无头（Headless）设计。 CLI 的权限提示——"是否允许执行此 bash 命令？"——会阻塞等待人工输入。SDK 用 permissionMode 选项和一组权限模式取而代之——例如 acceptEdits 用于自动批准文件编辑，bypassPermissions 用于在沙箱化的 CI 环境中不加提示地运行所有操作——此外还提供了一个可编程的批准回调，用于自定义流程。具体的模式名称和行为记录在 Anthropic 的 SDK 参考文档中（请查阅当前的完整列表），但效果是一样的：你的自动化流程永远不会因等待按键而挂起。

同一个 Claude Code 引擎，两种接口：交互式 CLI 用于人机协同工作，Agent SDK 用于编程化、无头的自动化场景，此时由你的应用程序控制提示词，权限模式取代了审批对话框。

安装 SDK

Anthropic 发布了两个包：

• TypeScript： @anthropic-ai/claude-agent-sdk（npm）
• Python： claude-agent-sdk（pip；需要 Python 3.10+）

TypeScript 包为你的平台捆绑了原生的 Claude Code 二进制文件，因此无需单独安装 CLI。身份验证通过从 Anthropic Console 获取的 ANTHROPIC_API_KEY 环境变量完成。SDK 还支持 Amazon Bedrock、Google Vertex AI 和 Microsoft Azure AI Foundry——相关环境变量配置方式请参阅 Anthropic 的文档。

核心概念

理解以下四个概念，即可覆盖绝大多数实际的 SDK 使用场景。

1. query() 函数与异步消息流

每一次 SDK 交互都始于 query()。你传入一个 prompt 字符串和一个 options 对象；作为返回，你会得到一个异步迭代器，随着 agent 工作的推进不断产出类型化的消息对象。当 agent 完成任务或遇到错误时，循环结束。

你收到的消息包括：

• AssistantMessage —— Claude 的推理文本和工具调用描述
• ToolResultMessage —— 每次工具执行的输出
• ResultMessage —— 最终结果，带有一个表示成功或失败的 subtype 字段
• SystemMessage —— 会话生命周期事件（init 子类型携带 session_id）

在大多数生产代码中，你会筛选 ResultMessage 以提取最终输出，并可选地记录 AssistantMessage 块以追踪 agent 的具体操作。

2. 工具与 allowedTools

SDK 的内置工具清单直接映射到 Claude Code 的能力：

allowedTools 选项会预先批准这些工具的一个子集，实质上是授予 agent 无需任何额外审批门槛即可调用这些工具的权限。一个只读的审计型 agent 可能只列出 ["Read", "Glob", "Grep"]；而一个完整的自动化流程可能包括 ["Read", "Edit", "Bash", "Glob", "Grep"]。

3. 权限模式

权限模式控制当 agent 想要使用一个未在 allowedTools 中预先批准的工具时会发生什么：

• acceptEdits —— 自动批准文件编辑和常见的文件系统操作；对其他一切操作则会提示。最适合可信的开发工作流。
• dontAsk —— 静默拒绝任何不在 allowedTools 中的操作。最适合锁定式的无头 agent。
• bypassPermissions —— 不设任何门槛，运行所有工具。仅在沙箱化环境中使用。

SDK 还提供了一个可编程的批准回调，方便你实现完全自定义的批准逻辑，且可用的模式名称可能会随时间扩展——请查阅 Anthropic 的 SDK 参考文档获取权威的、最新的列表以及各模式的确切行为。在 CI 中，你几乎总是会使用一个范围严格、默认拒绝的配置，或者在你自己掌控的容器沙箱内使用 bypassPermissions。

4. 会话、恢复与上下文

每次调用 query() 都会创建（或恢复）一个会话。会话的 session_id 会在第一个 subtype === "init" 的 SystemMessage 中送达。你可以捕获它，并在后续调用中以 resume: sessionId 的形式传入，从而精确地从对话中断处继续——相同的文件读取记录、相同的推理历史、相同的上下文窗口。

这正是构建多轮 agent 的方式：一次 query() 调用分析一个模块并捕获 session_id，第二次 query() 调用（带 resume）就能引用"它"或"你刚才读过的文件"，而无需重新解释。会话记录默认写入本地磁盘；在生产环境中，你可以附加一个由 S3、Redis 或 Postgres 支持的 SessionStore 适配器，使会话能够在容器重启后依然存活。

构建模式一：CI 代码审查机器人

这是典型的"无头自动化"用例。每次有 pull request 时，CI 任务会检出该分支，运行一个 agent 读取变更文件，并发布一条审查评论。

流程如下：

1. PR 事件触发一个 GitHub Actions 工作流（或 GitLab CI 任务）。
2. Runner 检出分支并运行你的审查脚本。
3. 你的脚本以审查提示词、allowedTools: ["Read", "Glob", "Grep", "Bash"] 和 permissionMode: "dontAsk" 调用 query()。
4. Claude 读取 diff，搜索模式，对发现的问题进行推理。
5. ResultMessage 携带审查文本；你的脚本通过 GitHub API 将其发布到 PR 上。

关键的设计选择是配合只读工具列表使用 dontAsk。agent 无法写入文件或进行工具允许范围之外的网络调用，因此你的 CI 任务不会意外地合并提交或调用外部 API。选项中设置的 maxTurns 上限约束了 agent 的深度，防止失控循环消耗过多预算。

关于此流程的图示架构，请参见下方示意图。

一条完全自动化的代码审查流水线。SDK agent 在 CI 容器内以只读工具列表运行；发现的问题以 ResultMessage 的形式流回，你的代码将其作为 GitHub PR 评论发布出去。agent 从不写入文件，也从不离开容器。

你可以用 hooks 来扩展这一模式——这是我们在 Claude Code hooks 深度解析 中介绍过的 SDK 功能——用于将每次工具调用记录到审计文件、阻止读取特定文件路径，或在审查过程中一并发出结构化的遥测数据。

构建模式二：多 Agent 工具链

SDK 的 agents 选项让你能够定义具名的子 agent，每个都有自己的系统提示词、工具列表和权限。你的主 agent 通过内置的 Agent 工具将工作委派给它们。子 agent 消息包含一个 parent_tool_use_id 字段，方便你精确追踪是哪次委派产生了每一段输出。

一个实际的例子：一条安全审计 agent 链，其中 code-scanner 子 agent 使用 Grep 和 Glob 查找潜在漏洞，dependency-checker 子 agent 运行 Bash 查询你的软件包元数据，协调者 agent 则将两份报告综合成一份统一的审计报告。每个子 agent 都只拥有其角色所需的最小工具访问权限，从而限制了子 agent 出现幻觉、执行危险命令时的影响范围。

多 agent 链非常适合那些能自然分解的任务：每个 agent 专注一个关注点，配以紧凑的工具列表，由一个仅需 Read 和 Agent 的协调者进行编排。若想更全面地了解多 agent 架构如何与 CLAUDE.md 记忆、skill 文件等 Claude Code 特性协同工作，请参阅我们的 harness 工程指南。

构建模式三：无头自动化流水线

除了代码审查，SDK 在任何"agent 是更大流水线中一个环节"的经常性自动化场景中都表现出色：

每夜依赖审计。 一个 cron 任务调用 query()，提示词要求检查过期的包、运行安全扫描器，并生成结构化报告。Bash 工具运行 npm audit 或 pip check；Read 检查锁文件。ResultMessage 会被输送到一条 Slack 通知中。

PR 合并时的翻译与 i18n。 当一个 PR 合并时，一个 webhook 触发一个 agent，用 Glob 和 Read 读取变更的字符串文件，用 Write 生成翻译版本，再通过 Bash（运行 gh pr create）打开一个新的 PR。

日志异常检测。 将近期日志输出通过管道传入 query() 的提示词。agent 会在需要时读取额外的上下文文件，对日志进行推理，并给出结构化的发现结果。无需任何文件写入操作；只读工具列表已经足够。

文档同步。 PR 合并后，一个 agent 读取更新后的源文件并重写对应的文档页面，然后提交这些改动。permissionMode: "acceptEdits" 会在不提示的情况下处理文件写入。

共同点在于：query() 取代了一套定制化的 LLM 集成方案。你不需要实现工具循环、手动管理上下文窗口，也不需要解析模型输出来决定下一步执行什么。agent 负责编排，你只需提供提示词并消费结果。

一个具有说明性的完整示例：修复 Bug 的 Agent

官方快速入门清晰地展示了这一模式（以下代码遵循文档中的 API——请在 Anthropic 的快速入门文档 中核实确切语法）：

说明性 Python 代码（请在官方文档中核实确切 API）：

# Illustrative — confirm exact import paths and option names in official docs
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def run_bug_fixer(file_path: str):
    async for message in query(
        prompt=f"Review {file_path} for bugs that would cause crashes. Fix any issues.",
        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)
        elif isinstance(message, ResultMessage):
            print(f"Completed: {message.subtype}")

asyncio.run(run_bug_fixer("src/utils.py"))

说明性 TypeScript 代码（请在官方文档中核实确切 API）：

// Illustrative — confirm exact import paths and option names in official docs
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review src/utils.ts for crash-causing bugs and fix them.",
  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);
    }
  }
  if (message.type === "result") console.log("Done:", message.subtype);
}

运行时会发生什么：Claude 使用 Read 工具读取 utils.py（或 .ts），对代码进行推理，识别边界情况，然后调用 Edit 插入防御性处理逻辑。你会看到推理过程和工具调用以 AssistantMessage 对象的形式流式呈现；最终的 ResultMessage 标志着任务完成。包括重新读取文件以验证编辑结果在内的整个 agent 循环，都由 SDK 负责管理。

这正是 SDK 与直接调用 Anthropic 模型 API 的不同之处：你不需要实现工具执行层。Claude 会自行决定何时调用 Read，执行调用，取回文件内容，并继续推理。这个循环是自主的。

权限、沙箱化与生产环境安全

在生产环境中运行自主 agent，需要认真考虑它们能够触及的范围。SDK 提供了若干层控制机制。

工具范围限定是第一道防线。如果一个 agent 不需要 Bash，就不要将其纳入 allowedTools。一个只拥有 ["Read", "Glob", "Grep"] 的 agent，无论其提示词说了什么，都无法修改文件、运行 shell 命令或发起网络调用。

权限模式提供了第二道关卡。dontAsk 确保任何在 allowedTools 之外的操作都会被静默拒绝，而不是发出提示。这在无头环境中至关重要——一个悬而未决、等待用户输入的提示会使你的流水线卡住。

cwd 选项将 agent 的文件系统访问范围限定在特定目录内。在多租户环境中，为每个会话传入独立的工作目录，使不同租户的 agent 无法读取彼此的文件。

租户隔离需要额外的步骤：设置 settingSources: [] 以防止任何文件系统设置跨租户泄漏；设置 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 以阻止自动记忆功能加载；将 CLAUDE_CONFIG_DIR 指向按租户区分的路径。这些内容在 Anthropic 的托管指南中都有详细记录。

容器沙箱化是最外层的防护壳。对于需要 Bash 访问权限的生产 agent，应在容器内运行 SDK，并将网络出站流量限制在你明确允许的域名范围内。Modal、E2B、Cloudflare Sandboxes、Fly Machines 和 Vercel Sandbox 等服务商在 Anthropic 文档中都被列为沙箱化 SDK 部署的可选方案。

maxTurns 限制了工具使用往返的次数上限，从而约束了成本和失控循环。请根据任务的预期复杂度来设置——一个简单的文件读取审查可能只需要 5–10 轮；一次复杂的多文件重构则可能需要 30–50 轮。

对于正在构建生产级 hooks 和权限流程的团队，我们的 Claude Code hooks 指南 详细介绍了 PreToolUse 和 PostToolUse hook 的生命周期，包括如何编写在工具调用执行前进行阻止、转换或记录的 hook 回调函数。

MCP：将 Agent 连接到外部系统

SDK 完全支持模型上下文协议（Model Context Protocol，MCP），它让你能够将 agent 连接到任何暴露了 MCP 服务器的外部系统：数据库、浏览器自动化、Jira、Slack、GitHub，以及数百个社区构建的服务器。

你在 mcpServers 选项中配置 MCP 服务器——每个条目指定一个要运行的命令以及可选的参数。SDK 会将这些服务器作为子进程启动，agent 调用它们的工具的方式和调用内置工具完全相同。这就是你为代码审查 agent 提供工单系统访问权限，或将文档 agent 连接到公司知识库的方式。

权限模型同样适用于 MCP 工具调用——allowedTools 可以包含 MCP 工具名称，permissionMode 则决定了未列出工具的处理方式。

常见陷阱与注意事项

会话默认是子进程本地的。 会话记录存储在宿主机本地磁盘的 ~/.claude/projects/ 目录下。在容器化或水平扩展的部署中，这意味着会话状态会在重启或节点重新分配后丢失。对于任何需要跨容器恢复的会话，请使用 SessionStore 适配器。

子进程模型带来内存开销。 每个正在运行的会话都是一个独立的子进程。同时运行五十个并发会话，意味着五十个 Claude Code 进程。官方建议每个 agent 大约需要 1 GiB 内存作为起点，但实际内存使用量取决于会话长度和工具活动情况。请据此调整容器规格，并设置 maxTurns 来限制会话深度。

大规模子 agent 扇出会触及速率限制。 如果你的编排器同时向二十个子 agent 委派任务，你很可能会碰到 Anthropic 的 API 速率限制。请将大规模的扇出拆分成批次，并在各批次的派发之间添加小的延迟。

bypassPermissions 需要一个真正的沙箱。 该模式会跳过所有权限门槛。它专为完全受控的环境设计，例如你完全掌控整个执行上下文的 CI 容器。在开发者的机器上使用它——那里的 agent 能够访问 SSH 密钥、云凭证以及任意文件系统路径——存在安全风险。

TypeScript SDK 捆绑了 Claude Code 二进制文件；Python 无需单独依赖它。 但两个 SDK 都固定绑定到特定的 CLI 版本。当你升级 SDK 包时，底层的 CLI 也会随之升级。在进行小版本升级前请查看更新日志——重大的行为变更会在其中公布。

默认情况下，提示词文本和工具输入不会包含在 OTEL 导出数据中。 这是刻意为之的隐私保护行为。如果你需要用于调试的提示词级追踪，必须通过 Anthropic 可观测性指南中记录的环境变量显式启用。

旧版本的 SDK 可能不支持较新的模型。 Anthropic 的文档指出，由于思考参数 API 的变化，较新的模型可能需要较新的 SDK 版本，因此过时的 SDK 在面对新模型时可能会失败。在采用新模型时，请务必查看更新日志并固定使用一个已知可用的版本。

SDK 与 CLI：你需要哪一个？

对大多数开发者而言，答案是两者都需要——这正是设计初衷。

交互式 CLI 适合日常开发场景：探索一个陌生的代码库、交互式地排查一个复杂的 bug，或运行一次性的重构。SDK 则适合任何需要在无人值守情况下运行的场景：CI、定时任务、应用功能，以及多 agent 流水线。

SDK 与 CLI 并非相互竞争的产品。你用 CLI 交互式开发出的工作流，可以直接迁移到 SDK 自动化中——相同的工具、相同的权限概念、相同的 CLAUDE.md 记忆与 skills 系统。今天你在终端中用 claude 原型化的审查工作流，明天就能变成一个由 SDK 驱动的 CI 机器人。

对于使用网页版 Claude Code 的团队（详见我们的 Claude Code 网页版指南），SDK 打开了将网页会话与编程化编排相结合的大门——从网页端启动一个长时间运行的任务，然后从后端以编程方式接入其中。

常见问题

Claude Code SDK（Agent SDK）到底是什么？ 它是一个 Python（claude-agent-sdk）和 TypeScript（@anthropic-ai/claude-agent-sdk）库，将 Claude Code 的完整 agent 引擎——工具、权限、会话管理、子 agent、MCP——以一个可编程的异步 API 形式公开出来。你调用 query()，传入提示词和选项，然后以类型化消息对象的形式流式接收 agent 的工作过程。

我需要安装 Claude Code 才能使用 SDK 吗？ 对于 TypeScript SDK 来说不需要——该包捆绑了原生的 Claude Code 二进制文件。对于 Python SDK，claude-agent-sdk 包会处理这个依赖。但你确实需要一个来自 Anthropic Console 的 Anthropic API 密钥。

我可以将 SDK 与 Anthropic API 之外的其他模型一起使用吗？ 可以。SDK 通过环境变量支持 Amazon Bedrock、Google Vertex AI、Microsoft Azure AI Foundry，以及 AWS 上的 Claude Platform。你也可以通过设置 ANTHROPIC_BASE_URL 将请求路由到自定义代理。

如何在 GitHub Actions 工作流中使用 SDK？ 将你的 ANTHROPIC_API_KEY 添加为 GitHub Actions secret，在工作流中检出 PR 分支，安装 SDK 包，并运行你的 agent 脚本。配合只读的 allowedTools 列表使用 permissionMode: "dontAsk"，这样 agent 就无法在你的 CI 环境中修改文件。Anthropic 的文档还介绍了一个专门的 GitHub Actions 集成，无需编写自定义 SDK 代码即可自动完成 PR 审查和 issue 分诊。

Agent SDK 与 Managed Agents 有什么区别？ Agent SDK 是一个在你自己的进程和基础设施内运行 agent 循环的库。Managed Agents 则是一个托管的 REST API，由 Anthropic 运行 agent 和沙箱环境——你发送事件并流式接收结果。SDK 更适合本地原型开发以及需要直接操作你文件系统的 agent；而 Managed Agents 更适合不想自行运维容器基础设施的生产环境。

我该如何限制 agent 能够访问的内容？ 使用 allowedTools 限制可用的工具，使用 permissionMode: "dontAsk" 拒绝该列表之外的一切操作，并使用 cwd 将文件系统访问范围限定在特定目录。对于多租户部署，还需额外设置 settingSources: [] 和 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。

SDK 支持流式输出吗？ 支持——query() 返回的异步迭代器会实时流式输出消息。如果你不需要实时输出（例如后台任务或只关心最终结果的 CI 流水线），Anthropic 的文档描述了一种单轮模式，会在返回之前收集所有消息。详见官方文档中的流式模式与单轮模式对比。

我可以并行运行多个 agent 吗？ 可以。每次 query() 调用都会派生一个独立的子进程。你可以运行 N 个并发会话——但每一个都是独立的进程，因此请相应地配置内存，并注意 API 速率限制。对于来自单一编排器的并发子 agent 扇出，请将你的派发批次化，以避免触及速率限制。

如果会话在任务执行到一半时崩溃了会怎样？ 默认情况下，会话记录是容器本地的，重启后会丢失。为了在重启后依然存活，请配置一个 SessionStore 适配器（S3、Redis 或 Postgres），并在选项中传入。之后你就可以在一个全新的容器上通过 session_id 恢复该会话。

无需本地环境配置即可运行 Agent

SDK 的价值主张在于自动化——但要让这种自动化真正运行起来，需要真实的基础设施投入：一个 Python 或 Node 运行时、一个 API 密钥、一套容器策略、一个沙箱化方案，以及在你的首次生产部署之前花在权限建模上的时间。

对于希望在不承担这些配置开销的情况下迭代 agent 想法的开发者来说，Happycapy 可以直接在浏览器中运行 Claude Code 风格的 agent。无需本地安装，无需子进程管理，也无需容器配置。你只需带来一个提示词，Happycapy 负责处理执行环境——可访问 150 多个模型，并配备安全的云沙箱。这是一条快速通道，能让你先原型化 agent 行为，之后再用 SDK 将其产品化。

在 happycapy.ai 免费开始

相关指南

• Claude Code Hooks：自动化你的 Agent 的进阶指南
• Claude Code 代码审查究竟是如何工作的：Diff、Hooks 与 Agent 能捕获到什么
• Claude Code Web：如何在浏览器中运行 Claude Code（无需安装）
• 什么是 Harness 工程？构建可靠的 AI Agent Harness（2026）