Claude Agent SDK

tags: [AI, Agent, SDK, Anthropic, 基础设施]
created: 2026-04-14
updated: 2026-04-28
sources: [raw/notes/claude-agent-sdk-research-2026.md, raw/notes/founder-park-creao-organizational-pivot-2026.md, raw/notes/google-agent-platform-research-2026-04-28.md]

定义¶

Anthropic 将 Claude Code 的完整 Agent 运行时开放为开发者库（Python / TypeScript）。不是 API 端点，不是轻量封装——它捆绑了 Claude Code CLI 的整个运行时，包括已实现的工具（文件读写、Shell 执行、代码编辑、Web 搜索）、Agent 循环、上下文管理和 MCP 集成。

与所有其他 Agent 框架的根本区别：Batteries-included。 开发者不需要自己实现工具执行。

首发：2025-06-11
许可证：MIT
Python: pip install claude-agent-sdk（v0.1.59）
TypeScript: npm install @anthropic-ai/claude-agent-sdk（v0.2.107）

架构¶

应用代码 → SDK query() → 本地 Claude Code CLI 子进程
                              │
                     JSON-over-stdio 通信
                              │
                     ┌────────┴────────┐
                     │  Agent 循环      │
                     │  1. 调 Messages API │
                     │  2. 执行工具（本地）│
                     │  3. 反馈结果      │
                     │  4. 重复直到完成   │
                     └─────────────────┘

关键特性： - Agent 循环内置：LLM 自判是否完成目标，不是单次调用 - 上下文管理：跨 turn 累积、静态内容 prompt cache、接近限制自动 compaction - Subagent 隔离：子 Agent 独立上下文，只返回最终结果（区别于 OpenAI 的 Handoff 共享上下文模式）

核心概念¶

概念	含义
Agent	system prompt + 工具集 + 权限的 Claude 实例
Session	有状态会话，支持恢复/继续/分叉，本地持久化
Turn	一轮"Claude 输出 → 工具执行 → 反馈"循环
Subagent	隔离上下文的子 Agent，非 Handoff
Hooks	生命周期回调（PreToolUse/PostToolUse/Stop 等），可拦截/审计
权限	allowed_tools / disallowed_tools / permission_mode / can_use_tool 回调

API 设计¶

两个接口对应两种使用模式：

# 一次性任务——每次新 session
async for msg in query(
    prompt="修复 auth.py 的 bug",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash"],
        max_turns=30,
        max_budget_usd=5.0,
    ),
):
    ...

# 持续对话——复用同一 session
client = ClaudeSDKClient(options=...)
async for msg in client.send("第一个任务"): ...
async for msg in client.send("继续"):     ...  # 同一上下文

关键控制参数：max_turns（循环上限）、max_budget_usd（成本上限）、model（可为 subagent 指定不同模型）。

MCP 集成¶

四种 MCP 服务器类型：

类型	说明
Stdio	子进程，标准 MCP 模式
SSE	远程，Server-Sent Events
HTTP	远程，请求-响应
SDK Server	进程内，零 IPC 开销（独有特性）

进程内 SDK Server 意味着可以用 Python/TypeScript 函数直接定义 MCP 工具，无需启动额外进程——部署和调试都更简单。

与其他框架的对比¶

	Claude Agent SDK	OpenAI Agents SDK	LangChain/LangGraph	CrewAI
工具执行	内置	开发者实现	开发者实现	开发者实现
抽象层级	极少（async iterator）	少	大量	中等
供应商	仅 Claude	仅 OpenAI	多供应商	多供应商
委托模型	Subagent（隔离）	Handoff（共享上下文）	Graph 节点	Crew/Task
MCP	一等公民 + 进程内	适配器	适配器	有限

OpenAI Handoff vs Anthropic Subagent：Handoff 在 Agent 之间转移控制权并共享上下文；Subagent 每次启动全新上下文，只返回结果。Subagent 模式更安全（无上下文泄漏），但信息传递更受限。

部署与资源¶

每实例：~1 GiB RAM、~5 GiB 磁盘、1 CPU（包含 Node.js 运行时）
支持 Bedrock / Vertex AI / Azure 认证
四种部署模式：临时容器 / 长驻容器 / 混合（临时+历史注入）/ 单容器多进程
沙箱支持：Modal、Cloudflare、E2B、Fly、Vercel、Docker

局限¶

单一供应商锁定：仅支持 Claude
资源开销：每实例需 Node.js 子进程，不适合大规模轻量任务
托管服务缺失：文档中提到的 /v1/agents /v1/sessions 端点目前 404，疑似未发布
成本不可控：开放式 prompt 不设限制可能消耗大量 API 额度
无对等 Agent 通信：只有父→子层级，无 Agent 间直接通信

