Claude Agent SDK

Claude Agent SDK 是 Anthropic 把驱动 Claude Code 的那套 agent harness（agent loop、内置工具、上下文管理、权限系统）抽出来做成的编程库，提供 Python 和 TypeScript 两个版本。你不用再自己写 tool-use 循环，一个 query() 调用就能让 Claude 在你的应用进程里读文件、跑命令、改代码、搜网页，直到任务完成。

一、定位：Claude Code 的 harness，开放成 SDK

这个 SDK 的出身决定了它的气质。Anthropic 在 2025 年 9 月的官方博客里说得明白：Claude Code 在内部早已不只是编程工具——他们用同一个 harness 做深度研究、视频创作、笔记整理，"几乎驱动了我们所有主要的 agent loop"。于是他们把这个原本叫 Claude Code SDK 的库更名为 Claude Agent SDK，以反映它远不止于 coding 场景。更名发生在 2025 年 9 月，同月内完成（先以 Claude Code SDK 发布，月底更名），Python 包从 claude-code-sdk 迁移为 claude-agent-sdk，TypeScript 包从 @anthropic-ai/claude-code-sdk 迁移为 @anthropic-ai/claude-agent-sdk，核心配置类也从 ClaudeCodeOptions 改名为 ClaudeAgentOptions。

理解它的定位，最好的办法是跟 Anthropic 的底层 Messages API 对比：

维度	Messages API（Client SDK）	Claude Agent SDK
抽象层次	单次请求/响应	完整 agent loop
工具执行	你自己写 handler、自己拼结果回传	SDK 内置执行，读文件/跑 Bash 开箱即用
上下文管理	你自己维护 messages 数组	自动管理，接近上限自动 compaction
权限控制	无概念，全靠你自己拦	内建 permission mode / hooks / 工具白名单
会话持久化	自己存数据库	会话以 JSONL 落盘，可跨进程 resume
适用	聊天、结构化抽取、自定义 loop	长任务、多步骤、需要操作真实环境的 agent

一个常见的比喻：Messages API 是引擎，Agent SDK 是整车。大多数想做 agent 的人要的是车。它的架构位置大致是：

┌─────────────────────────────────────────────┐
│            你的应用（Python / TS 进程）        │
│   query() / ClaudeSDKClient                  │
├─────────────────────────────────────────────┤
│        Claude Agent SDK（agent harness）      │
│  agent loop │ 权限系统 │ hooks │ compaction   │
│  子代理编排  │ 会话管理 │ MCP 客户端           │
├─────────────────────────────────────────────┤
│        Claude Code CLI（SDK 自动捆绑）         │
│  Read/Write/Edit/Bash/Glob/Grep/WebSearch... │
├─────────────────────────────────────────────┤
│        Claude 模型（Anthropic API /           │
│        Bedrock / Vertex / Foundry）           │
└─────────────────────────────────────────────┘

和 Claude Code 的关系

SDK 的 Python 包会自动捆绑对应平台的 Claude Code CLI，不需要单独安装；TS 包同样内置原生二进制。所以"用 SDK"本质上是在你的进程里以编程方式驱动 Claude Code 的核心引擎，而不是在终端里跟人交互。关于产品形态本身，见 Claude Code 案例页。

二、核心理念：给模型一台计算机

SDK 的设计哲学在官方博客里被浓缩成一句话：give your agents a computer（给你的 agent 一台计算机）。不要给模型造一堆狭窄的 API 封装，而是给它程序员每天用的同一套工具——文件系统和终端——让它像人一样工作：找文件、写代码、跑起来、看报错、再改，迭代直到成功。

这个理念带来三个直接推论：

1. 文件系统就是 context 基础设施。 历史对话、文档、日志都存在目录里，agent 用 grep、tail、Glob 按需把信息捞进 context，而不是一开始全塞进去。文件夹结构本身就是一种 context engineering。
2. agentic search 优先于 semantic search。 官方明确建议：先用 agentic search（让 agent 自己 grep/翻文件），因为它更透明、更好维护；只有在需要更快响应或更多召回变化时才加向量检索。这与 RAG 章节讨论的取舍一脉相承。
3. 代码生成是通用能力，不只是 coding。 代码精确、可组合、可复用。agent 需要一个 Excel 报表？写一段 Python 脚本生成它，比任何专用工具都可靠。Claude.ai 的文件创建功能就是这么做的。

SDK 内置的 agent loop 遵循 Claude Code 验证过的循环：gather context → take action → verify work → repeat。内置工具集直接来自生产环境而非玩具演示，包括：

