精读：Claude Agent SDK

2025 年 9 月以”Claude Code SDK”发布，2026 年 5 月更名为”Claude Agent SDK”。这次更名不只是改名——它标志着 Claude Code 的引擎能力从编码场景扩展到通用 Agent 平台。

产品定位演变

Claude Code CLI (2025.2)
    │
    ▼
Claude Code SDK (2025.9) ← "用 Claude Code 引擎构建编程 Agent"
    │
    ▼
Claude Agent SDK (2026.5) ← "用 Claude Code 引擎构建任意 Agent"

更名背后的战略意图

维度	Claude Code SDK（旧）	Claude Agent SDK（新）
场景	编程自动化	通用 Agent 构建
目标用户	开发者	开发者 + 企业 + 平台商
能力边界	代码读写/搜索/执行	+ 研究/视频/笔记/数据分析
竞品	OpenAI Codex SDK	OpenAI Agents SDK

架构概览

SDK 与 CLI 的关系

┌─────────────────────────────────────────────────────┐
│                  Claude Agent SDK                     │
│  ┌──────────────────────────────────────────────┐   │
│  │              Core Engine                       │   │
│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐       │   │
│  │  │Agent │ │Tool  │ │Context│ │Perm  │       │   │
│  │  │Loop  │ │Exec  │ │Mgmt  │ │Model │       │   │
│  │  └──────┘ └──────┘ └──────┘ └──────┘       │   │
│  └──────────────────────────────────────────────┘   │
│                         │                            │
│         ┌───────────────┼───────────────┐           │
│         ▼               ▼               ▼           │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐   │
│  │ Claude Code│  │ Custom App │  │ Enterprise │   │
│  │ CLI        │  │ (SDK 构建)  │  │ Agent      │   │
│  └────────────┘  └────────────┘  └────────────┘   │
└─────────────────────────────────────────────────────┘

关键理解：Claude Code CLI 本身就是 Claude Agent SDK 的一个”应用”。SDK 暴露了 CLI 内部使用的同一套引擎。

核心能力复用

SDK 暴露的能力	对应 CLI 内部
Agent Loop API	queryLoop（AsyncGenerator 驱动）
Tool Registration	40 方法/属性的工具接口契约
Permission Model	4 层权限分类器
Context Management	自动压缩 + Prompt Caching
MCP Integration	7 种传输 + OAuth + Elicitation
Hook System	21 个事件 + 3 种 handler
Multi-Agent	SubAgent / Swarm / Workflow

SDK API 设计

Python SDK

from claude_agent_sdk import Agent, Tool, Session

# 定义自定义工具
@Tool(name="search_docs", description="搜索内部文档")
async def search_docs(query: str) -> str:
    # 自定义实现
    return await internal_search(query)

# 创建 Agent
agent = Agent(
    model="opus-4.8",
    system_prompt="你是一个研究助手...",
    tools=[search_docs],
    permissions="auto",  # 使用 AI 分类器
    max_turns=50,
)

# 运行
async with Session(agent) as session:
    result = await session.run("分析 Q2 销售数据趋势")
    print(result.final_message)

TypeScript SDK

import { Agent, Tool, Session } from '@anthropic/agent-sdk';

const searchDocs = Tool.define({
  name: 'search_docs',
  description: '搜索内部文档',
  parameters: { query: { type: 'string' } },
  execute: async ({ query }) => internalSearch(query),
});

const agent = new Agent({
  model: 'opus-4.8',
  systemPrompt: '你是一个研究助手...',
  tools: [searchDocs],
  permissions: 'auto',
});

const session = await Session.create(agent);
const result = await session.run('分析 Q2 销售数据趋势');

三种产品形态复用

形态 1：CLI（Claude Code）

SDK 引擎 + 终端 UI（Ink/React）+ 本地文件工具集

SDK Engine → Terminal UI → 用户直接交互

形态 2：IDE 扩展

SDK 引擎 + IDE 协议适配 + 编辑器工具集

SDK Engine → VS Code Extension Protocol → IDE 内嵌面板
SDK Engine → JetBrains Plugin API → IDE 内嵌面板

