Claude Agent SDK 实战:如何构建 AI 智能体（2026）

摘要

• Claude Agent SDK 是 Anthropic 让你在自己代码里构建 AI 智能体的库——和 Claude Code 同一套智能体内核,Python 叫 claude-agent-sdk(3.10+),TypeScript 叫 @anthropic-ai/claude-agent-sdk。
• 它在 2025 年底从 `claude-code-sdk` 改了名;如果某篇教程还写 ClaudeCodeOptions,那是过时的——现在这个类叫 ClaudeAgentOptions。
• 你免费拿到整套智能体循环:文件工具、Bash、联网搜索、经 @tool 的自定义工具、MCP server(Jira/Shopify 就靠它接)、子智能体、hooks、权限。你只为 Claude API 的 token 付费。
• 它走 Anthropic Messages API,所以你能用 ANTHROPIC_BASE_URL 把它指向网关——我们实测把它指向 [Velokey](https://api.velokey.ai) 的 /v1/messages 端点,一把 key、按额度计费就能跑。

现在人人都在搭智能体,而大多数教程停在那十行 quickstart。这篇讲之后的事:怎么装才不踩常见的 Node 坑、怎么接 Jira/Shopify 这种真工具、跑起来到底多少钱、怎么把它走网关。开始吧。

Claude Agent SDK 是什么？

Claude Agent SDK 是一个库,把 Claude Code 里那套自主智能体循环给到你自己的应用——读写文件、执行命令、联网搜索、调用工具,而不用你手写工具调用循环。Anthropic 同时提供 Python 和 TypeScript 版,并且据官方文档,它是在 Claude 上构建生产级智能体的官方支持方式。

多数人漏掉的关键背景:它以前叫 Claude Code SDK。Anthropic 在 2025 年底把它改名成 Claude Agent SDK,以示它是用来构建*任何*智能体、不只是编码工具。包名、导入、以及一个核心类都变了——claude-code-sdk 变成 claude-agent-sdk,ClaudeCodeOptions 变成 ClaudeAgentOptions。很多博客和 Stack Overflow 答案还在引用旧名,所以你导入报错,通常就是这个原因。

底层上,SDK 把 Claude Code CLI 当子进程包了起来。你的 Python/TypeScript 代码对接 SDK;SDK 驱动内置的 CLI;CLI 对接 Claude。这个架构有两点后面要用到:CLI 是个 Node 二进制(所以即便用 Python SDK 也得装 Node),而且 CLI 会对它的系统提示词做激进的 prompt 缓存(这会改变你的成本账)。

怎么安装和使用 Claude Agent SDK？

从 PyPI(或 npm)装 Claude Agent SDK、设好 key、调 query()——一个能跑的智能体大约十行。Python 需要 3.10 或更新:

pip install claude-agent-sdk
export ANTHROPIC_API_KEY="sk-ant-..."

这是最小的一次性智能体。query() 返回一个消息的异步迭代器:

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="列出这个仓库里的 Python 文件并逐个总结。"):
        print(message)

anyio.run(main)

要交互或多轮,用 ClaudeSDKClient,并用 ClaudeAgentOptions 配置:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="You are a careful code-review assistant.",
    allowed_tools=["Read", "Grep", "Glob"],
    permission_mode="acceptEdits",
    max_turns=10,
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Review auth.py for security issues.")
    async for msg in client.receive_response():
        print(msg)

两个绊倒人的安装坑,都不在十行 quickstart 里:

用 Claude Agent SDK 能构建什么？

任何需要文件访问、命令执行或工具调用的智能体你都能搭——从代码审查员到客服分诊员到数据管道操作员。SDK 给你五块积木,整个设计都围绕"控制智能体被允许做什么":

自定义工具是最清爽的部分。给一个函数加装饰器,智能体就能直接调它——没有独立进程、没有网络跳转:

from claude_agent_sdk import tool

@tool("get_order", "Look up an order by ID", {"order_id": str})
async def get_order(args):
    order = db.fetch(args["order_id"])
    return {"content": [{"type": "text", "text": str(order)}]}