与 Harness Engineering 的关系¶

Claude Agent SDK 是 harness-engineering 的产品化交付物——把 Claude Code 51 万行 TypeScript 中的 Harness 能力（五层上下文压缩、缓存经济学、工具执行、权限控制）封装为可嵌入的库。

这也是 platform-layer-collapse 的最新进展：Anthropic 从模型层继续向下吃，不仅提供模型 API，还提供完整的 Agent 运行时，进一步压缩中间层框架（LangChain 等）的生存空间。

对 Sentino 的评估¶

Sentino 的 standalone agent 需要的工具是平台侧能力（查设备状态、调 API、读用户数据、发通知），而非 SDK 内置的文件/Shell 操作。因此更合适的路径是：

借鉴 SDK 的 Agent Loop 模式（LLM 自判目标完成）
自建轻量 Agent Loop，接入平台自有工具
不锁定单一供应商

但 SDK 的设计决策值得参考：max_turns + max_budget_usd 双重限制、Subagent 隔离模式、Hook 生命周期回调。

同类对标：Google ADK（Agent Development Kit）¶

Google Gemini Enterprise Agent Platform Build 柱的 ADK（Agent Development Kit） 是 Anthropic Claude Agent SDK 的同类对标——模型厂商出的 agent SDK：

维度	Claude Agent SDK	Google ADK
模型绑定	仅 Claude	仅 Gemini（但 Model Garden 200+ 模型可作为 agent 调用对象）
编排模式	父→子 Subagent（层级，单次启动新上下文）	2026 升级 graph-based 子 agent 网络——显式 DAG 编排子 agent 间协作
MCP 支持	一等公民 + 进程内 SDK Server	一等公民 + 与 Agent Gateway 集成
工具执行	内置（文件/Shell/编辑/Web 搜索）	通过 Native Ecosystem Integrations 接 BigQuery / Pub/Sub 等
资源开销	每实例 ~1 GiB RAM + Node.js 子进程	google-adk Python 包 + Vertex AI 推理
部署模式	临时容器 / 长驻 / 沙箱（Modal/Cloudflare/E2B 等）	Agent Runtime sub-second cold starts + Agent Sandbox hardened 执行环境
治理集成	弱（开发者自己实现）	与 Agent Identity / Registry / Gateway 全栈集成

ADK 2026 graph-based 升级的行业含义¶

ADK v1.0 stable + google-adk PyPI 2026-04-21 发布，核心升级是graph-based 子 agent 网络——之前是线性子 agent，现在是显式 DAG 编排。Google 官方宣传 "unlock more powerful reasoning by organizing agents into a network of sub-agents"。

这是回应 LangGraph，反映 2026 行业从"单 agent + tool-calling"到"orchestrated 多 agent"的转向。三种路径并存：

路径	代表	哲学
显式 graph 编排	Google ADK 2026 / LangGraph	子 agent 间协作要 DAG 编排
父→子 Subagent（层级）	Claude Agent SDK	单次启动新上下文，只返回最终结果
无编排	orchestration-free-agents Carlini	文件锁 + Git + 自组织任务池

Sentino 的判断：当前是单 agent + 工具化集成 + Standalone Agent 数据生产者模式（sentino-agent），没有显式 graph-based 子 agent 编排。三条路径并存于 2026 行业，Sentino 选哪条要在客户场景需求明确后再定——但当前不必跟随 Google ADK graph 化。Standalone Agent + Amphiflow（amphiflow-pattern）路径已经在自己的成本-灵活度平衡点上。

行业第二独立样本：CREAO 也是评估后选择自建¶

CREAO 在 2026-04 Founder Park 访谈中披露同向决策（详见 ai-first-engineering）：

早期直接用 Claude Code 但启动时间 10-20s 不可接受，自建架构深度优化到 <5 秒。

"这件事只有充分了解自己整套架构才能做到——OpenClaw 这种开源框架要面向各种环境无法对特定场景做性能优化。"

含义： - 行业头部 AI 创业（CREAO + Sentino）都在评估 Claude Code / Claude Agent SDK 后选择自建轻量实现——这给"自建 Agent Loop"决策提供了第二独立样本 - 主要理由都是性能优化与场景适配——SDK 的~1 GiB RAM + Node.js 子进程开销在追求高并发/低延迟的场景下不合适 - SDK 的设计哲学（Agent Loop / Subagent 隔离 / Hook 生命周期）仍然值得借鉴，只是不直接采用其实现

对 sentino-agent 的强化：本来 Sentino 自建 Agent Loop 是单一团队判断，现在有了 CREAO 同向证据——可以在对外材料/团队对齐时引用作为决策合理性的行业背书。

定义¶

架构¶