• 文件操作：Read、Write、Edit
• 命令执行：Bash（跑脚本、git、构建、测试）
• 代码导航：Glob（按模式找文件）、Grep（正则搜索内容）
• 联网：WebSearch、WebFetch
• 编排与人机交互：Agent（派生子代理）、AskUserQuestion（向用户提问）

关键点：这些工具你一行 handler 都不用写。对比手写 loop 时要为每个工具实现执行逻辑、序列化结果、处理错误，这是 Agent SDK 最实在的生产力来源。关于工具设计的通用原则，见 工具与 MCP。

三、核心能力

3.1 子代理（subagents）

SDK 原生支持子代理：主 agent 通过 Agent 工具把聚焦的子任务委派给专门的子代理，每个子代理有自己独立的 context window、工具集和系统提示，完成后只把结论汇报给主代理。这同时解决两个问题——并行化（多个子代理同时跑不同任务）和上下文隔离（子代理翻完几百封邮件，只回传相关摘录，不污染主上下文）。这正是 多智能体架构中 orchestrator-worker 模式的内置实现。

子代理有两种定义方式：代码里用 AgentDefinition 编程式定义，或像 Claude Code 一样在 .claude/agents/ 目录下放带 YAML frontmatter 的 Markdown 文件。

3.2 Skills

Agent Skills 是把领域专长打包成"指令 + 脚本 + 资源"的目录（含一个带 YAML frontmatter 的 SKILL.md），agent 根据 description 字段判断何时调用。SDK 通过 setting_sources 配置加载：

• setting_sources=["project"]：加载项目级 .claude/skills/，可随 git 与团队共享
• 包含 "user"：加载 ~/.claude/skills/ 下的个人 Skills
• 已安装的 Claude Code plugins 附带的 Skills 也可用

配置 setting_sources 后 Skill 工具会自动放行，无需手动加进 allowed_tools。这意味着 Claude Code 生态里积累的大量现成 Skills，你的 SDK agent 可以直接复用。

3.3 Hooks

Hook 是在 agent loop 特定事件点由 harness（不是模型） 调用的确定性函数，可用的事件点包括 PreToolUse、PostToolUse、Stop、SessionStart、SessionEnd、UserPromptSubmit 等。典型用途：

• 安全拦截：PreToolUse 里检查 Bash 命令，命中黑名单就返回 permissionDecision: "deny"
• 审计日志：PostToolUse 里把每次文件修改写入审计文件
• 结果加工：在工具结果返回给模型前做转换或脱敏

Hook 的价值在于"确定性"——模型行为是概率性的，但合规和审计要求是硬性的，这类逻辑不该交给模型自觉。更多安全设计见 Agent 安全。

3.4 MCP 集成

SDK 内置 MCP 客户端，支持两类服务器：

• 外部 MCP server：stdio 子进程或远程 HTTP/SSE，接入 Playwright、数据库、第三方 API 等几百个现成 server
• 进程内 SDK MCP server（create_sdk_mcp_server）：把 Python/TS 函数直接变成 agent 可调用的工具，无子进程、无 IPC 开销、类型安全，两者还能混用

进程内 MCP server 是 SDK 的一个甜点功能：自定义工具的开发和调试体验跟写普通函数完全一样，部署也只有一个进程。

3.5 权限系统

SDK 把 Claude Code 的权限模型完整搬了过来，决策链大致是：allowed_tools 白名单 → permission_mode → can_use_tool 回调 → hooks。几个要点：

• allowed_tools 是自动批准白名单，不是工具可用性开关；要禁用工具用 disallowed_tools
• permission_mode 常用的有："default"（什么都问）、"acceptEdits"（自动接受文件编辑）、"bypassPermissions"（全自动，CI/CD 场景）、"plan"（先出计划再执行）
• can_use_tool 回调让你用代码实现任意复杂的审批逻辑（比如"写操作只允许在 src/ 目录下"）

生产环境别裸奔

很多教程为了演示直接 permission_mode="bypassPermissions" 加全部工具。放到服务器上跑之前，至少要做到：Bash 命令过 hook 审查、写操作限定目录、关键操作走 can_use_tool 人工确认。agent 拥有计算机访问权，意味着 prompt injection 的攻击面就是整台机器。

3.6 会话管理

SDK 的会话以 JSONL 文件持久化在磁盘上，三个原语覆盖大多数场景：