Hooks 和权限是把 demo 变成能无人值守跑的东西的关键。一个 PreToolUse hook 可以拦掉匹配危险模式的 Bash 命令;permission_mode 决定智能体是停下等批准还是自动接受编辑。生产里,多数团队从一个很紧的 allowed_tools 列表起步,随着信任增加再放开——跟那个大敞四开的 quickstart 正相反。

第六块积木、也是单个智能体变慢后大家会去够的那块,是子智能体(subagents)。SDK 能开一个带独立上下文的子智能体去处理一个限定范围的子任务,再把结果交回来——Claude Code 就是靠这个在多文件间铺开。它是"能不能并行做几件事""怎么不让主上下文被塞满"的内置答案:把吵闹的活(读十个文件、跑一个测试矩阵)交给子智能体,主智能体就能保持专注。会话分叉(session forking)是与之相关、用来给进行中的对话开分支的手法。

怎么用 Claude Agent SDK 集成 Jira 或 Shopify？

你集成 Jira、Shopify 或任何外部系统,靠的是把它的 MCP server 加到 ClaudeAgentOptions 的 mcp_servers 里——SDK 没有 Jira 专用代码,它说的是开放的 Model Context Protocol,而 Atlassian 和 Shopify 都有 MCP server。这就是那几个搜得最多的集成问题("how to connect Jira/Shopify with Claude Agent SDK")的答案:没有特殊连接器,你注册一个 MCP server、放行它的工具。

两者的套路一样。把 SDK 指向 MCP server(一个本地命令或一个远程 URL),再放行它暴露的工具:

