Claude Agent SDK 教程：用 Claude Code 引擎搭建专属 AI Agent（2026）

如果你已经在用 Claude Code 写代码，可能会遇到这样的需求：想把同一套「自动读文件、跑命令、改代码」的能力接进自己的产品里，而不是只在终端里手动敲指令——比如做一个能自动修 bug 的 CI 流水线，或者一个能读邮件、查资料的后台 Agent。这正是 Claude Agent SDK 要解决的问题：它把 Claude Code 背后的工具执行循环、上下文管理、权限系统整体打包成 Python/TypeScript 库，调一个 query() 函数就能跑起同一个 Agent 引擎。这篇 Claude Agent SDK 教程讲清楚它是什么、和 Claude Code CLI / Claude API / Managed Agents 怎么选、安装鉴权怎么配、以及最容易搞错的计费方式。

Claude Agent SDK 是什么

Claude Agent SDK 的前身叫 Claude Code SDK，后来改了名字，用来强调它不只是给「写代码」用的——同一套引擎也能拿去做研究助手、邮件助手、数据分析 Agent 等各种任务。SDK 目前提供 Python 和 TypeScript 两个官方语言包，核心入口是一个异步函数 query(prompt, options)，调用后返回一个消息流：Claude 的推理过程、要调用的工具、工具执行结果、最终结果，都会作为消息依次吐出来。你不需要自己写「调用模型 → 解析工具调用 → 执行 → 把结果传回去」这个循环，SDK 已经把这套 Agent Loop、上下文管理、重试逻辑都做好了。

和 Claude Code CLI、Claude API、Managed Agents 有什么区别

Anthropic 现在提供好几种「用 Claude 干活」的方式，容易搞混，先弄清楚各自的定位：

简单说：Claude API 是最底层的「发消息」；Claude Agent SDK 和 Claude Code CLI 用的是同一套引擎，区别只是「库」还是「终端程序」这层交互形式——日常写代码用 CLI，要接入 CI/CD 或自己的应用就用 SDK；而 Managed Agents 是连服务器和沙箱都不用你管的托管方案，更适合生产环境里长时间跑、不想自己维护基础设施的场景。很多团队的实际路径是：先用 Agent SDK 在本地跑通原型，确认可行后再考虑要不要迁到 Managed Agents 做生产托管。

安装与环境要求

• 运行环境：Node.js 18+ 或 Python 3.10+（二选一，取决于你用哪个语言包）
• TypeScript 包会自动下载适配你所在平台的 Claude Code 原生二进制文件（作为可选依赖），不需要你另外单独安装 Claude Code
• 账号要求：一个 Anthropic 账号 + 一把 API Key（在 platform.claude.com 的 Console 里生成），不是 claude.ai 网页版的登录账号

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

# 或者 Python（用 uv，自动管理虚拟环境）
uv init && uv add claude-agent-sdk

# 或者 Python（用 pip，先建虚拟环境再装）
python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdk

装好之后设置好 API Key（环境变量 ANTHROPIC_API_KEY），就可以跑最基础的例子了——下面这段会让 Claude 自主读一个文件、找 bug、直接改掉：

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

for await (const message of query({
  prompt: "帮我看看 auth.ts 里有没有 bug，有的话直接修复",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

整个过程里，SDK 会自己决定要不要读文件、要不要跑命令、要不要多轮尝试，你只需要在 options 里控制「允许用哪些工具」和「要不要人工确认」。

核心能力：工具、Hooks、子智能体、MCP、权限

• 内置工具 — Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch，以及 AskUserQuestion（向用户提选择题）等，开箱即用不用自己实现执行逻辑
• Hooks — 在 PreToolUse、PostToolUse、SessionStart、SessionEnd 等关键节点插入自定义回调，可以用来记日志、拦截危险操作、修改行为
• 子智能体（Subagents）— 用 AgentDefinition 定义专用子智能体（比如一个专职代码审查的 agent），主 Agent 通过内置的 Agent 工具委派任务，子智能体独立维护自己的上下文
• MCP 支持 — 通过 Model Context Protocol 连接数据库、浏览器自动化（如 Playwright MCP）、第三方 API 等外部系统，几百个现成的 MCP Server 可以直接接
• 权限系统 — 用 allowedTools/disallowedTools 精确控制能用哪些工具，更细的审批逻辑用 permission_mode 控制

权限模式（permission_mode）怎么选

计费怎么算：走的是 Claude API 按量计费，不是订阅

这是最容易踩坑的地方——Claude Agent SDK 不认 claude.ai 网页版的 Pro/Max 订阅登录，官方文档明确写了：除非另外获得批准，第三方开发者不允许把 claude.ai 登录或订阅额度提供给自己的产品用户，包括基于 Agent SDK 搭建的 Agent。也就是说，不管你自己是不是 Claude 订阅用户，只要是用 Agent SDK 做产品，就必须走标准的 ANTHROPIC_API_KEY 按 token 计费，和直接调 Claude API 是同一套价格体系，按你选用的模型（Opus/Sonnet/Haiku 系列）和输入输出 token 量计费，具体单价请以 platform.claude.com 的 Pricing 页面为准，官方也在持续更新。除了原生 API Key，SDK 也支持通过环境变量切到 Amazon Bedrock、Claude Platform on AWS、Google Cloud、Microsoft Foundry 这些第三方渠道鉴权计费。

Claude Code 的项目配置在 SDK 里也能用

SDK 默认会读取当前目录下的 .claude/ 和用户目录下的 ~/.claude/，也就是说你项目里已有的 CLAUDE.md 记忆文件、.claude/skills/ 技能、.claude/commands/ 自定义命令，在 SDK 里跑起来时同样生效，不用重新配置一遍；想精确控制读取哪些配置来源，可以用 setting_sources（Python）/ settingSources（TypeScript）选项收窄范围。

生产环境部署要注意什么

本地跑通原型之后，官方文档有专门的 Hosting 指南讲怎么部署到 Docker、云平台、CI/CD 流水线。几个和本地开发不一样的点：会话状态默认存成本地文件系统里的 JSONL，支持用 resume 恢复上一次会话上下文、用 fork 从某个节点分叉出新会话去试不同方案；生产环境建议用 dontAsk 或 bypassPermissions 这类无人值守权限模式，配合 allowedTools 白名单而不是完全放开；如果不想自己维护会话存储和沙箱环境，这也是该考虑换成 Managed Agents 托管方案的信号。

Claude Agent SDK 把 Claude Code 那套「自己读文件、自己跑命令、自己改代码」的能力开放成了可编程接口，这也是这两年 AI 编程工具的一个明显方向——从「终端里的助手」变成「能嵌进任何产品的引擎」。如果你想系统学习怎么用 AI 工具从零到一搭建出真实产品，欢迎来 IMAI 看看我们的体系化实战课程。