SupaStore

返回博客列表

Claude Agent SDK 怎么用?用 Python / TypeScript 搭建 AI Agent 入门教程(2026)

Claude Agent SDK 怎么用?本文讲清 Claude Agent SDK 是什么、与 Claude API 的区别,演示 Python 与 TypeScript 安装和 query() 用法,配置内置工具、权限模式、自定义工具、会话与成本统计,并附从 Claude Code SDK 迁移的注意事项和常见问题。

SupaStore 开发者体验组 ·

Claude Agent SDK 怎么用?用 Python / TypeScript 搭建 AI Agent 入门教程(2026)

Claude Agent SDK 是 Anthropic 把 Claude Code 的智能体能力打包成的开发库:你写一个提示词和几行配置,Agent 就能自己读写文件、执行命令、搜索网页,并循环调用工具直到完成任务。它支持 Python 和 TypeScript,适合用来搭建代码助手、运维机器人、数据分析 Agent 等应用。

本文讲清 Claude Agent SDK 和 Claude API 的区别,演示 Python、TypeScript 的安装与第一个 Agent,再介绍工具、权限、自定义工具、会话和成本统计。


Claude Agent SDK 和 Claude API 有什么区别

对比项 Claude API(Messages API) Claude Agent SDK
本质 一次请求、一次回答 内置 Agent 循环,自动多轮调用工具
工具 需要自己定义并执行 自带读写文件、执行命令、搜索等工具
上下文管理 自己维护对话历史 SDK 自动管理会话
适合 问答、分类、提取、生成 需要自主完成多步任务的 Agent

简单说:只是让模型回答问题,用 Claude API 就够了(入门见《Claude API 调用教程:Python 接入 Claude API 完整示例》);需要模型自己动手完成一系列操作,用 Claude Agent SDK 能省掉大量循环和工具执行的代码。自己实现工具调用的方法见《Claude 工具调用怎么用?》。


安装 Claude Agent SDK

Python(需要 Python 3.10 及以上):

pip install claude-agent-sdk

TypeScript(需要 Node.js 18.14 及以上):

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

两个 SDK 都自带了 Claude Code 的运行程序,大多数情况下不需要另外安装 Claude Code。

然后设置 API Key:

export ANTHROPIC_API_KEY="your-api-key"

SDK 不会自动读取 .env 文件,需要的话请自己用 dotenv 加载。Key 的获取方法见《Claude API Key 怎么获取?》。


第一个 Agent:Python 示例

下面的 Agent 会自己找到并修复 utils.py 里的 bug:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="检查 utils.py 中会导致崩溃的 bug,并修复它们",
        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 hasattr(block, "name"):
                    print(f"调用工具:{block.name}")
        elif isinstance(message, ResultMessage):
            print(f"完成:{message.subtype}")

asyncio.run(main())

query() 会以流的形式不断返回消息:AssistantMessage 是 Claude 的回复和工具调用,ResultMessage 是任务结束时的结果。subtype 为 success 表示正常完成,error_max_turns 表示达到了最大轮数。


TypeScript 示例

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

for await (const message of query({
  prompt: "检查 utils.py 中会导致崩溃的 bug,并修复它们",
  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);
      else if ("name" in block) console.log(`调用工具:${block.name}`);
    }
  } else if (message.type === "result") {
    console.log(`完成:${message.subtype}`);
  }
}

TypeScript 的选项名是驼峰写法:allowedTools、permissionMode、maxTurns、systemPrompt。


常用配置项

Python TypeScript 作用
allowed_tools allowedTools 允许 Agent 使用的工具,如 Read、Edit、Bash、Glob、WebSearch
permission_mode permissionMode 权限模式,决定改文件、执行命令前是否需要确认
system_prompt systemPrompt 系统提示词
max_turns maxTurns 最大轮数,防止 Agent 无限循环
max_budget_usd maxBudgetUsd 预算上限(客户端估算)
model model 使用的模型
cwd cwd Agent 的工作目录