options = ClaudeAgentOptions(
    mcp_servers={
        "jira": {
            "command": "npx",
            "args": ["-y", "@atlassian/mcp-server-jira"],
            "env": {"JIRA_API_TOKEN": os.environ["JIRA_API_TOKEN"]},
        }
    },
    allowed_tools=["mcp__jira__search_issues", "mcp__jira__create_issue"],
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("找出分配给我的未关闭 bug 并总结。")
    async for msg in client.receive_response():
        print(msg)

把 server 块换成 @shopify/mcp-server(配你的 Shopify token),同一个智能体就能读订单或改商品。两点要弄对:工具名遵循 mcp__<server>__<tool> 约定,所以你的 allowed_tools 条目必须精确匹配;每个 MCP server 都要在 env 里有自己的凭证。如果智能体说某工具不可用,那几乎总是名字对不上或缺 token,而不是 SDK 的 bug。

如果厂商托管的是远程 MCP server 而不是本地命令,就用 URL 而非 command/args 注册——{"jira": {"url": "https://mcp.atlassian.com/v1/sse"}}——SDK 走网络连它。本地(stdio)server 开发时更简单、token 留在你机器上;远程(URL)server 省得你装东西。两种方式,allowed_tools 和每 server 凭证的规则都一样。

怎么让 Claude Agent SDK 走网关？

把 ANTHROPIC_BASE_URL 设成你网关的根地址,SDK 就会把每个请求发到那里,而不是 api.anthropic.com——不用改代码。SDK 认标准的 Anthropic 环境变量,所以任何暴露 Anthropic Messages API(/v1/messages)的后端都能用:公司代理、区域桥接,或一个统一网关。

我们拿 [Velokey](https://api.velokey.ai) 实测了——它暴露了一个 Anthropic 兼容的 /v1/messages 端点。一次真实请求返回了标准 Messages 响应(stop_reason: end_turn、Anthropic 式 usage),正是 SDK 期待的:

export ANTHROPIC_BASE_URL="https://api.velokey.ai"
export ANTHROPIC_API_KEY="sk-你的velokey密钥"
# 然后照常跑你的智能体——把模型设成 Velokey 提供的某个:

options = ClaudeAgentOptions(
    model="claude-sonnet-5",      # 或 claude-opus-4-8
    allowed_tools=["Read", "Grep"],
    max_turns=8,
)

为什么要让智能体走网关?一把 key,免去单独开 Anthropic 账户、跑用量档、配 30 天保留;按额度计费、可封顶;而且同一把 key 触达 [Claude Opus 4.8](/model/claude-opus-4-8)、[Claude Sonnet 5](/model/claude-sonnet-5) 以及你别处可能用的模型。如果你的代理要的是 bearer token 而不是 x-api-key 头,就设 ANTHROPIC_AUTH_TOKEN 而非 ANTHROPIC_API_KEY。这跟把一个 OpenAI 兼容工具指向网关是同一个即插即用思路——OpenAI 格式那边的等价做法见我们的 Qwen CLI 指南。

Claude Agent SDK 要多少钱？

SDK 本身免费、开源——你为智能体消耗的 Claude API token 付费,而智能体很能吃 token。每一轮都重发不断增长的对话,每个工具结果都回灌进上下文,一个"修这个 bug"的任务能跑十几轮。这就是成本的意外:代码十行,但 token 账单随智能体探索的程度线性上涨。

三个杠杆能压住它,而最大的那个 SDK 已经帮你内置了:

最后那一行是真的,不是理论:在我们的测试请求里,响应报告了数万个 cache_read_input_tokens,意味着那个很大的系统提示词是从缓存以约输入价十分之一的价格取的,而不是每轮重新计费。这也是智能体成本没有轮数看起来那么凶残的主要原因。完整的按模型 token 账见我们的 Claude API 价格指南;想在搭智能体之前先跑通一次对 Claude 模型的单次调用,如何用 API key 调用 Claude 讲了基础。

常见问题

Claude Agent SDK 是什么？

它是 Anthropic 官方用来在 Python 或 TypeScript 里构建 AI 智能体的库,用的是驱动 Claude Code 的同一套自主智能体循环。它替你处理工具调用循环、文件操作、命令执行和 MCP 集成,所以你写的是目标和工具,而不是编排。你只为 Claude API 的 token 付费。

Claude Agent SDK 和 Claude Code SDK 是一回事吗？

是——它是改名后的版本。Anthropic 在 2025 年底把 claude-code-sdk 改名成 claude-agent-sdk,ClaudeCodeOptions 变成 ClaudeAgentOptions。功能延续,只是包名和类名变了。如果一篇教程还导入旧名,那它早于改名,在当前包上会导入失败。

怎么安装 Claude Agent SDK？

跑 pip install claude-agent-sdk(Python 3.10+),或 TypeScript 用 npm install @anthropic-ai/claude-agent-sdk,再设 ANTHROPIC_API_KEY。因为 SDK 把内置的 Claude Code CLI 当子进程驱动,所以即便用 Python 包也要装 Node.js——缺 Node 是最常见的安装失败。

怎么把 Jira 或 Shopify 接到 Claude Agent SDK 智能体?

把厂商的 MCP server 加到 ClaudeAgentOptions 的 mcp_servers 里,并放行它的工具。Atlassian(Jira)和 Shopify 都发布了 MCP server,所以不用写自定义连接器——你带着 API token 注册 server,把它的工具(名为 mcp__<server>__<tool>)列进 allowed_tools。

Claude Agent SDK 能配网关或代理吗？

能。它认 ANTHROPIC_BASE_URL 环境变量,所以能路由到任何暴露 Anthropic Messages API(/v1/messages)的后端,不用改代码。我们对 Velokey 的 Anthropic 兼容端点做了一次真实请求验证。x-api-key 的代理用 ANTHROPIC_API_KEY,bearer token 的代理用 ANTHROPIC_AUTH_TOKEN。

Claude Agent SDK 用哪些模型？

它通过你指向的端点用 Claude 模型——默认是 Anthropic 的最新款,你也能用 model 选项指定某个(比如 claude-sonnet-5 或 claude-opus-4-8)。走网关时,你可以选那个网关提供的任何 Claude 模型,这对在日常智能体跑动上用更便宜的模型很方便。

Claude Agent SDK 免费吗？

SDK 免费、开源,但跑智能体要花 Claude API token,而多轮智能体循环用得很快。控制花费:日常活选更便宜的模型、设 max_turns、限制工具访问——并靠内置的 prompt 缓存,它把重复的系统提示词以约输入价十分之一供给。