形态 3：自定义 Agent（企业/平台）

SDK 引擎 + 自定义工具集 + 自定义 UI

SDK Engine → Custom Tools + Custom UI → 企业场景
                                         ├── 客服 Agent
                                         ├── 研究 Agent
                                         ├── 数据分析 Agent
                                         └── 运维 Agent

与 OpenAI Agents SDK 对比

维度	Claude Agent SDK	OpenAI Agents SDK
定位	Claude Code 引擎的可编程封装	通用多 Agent 编排框架
依赖	绑定 Anthropic API	绑定 OpenAI API
Agent Loop	内置完整（queryLoop）	内置完整（Runner）
多 Agent	内置 Swarm/Workflow	内置 Handoff/Orchestration
工具系统	与 Claude Code 共享 40 方法接口	独立定义（更轻量）
MCP	深度集成（7 种传输）	客户端集成（连接外部 server）
沙箱	应用层 AI 分类器	无内置（依赖外部）
Tracing	无官方内置	内置 tracing + evaluation
语言	Python + TypeScript	Python + JavaScript
开源	闭源（API 调用）	开源（Apache-2.0）
生态	Plugin Marketplace	社区 MCP Servers

核心差异

Claude Agent SDK = “把 Claude Code 这辆完整的车给你开”——包含引擎、底盘、安全系统、导航，你只需要定义目的地和路线。

OpenAI Agents SDK = “给你一套积木让你搭车”——提供轮子、发动机、方向盘的标准接口，你自己组装。

SDK 解锁的非编码场景

深度研究 Agent

research_agent = Agent(
    model="opus-4.8",
    tools=[web_search, pdf_reader, citation_manager],
    system_prompt="系统性文献综述...",
    context_window="200k",
)

数据分析 Agent

data_agent = Agent(
    model="sonnet-5",
    tools=[sql_executor, chart_generator, report_writer],
    system_prompt="分析 CSV/数据库并生成可视化报告...",
)

视频制作 Agent

video_agent = Agent(
    model="opus-4.8",
    tools=[script_writer, storyboard_gen, video_editor_api],
    system_prompt="从概念到成片的视频制作...",
)

运维 Agent

ops_agent = Agent(
    model="sonnet-5",
    tools=[kubectl_exec, log_searcher, alert_manager],
    system_prompt="Kubernetes 集群运维自动化...",
    permissions="strict",  # 运维场景需要严格权限
)

企业级特性

特性	说明
MDM 部署	managed-settings.json 统一配置
SSO 集成	SAML/OIDC 企业认证
审计日志	所有工具调用和权限决策可追溯
Usage Limits	按团队/项目设置 token 预算
Managed MCP	企业管理员统一配置 MCP 服务器
Custom Models	支持 fine-tuned 模型接入

SDK 版本与 Claude Code 版本关系

SDK 版本	对应 Claude Code	说明
0.1.x (2025.9)	v1.0.x	初始发布，编码专用
0.2.x (2025.12)	v2.0.x	MCP + Hook 集成
1.0.x (2026.3)	v2.1.x	Multi-Agent + Auto Mode
1.1.x (2026.5)	v2.1.150+	更名为 Agent SDK
1.2.x (2026.6)	v2.1.185	当前最新，Opus 4.8

对竞品格局的影响

前：工具之争

Claude Code vs Codex vs Cursor vs Windsurf vs ...
（各自是一个编程工具）

后：平台之争

Claude Agent SDK vs OpenAI Agents SDK vs ...
（各自是构建 Agent 的基础平台）

战略含义：Anthropic 不再只卖”编程助手”，而是卖”构建任意 AI Agent 的引擎”。这把竞争升级到了平台层面。

交叉引用

Claude Code 生态定位 — 产品三形态与 SDK 关系
Claude Code 版本演进 — SDK 更名时间线
Claude Code 总架构 — queryLoop 引擎
Codex 多 Agent 编排 — OpenAI Agents SDK 对比
Claude Code vs Codex — 平台策略差异