permission_mode 常用的取值有 default(敏感操作需要确认)、acceptEdits(自动接受文件修改)和 plan(只做规划不执行)。给 Agent 的权限应当"够用就好",尤其是在服务器上运行时,不要随意放开执行命令的权限。权限的概念和 Claude Code 一致,见《Claude Code 权限怎么设置?》。


自定义工具

除了内置工具,还可以把自己的函数注册成工具。Python 用 @tool 装饰器定义工具,再用 create_sdk_mcp_server 打包:

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions

@tool("get_order", "根据订单号查询订单状态", {"order_id": str})
async def get_order(args):
    status = "已发货"  # 这里换成你的数据库或接口查询
    return {"content": [{"type": "text", "text": f"订单 {args['order_id']}:{status}"}]}

orders = create_sdk_mcp_server(name="orders", version="1.0.0", tools=[get_order])

options = ClaudeAgentOptions(
    mcp_servers={"orders": orders},
    allowed_tools=["mcp__orders__get_order"],
)

注册后,工具名的格式是 mcp__服务器名__工具名,要加到 allowed_tools 里 Agent 才能调用。MCP 的概念见《Claude Code MCP 怎么配置?》。


多轮对话与成本统计

  • 单次任务用 query():每次调用默认是一个新会话,适合一次性的自动化任务;
  • 多轮对话用 ClaudeSDKClient:在同一个会话里连续交互,支持中途打断,适合聊天类应用;
  • 恢复会话:通过 resume 选项传入会话 ID,可以在之前的上下文上继续。

成本方面,Python 的 ResultMessage 带有 total_cost_usd 字段,记录本次任务的累计花费。流式模式下它是累计值,读最后一条结果即可,不要把每条加起来。


从 Claude Code SDK 迁移的注意事项

Claude Agent SDK 由 Claude Code SDK 更名而来:

  • 包名:Python 从 claude-code-sdk 改为 claude-agent-sdk,TypeScript 从 @anthropic-ai/claude-code 改为 @anthropic-ai/claude-agent-sdk;
  • Python 的 ClaudeCodeOptions 改名为 ClaudeAgentOptions;
  • 默认系统提示词变了:新版不再默认使用 Claude Code 的系统提示词。想保持原来的行为,需要显式指定 system_prompt={"type": "preset", "preset": "claude_code"}。

通过中转站使用 Claude Agent SDK

Agent SDK 底层运行的就是 Claude Code,Claude Code 读取的 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 等环境变量,可以通过系统环境变量或 env 选项传给 Agent。地址的填写方法与本地 Claude Code 相同,见《Claude API 中转怎么用?国内 Claude Code 中转站配置教程》。官方 SDK 文档没有专门说明这种用法,正式上线前请先用简单任务验证。


常见问题 (FAQ)

Q: Claude Agent SDK 免费吗?

答: SDK 本身免费开源,但 Agent 每一轮都会调用模型,按 Token 计费。Agent 任务往往要多轮调用,建议用 max_turns 和 max_budget_usd 控制单次任务的上限。

Q: Claude Agent SDK 可以用 Claude Pro 或 Max 订阅登录吗?

答: 不可以用于对外提供的产品。官方说明,除非事先获得批准,第三方开发者不能在基于 Agent SDK 的产品中提供 claude.ai 登录或使用订阅额度,应使用 API Key。

Q: Agent SDK 和 Claude Code 有什么关系?

答: Claude Code 是一个现成的命令行编程工具,Agent SDK 则把同样的 Agent 循环、工具和上下文管理能力开放成开发库,让你把它嵌入自己的程序。

Q: query() 和 ClaudeSDKClient 怎么选?

答: 一次性任务、脚本和定时任务用 query();需要和用户来回对话、根据上一轮结果决定下一步,或者需要中途打断时,用 ClaudeSDKClient。