• resume：按 session ID 续接之前的会话，跨进程、跨天都行
• fork_session：从已有会话分叉，做"同一起点、不同探索"的分支实验
• 也可以每次新开会话、把上一轮的摘要注入 system prompt，做轻量接力

长流水线里常见的用法是：第一阶段分析完拿到 session_id，后续每个阶段 resume 接着干，完整的推理链全程保留。

3.7 上下文压缩（compaction）

长任务跑到 context 上限附近时，SDK 会自动对历史消息做摘要压缩（源自 Claude Code 的 /compact 能力），agent 不会因为 context 爆了而中断。这是"能跑几小时的长任务"的底层保障之一——当然，摘要是有损的，关键结论最好让 agent 随时写进文件，这也呼应了"文件系统即记忆"的理念。

四、代码示例

安装（Python 3.10+；Node 18+）：

pip install claude-agent-sdk            # Python，自动捆绑 Claude Code CLI
npm install @anthropic-ai/claude-agent-sdk   # TypeScript
export ANTHROPIC_API_KEY=your-api-key   # 或走 Bedrock / Vertex / Foundry

4.1 最小可用 agent（Python）

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="找出这个代码库里所有 TODO 注释并汇总",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],  # 只读 agent：自动批准这三个工具
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

query() 返回异步消息迭代器，消息类型包括 AssistantMessage（含 TextBlock/ToolUseBlock）、SystemMessage（subtype == "init" 时带 session_id）、ResultMessage（最终结果，含耗时与 token 用量）。逐条消费这个流，你就拿到了完整的执行过程，接日志或 可观测性系统都方便。

4.2 TypeScript 版本

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

for await (const message of query({
  prompt: "审查代码库中的常见安全问题（SQL 注入、XSS、硬编码密钥），写入 security-report.md",
  options: {
    allowedTools: ["Read", "Write", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",  // 自动接受文件编辑
  },
})) {
  if ("result" in message) console.log(message.result);
}

4.3 自定义工具（进程内 MCP server）

from claude_agent_sdk import (
    tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient,
)

# 用 @tool 装饰器把普通函数变成 agent 可调用的工具
@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

server = create_sdk_mcp_server(name="my-tools", version="1.0.0", tools=[greet_user])

options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"],  # 自定义工具命名规则：mcp__<server>__<tool>
)

# 自定义工具与 hooks 需要用支持双向交互的 ClaudeSDKClient
async with ClaudeSDKClient(options=options) as client:
    await client.query("向 Alice 打个招呼")
    async for msg in client.receive_response():
        print(msg)

4.4 用 hooks 做安全拦截

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher

async def block_dangerous_bash(input_data, tool_use_id, context):
    """PreToolUse hook：命中黑名单的 Bash 命令直接拒绝"""
    if input_data["tool_name"] != "Bash":
        return {}
    command = input_data["tool_input"].get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "禁止执行 rm -rf",
            }
        }
    return {}

options = ClaudeAgentOptions(
    allowed_tools=["Bash"],
    hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[block_dangerous_bash])]},
)

4.5 子代理与会话续接

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, SystemMessage

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep", "Agent"],  # 放行 Agent 工具才能派生子代理
    agents={
        "code-reviewer": AgentDefinition(
            description="资深代码审查员，关注质量与安全",
            prompt="分析代码质量，标记潜在问题，只汇报结论。",
            tools=["Read", "Glob", "Grep"],  # 子代理自己的工具集
        )
    },
)

session_id = None
async for message in query(prompt="让 code-reviewer 审查这个代码库", options=options):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        session_id = message.data["session_id"]

# 后续任务在同一个会话上续接，保留完整上下文
async for message in query(
    prompt="根据审查结果修复最严重的三个问题",
    options=ClaudeAgentOptions(resume=session_id, allowed_tools=["Read", "Edit", "Bash"]),
):
    pass

一个容易踩的坑

SDK 默认会继承 Claude Code 的身份设定——不覆盖的话，你的 agent 会自称是 "Claude Code"。两个做法：用 system_prompt 覆盖身份；用 setting_sources=[] 做完全隔离，不加载任何用户/项目级配置（.claude/、CLAUDE.md、Skills 都不读）。生产部署建议显式设置这两项，避免本地调试和线上行为不一致。

五、与 Claude Code 的关系：同一 harness 的两种形态

可以这样理解两者的分工：

        同一套 agent harness（loop / 工具 / 权限 / hooks）
        ┌──────────────────┴──────────────────┐
   Claude Code（产品化形态）          Claude Agent SDK（编程化形态）
   终端里的交互式 coding agent        嵌入你自己应用的库
   人坐在方向盘前                     你的代码坐在方向盘前
   CLAUDE.md / .claude/ 配置          query() 参数编程配置

实践上的推论：

• 生态共享。.claude/skills/、.claude/agents/、CLAUDE.md、MCP 配置两边通用。在 Claude Code 里调好的 Skill，SDK agent 设 setting_sources=["project"] 就能直接用。
• 调试路径。SDK agent 行为诡异时，可以把同样的任务丢给终端里的 Claude Code 复现，排除是不是 harness 层面的问题。
• 迭代极快。SDK 跟随 Claude Code 的节奏发版，TypeScript 包 2026 年 8 月的 npm latest 已到 0.3.x（0.3.231），Python 包在 0.1.x——API 表面仍可能有小破坏，升级前看 CHANGELOG，版本号要锁死。

六、适用场景

SDK 官方博客给出的典型方向：金融分析 agent（读组合、调外部 API、跑计算）、个人助理（订行程、管日历、跨应用跟踪上下文）、客服 agent（处理高模糊度工单、必要时升级给人）、深度研究 agent（跨大量文档检索、交叉比对、生成报告）。结合社区实践，它的甜区可以归纳为三句话：

1. 长任务。自动 compaction + 会话持久化 + 子代理上下文隔离，让它能跑以小时计的任务——这是大多数手写 loop 框架要费很大劲才能做到的。
2. 编码与工程自动化。继承 Claude Code 的全部家底：代码审查、重构、修 bug、跑测试、git 操作、CI 里的自动修复 agent。
3. 研究/运营类"数字工作"agent。只要任务能归结为"操作文件、跑命令、调 API"，比如报表生成、日志分析、SRE 巡检机器人、内容管线，这套"给模型一台计算机"的打法都成立。

反过来说，以下场景它不是最优解：纯聊天/结构化抽取（用 Messages API 更轻）；需要精细控制每一步状态流转的图式编排（看 LangGraph）；多模型混编或非 Claude 模型（见下节）。

七、优缺点与厂商锁定

优点	缺点
harness 经过 Claude Code 大规模生产验证，不是纸面设计	只支持 Claude 模型，模型层不可替换
内置工具开箱即用，省掉大量胶水代码	版本迭代快，0.x 阶段 API 偶有小破坏
权限/hooks/compaction 等生产关切内建	harness 行为是黑盒，细粒度控制不如自写 loop
与 Claude Code 生态（Skills、MCP、插件）无缝复用	捆绑 CLI 二进制，部署体积与平台兼容性要考虑
Python/TS 双语言，会话 JSONL 可审计可回放	深度定制（换 loop、换 context 策略）空间有限

关于厂商锁定，值得说透一点：你锁定的其实不是"API 接口"（那层换起来不难），而是围绕这套 harness 沉淀的工程资产——CLAUDE.md、Skills、子代理定义、hooks、权限策略。这些资产都跟 Claude Code 的约定深度绑定，迁去别的框架基本要重写。所以选型决策应该是：你认可"gather context → take action → verify"这套循环和"给模型一台计算机"的哲学吗？认可，锁定就是深度整合的红利；不认可，从第一天就该选自写 loop 或更中立的编排框架（参见 框架选型总览 和 OpenAI Agents SDK 的对比）。

选型判断

如果你的任务是"让一个 agent 在真实环境里把事情办完"，而不是"研究 agent 架构本身"，Claude Agent SDK 在 2026 年是默认答案之一。自写 loop 的理由只剩下两个：需要模型中立，或者需要 harness 给不了的控制粒度。想亲手写一遍 loop 建立直觉，看 从零构建 Agent。

参考资料

• Building agents with the Claude Agent SDK — Anthropic Engineering —— 官方更名公告与设计理念，"给 agent 一台计算机"的出处
• anthropics/claude-agent-sdk-python (GitHub) —— Python SDK 官方仓库，含 query/ClaudeSDKClient/hooks/自定义工具完整示例
• anthropics/claude-agent-sdk-typescript (GitHub) —— TypeScript SDK 官方仓库与迁移指南
• TypeScript SDK Releases —— 发版记录，可查证最新版本与破坏性变更
• Claude Agent SDK 官方文档 —— 配置项、权限、会话、Skills 的权威参考
• How to Use the Claude Code API and Agent SDK — fast.io —— 2026 年中的实战教程，子代理/hooks/MCP 示例出处
• Claude Agent SDK provider — promptfoo —— SDK 接入 eval 框架的配置参考，含 setting_sources 与 Skills 细节