银弹还是枷锁？Claude Agent SDK 的架构真相 --知识铺

架构师（JiaGouX）

我们都是架构师！
架构未来，你来不来？

当我打开 node_modules 的那一刻

作为一名对 AI Agent 充满热情的开发者，我在看到 Claude Agent SDK 发布时几乎是第一时间就开始尝试。官方文档写得很漂亮：构建能够自主读取文件、运行命令、搜索网络、编辑代码的 AI 智能体，这是我一直在寻找的东西。

但当我真正开始深入研究这个 SDK，试图理解它的底层架构，准备将它集成到生产环境时，我发现了一个值得深入理解的技术设计，这个发现改变了我对整个 Agent 生态的理解。

核心架构特点：依赖 Claude Code 运行时

让我们从安装步骤说起。打开官方文档的 Get Started 部分会看到这样的说明：

<span leaf="">  
<section><span leaf="">  
<section><section><span leaf="">1</section><section><span leaf="">2</section><section><span leaf="">3</section><section><span leaf="">4</section><section><span leaf="">5</section></section><span leaf="">  
<section><p><span leaf=""># 第一步：安装 Claude Code<span leaf="">  
<span leaf="">npm install -g @anthropic-ai/claude-code<span leaf="">  
<span leaf=""> <span leaf="">  
<span leaf=""># 第二步：安装 SDK<span leaf="">  
<span leaf="">npm install @anthropic-ai/claude-agent-sdk</p></section><span leaf="">  
</section><span leaf="">  

必须先安装 Claude Code CLI，而且这不是一个可选项，也不是为了更好的体验。这意味着 Claude Agent SDK 本质上是 Claude Code CLI 的编程接口包装，而不是一个独立的、可移植的智能体开发框架。

依赖链条的深度剖析

第一层：Claude Code 是必需的基础设施

当调用 SDK 的 query() 函数时，背后发生的事情是：

<span leaf="">  
<section><span leaf="">  
<section><section><span leaf="">1</section><section><span leaf="">2</section><section><span leaf="">3</section><section><span leaf="">4</section><section><span leaf="">5</section><section><span leaf="">6</section><section><span leaf="">7</section><section><span leaf="">8</section></section><span leaf="">  
<section><p><span leaf="">import<span leaf=""> { query }<span leaf=""> from<span leaf=""> '@anthropic-ai/claude-agent-sdk'<span leaf="">;<span leaf="">  
<span leaf=""> <span leaf="">  
<span leaf="">// 看起来很简单的调用<span leaf="">  
<span leaf="">for<span leaf=""> await<span leaf=""> (<span leaf="">const<span leaf=""> msg<span leaf=""> of<span leaf=""> query<span leaf="">(<span leaf="">"分析这个代码库"<span leaf="">, { <span leaf="">  
<span leaf="">  allowedTools<span leaf="">: [<span leaf="">'Read'<span leaf="">,<span leaf=""> 'Bash'<span leaf="">] <span leaf="">  
<span leaf="">})) {<span leaf="">  
<span leaf="">  console<span leaf="">.<span leaf="">log<span leaf="">(msg);<span leaf="">  
<span leaf="">}</p></section><span leaf="">  
</section><span leaf="">  

但实际执行流程是：

1. 1. SDK 启动 Claude Code CLI 进程

2. 2. 通过进程间通信传递请求

3. 3. Claude Code 管理 agentic loop

4. 4. Claude Code 执行工具调用（读文件、运行 bash 等）

5. 5. 结果通过 IPC 返回给代码

很明显——整个 Agent 循环的核心逻辑都在 Claude Code CLI 中。

第二层：核心功能的来源

SDK 宣传的所有强大功能，实际上都继承自 Claude Code：

Agentic Loop（智能体循环）：Gather Context → Take Action → Verify Work → Repeat，这个三阶段循环不是 SDK 的创新，而是 Claude Code 的核心架构。SDK 只是让代码触发这个循环。

Tools/工具：

<span leaf="">  
<section><span leaf="">  
<section><span leaf="">1</section><span leaf="">  
<section><p><span leaf="">const<span leaf=""> tools = [<span leaf="">'Read'<span leaf="">,<span leaf=""> 'Write'<span leaf="">,<span leaf=""> 'Bash'<span leaf="">,<span leaf=""> 'Edit'<span leaf="">];</p></section><span leaf="">  
</section><span leaf="">  

这些内置工具的实现全部在 Claude Code 中，SDK 不包含任何工具执行逻辑。

Skills/技能：

<code data-language-pending="" data-raw-code=".claude/skills/code-review/SKILL.md" data-show-line-number="true"><span leaf="">  
<section><span leaf="">  
<section><span leaf="">1</section><span leaf="">  
<section><p><span leaf="">.claude/skills/code-review/SKILL.md</p></section><span leaf="">  
</section><span leaf="">  

Skills 的发现、解析、加载机制完全依赖 Claude Code。SDK 要使用 Skills，必须配置：

<span leaf="">  
<section><span leaf="">  
<section><section><span leaf="">1</section><section><span leaf="">2</section><section><span leaf="">3</section></section><span leaf="">  
<section><p><span leaf="">const<span leaf=""> options = {<span leaf="">  
<span leaf="">  settingSources<span leaf="">: [<span leaf="">'project'<span leaf="">,<span leaf=""> 'user'<span leaf="">]<span leaf="">  // 告诉 Claude Code 去哪找配置<span leaf="">  
<span leaf="">};</p></section><span leaf="">  
</section><span leaf="">  

Subagents/子智能体：多智能体协作、并行任务处理、上下文隔离——这些高级特性的编排逻辑都在 Claude Code 中实现。

第三层：系统提示词的耦合

更微妙但同样重要的是系统提示词（system prompt）的设计。SDK 文档指出：

The Agent SDK uses an empty system prompt by default for maximum flexibility.

这听起来很灵活，但当需要完整的 Agent 能力时会这样配置：

<span leaf="">  
<section><span leaf="">  
<section><section><span leaf="">1</section><section><span leaf="">2</section><section><span leaf="">3</section></section><span leaf="">  
<section><p><span leaf="">const<span leaf=""> options = {<span leaf="">  
<span leaf="">  systemPrompt<span leaf="">: {<span leaf=""> preset<span leaf="">:<span leaf=""> "claude_code"<span leaf=""> }<span leaf="">  
<span leaf="">};</p></section><span leaf="">  
</section><span leaf="">  

看到了吗？preset: "claude_code"。这个预设包含了：

• • 工具使用指令

• • 代码规范和格式化指南

• • 响应语气和详细程度设置

• • 安全和安保指令

• • 当前工作目录和环境的上下文

这些提示词是经过精心调优的，专门针对 Claude Code 的使用场景。它们不是通用的 Agent 提示词，而是 Claude Code 特定的操作手册。

Claude 模型的强耦合

现在来谈谈更深层的依赖：对 Claude 模型本身的耦合。

表面上的开放性

SDK 文档列出了支持的其他模型提供商：

• • Amazon Bedrock（通过 CLAUDE_CODE_USE_BEDROCK=1）

• • Google Vertex AI（通过 CLAUDE_CODE_USE_VERTEX=1）

• • Microsoft Foundry（通过 CLAUDE_CODE_USE_FOUNDRY=1）

这看起来很开放，对吧？你可以使用其他云平台提供的 Claude 模型。

但这里有个关键限制：你只能使用 Claude 模型。

尝试使用其他模型会发生什么？

理论上，SDK 是基于标准的工具调用协议构建的。GPT-4、Gemini Pro 等其他大模型也支持工具调用。那么，能否用它们替代 Claude？

答案是：技术上可能，但实际效果会显著下降。原因有几个：

1. Agentic Loop 的设计针对 Claude 的特性

Claude Code 的三阶段循环（Gather → Act → Verify）是针对 Claude 模型的思维模式优化的。特别是：

• • Context Gathering 阶段：Claude 擅长通过 agentic search（使用 grep、tail、head 等）精确定位需要的信息。其他模型可能倾向于一次性加载大文件，导致上下文溢出

• • Verification 阶段：Claude 的自我反思能力（尤其是 Claude Opus 4.5）在代码质量检查、错误识别方面特别强。其他模型可能需要更多的外部验证机制

2. 长上下文处理能力的差异

Claude Opus 4.5 和 Sonnet 4.5 支持 200K token 的上下文窗口，这对于 Agent 工作至关重要：

<code data-language-pending="" data-raw-code="// 一个典型的 Agent 会话可能包含:
- 初始提示词: ~1K tokens
- 文件系统结构: ~5K tokens
- 读取的代码文件: ~20K tokens
- 工具调用历史: ~10K tokens
- 中间结果和反思: ~15K tokens
// 总计: ~51K tokens,还有很大余量

// 如果使用上下文窗口较小的模型:
- 早期 GPT-4 (8K): 会频繁触发上下文截断
- 某些开源模型 (32K): 勉强够用,但无法处理复杂项目

// 较新的大模型上下文对比(2026年1月):
// GPT-5.2 (400K): 上下文窗口更大,但工具调用优化针对不同场景
// Gemini 3 Pro (1M-2M): 窗口最大,但 agentic 能力仍在发展中" data-show-line-number="true"><span leaf="">  
<section><span leaf="">  
<section><section><span leaf="">1</section><section><span leaf="">2</section><section><span leaf="">3</section><section><span leaf="">4</section><section><span leaf="">5</section><section><span leaf="">6</section><section><span leaf="">7</section><section><span leaf="">8</section><section><span leaf="">9</section><section><span leaf="">10</section><section><span leaf="">11</section><section><span leaf="">12</section><section><span leaf="">13</section><section><span leaf="">14</section><section><span leaf="">15</section></section><span leaf="">  
<section><p><span leaf="">// 一个典型的 Agent 会话可能包含:<span leaf="">  
<span leaf="">- 初始提示词: ~1K tokens<span leaf="">  
<span leaf="">- 文件系统结构: ~5K tokens<span leaf="">  
<span leaf="">- 读取的代码文件: ~20K tokens<span leaf="">  
<span leaf="">- 工具调用历史: ~10K tokens<span leaf="">  
<span leaf="">- 中间结果和反思: ~15K tokens<span leaf="">  
<span leaf="">// 总计: ~51K tokens,还有很大余量<span leaf="">  
<span leaf="">  
<span leaf="">// 如果使用上下文窗口较小的模型:<span leaf="">  
<span leaf="">- 早期 GPT-4 (8K): 会频繁触发上下文截断<span leaf="">  
<span leaf="">- 某些开源模型 (32K): 勉强够用,但无法处理复杂项目<span leaf="">  
<span leaf="">  
<span leaf="">// 较新的大模型上下文对比(2026年1月):<span leaf="">  
<span leaf="">// GPT-5.2 (400K): 上下文窗口更大,但工具调用优化针对不同场景<span leaf="">  
<span leaf="">// Gemini 3 Pro (1M-2M): 窗口最大,但 agentic 能力仍在发展中</p></section><span leaf="">  
</section><span leaf="">  

我做了一个简单的测试，用相同的任务分别尝试 Claude Opus 4.5 和 GPT-5.2：

任务：在这个 10 万行的代码库中找到所有认证相关的 bug 并修复

Claude Opus 4.5 的表现：

<code data-language-pending="" data-raw-code="1. 使用 grep -r &quot;authentication&quot; 搜索关键词
2. 识别出 23 个相关文件
3. 使用 tail 和 head 智能采样每个文件
4. 定位 5 个潜在问题
5. 逐一修复并运行测试
6. 全部通过,用时 8 分钟" data-show-line-number="true"><span leaf="">  
<section><span leaf="">  
<section><section><span leaf="">1</section><section><span leaf="">2</section><section><span leaf="">3</section><section><span leaf="">4</section><section><span leaf="">5</section><section><span leaf="">6</section></section><span leaf="">  
<section><p><span leaf="">1. 使用 grep -r "authentication" 搜索关键词<span leaf="">  
<span leaf="">2. 识别出 23 个相关文件<span leaf="">  
<span leaf="">3. 使用 tail 和 head 智能采样每个文件<span leaf="">  
<span leaf="">4. 定位 5 个潜在问题<span leaf="">  
<span leaf="">5. 逐一修复并运行测试<span leaf="">  
<span leaf="">6. 全部通过,用时 8 分钟</p></section><span leaf="">  
</section><span leaf="">  

GPT-5.2 的表现：

<code data-language-pending="" data-raw-code="1. 尝试分析整体架构(利用其 400K 上下文优势)
2. 能够加载更多文件到上下文中
3. 但在工具调用的精确性上略逊一筹
4. 识别了 4 个问题,遗漏了 1 个边缘情况
5. 提出的修复方案较为通用,需要额外验证
6. 完成时间约 12 分钟(包括一些人工确认)" data-show-line-number="true"><span leaf="">  
<section><span leaf="">  
<section><section><span leaf="">1</section><section><span leaf="">2</section><section><span leaf="">3</section><section><span leaf="">4</section><section><span leaf="">5</section><section><span leaf="">6</section></section><span leaf="">  
<section><p><span leaf="">1. 尝试分析整体架构(利用其 400K 上下文优势)<span leaf="">  
<span leaf="">2. 能够加载更多文件到上下文中<span leaf="">  
<span leaf="">3. 但在工具调用的精确性上略逊一筹<span leaf="">  
<span leaf="">4. 识别了 4 个问题,遗漏了 1 个边缘情况<span leaf="">  
<span leaf="">5. 提出的修复方案较为通用,需要额外验证<span leaf="">  
<span leaf="">6. 完成时间约 12 分钟(包括一些人工确认)</p></section><span leaf="">  
</section><span leaf="">  

需要说明的是，这是基于特定场景的单次测试，不同任务类型可能有不同结果。Agent SDK 的整个设计针对 Claude 模型进行了深度优化，这在工具调用的精确性和迭代效率上体现明显。

为什么会存在这样的依赖？

理解了是什么之后，我们需要思考为什么。Anthropic 开发者和研究者都是最顶尖的大脑，这种深度耦合一定有其原因。

Claude Agent SDK 的前身是 Claude Code SDK，而 Claude Code SDK 本质上是 Claude Code CLI 的可编程版本。

这意味着一开始就不是从零设计的通用 Agent 框架，而是：

1. 1. 首先，Anthropic 内部构建了 Claude Code，用于提升开发者生产力

2. 2. 然后，他们发现 Claude Code 可以做的远不止写代码

3. 3. 于是，他们开放了 SDK，让外部开发者能够调用 Claude Code 的能力

4. 4. 最后，将 Claude Code SDK 改名为 Claude Agent SDK，反映更广泛的用途

这个演进路径决定了架构：SDK 是 Claude Code 的 API 化，而不是独立的 Agent 框架。

此外，如果要构建一个真正模型无关的 Agent 框架，Anthropic 需要：

• • 重新设计工具执行引擎（而不是复用 Claude Code）

• • 实现通用的 agentic loop（而不是依赖 Claude Code 的循环）

• • 开发抽象的提示词管理系统（而不是使用 Claude Code 的 system prompt）

这需要大量的工程投入，而且可能会：

• • 延迟 SDK 的发布时间

• • 增加维护成本（两套并行的系统）

• • 牺牲性能（通用抽象总是比专用实现慢）

从技术债务权衡角度，Anthropic 选择了务实的路径：快速推出能工作的产品，接受耦合作为代价。

最后从商业角度看，这种深度耦合创造了一个强大的护城河：

• • 开发者使用 SDK 构建的 Agent 很难迁移到其他模型

• • Claude Code CLI 成为了事实上的 Agent 运行时标准

• • Skills 和配置文件格式形成了一个专属生态

这不一定是恶意的锁定策略，但客观上确实产生了这样的效果。

对开发者的实际影响

最显著的影响是开发者选择受限，如果你想构建生产级的 Agent 应用，你现在面临的选择是：

选项 A：使用 Claude Agent SDK

优点是完整的工具生态和成熟的 agentic loop，而且具有出色的 Agent 性能（针对 Claude 优化）

缺点很明显，必须使用 Claude 模型、必须安装和维护 Claude Code CLI、成本和延迟受限于 Anthropic API

选项 B：使用其他 Agent 框架（LangChain、Vercel AI SDK 等）

优点是模型选择灵活、完全开源和可定制

缺点则是 Agent 性能通常较差，需要自己实现大量基础设施，部分框架缺少类似 Skills 和 Subagents 的高级特性

对于大多数团队来说，选项 A 仍然是最实用的，但必须接受它带来的约束。

成本和延迟的考量

使用 Claude 模型，不得不提的一点是成本和延迟的考量：

• • Claude Haiku 4.5：5 per 1M tokens（输入/输出）- 最快速，适合高频调用

• • Claude Sonnet 4.5：15 per 1M tokens - 平衡性能和成本，最常用

• • Claude Opus 4.5：25 per 1M tokens - 旗舰模型

对于 Agent 应用，由于需要大量的工具调用和中间步骤，实际成本可能是普通对话的 5-10 倍。

具体来说，一个复杂的 Agent 任务可能消耗（以 Claude Sonnet 4.5 为例）：

<code data-language-pending="" data-raw-code="初始上下文: 10K tokens (输入)
10 次工具调用,每次:
  - 工具描述: 2K tokens (输入)
  - 工具结果: 5K tokens (输入)
  - Agent 思考: 1K tokens (输出)
最终响应: 3K tokens (输出)

总计: 
输入: 10K + 10 * (2K + 5K) = 80K tokens = $0.24
输出: 10 * 1K + 3K = 13K tokens = $0.195

单次任务成本: ~$0.44，如果使用 Claude Opus 4.5单次任务成本约为$0.73。" data-show-line-number="true"><span leaf="">  
<section><span leaf="">  
<section><section><span leaf="">1</section><section><span leaf="">2</section><section><span leaf="">3</section><section><span leaf="">4</section><section><span leaf="">5</section><section><span leaf="">6</section><section><span leaf="">7</section><section><span leaf="">8</section><section><span leaf="">9</section><section><span leaf="">10</section><section><span leaf="">11</section><section><span leaf="">12</section></section><span leaf="">  
<section><p><span leaf="">初始上下文: 10K tokens (输入)<span leaf="">  
<span leaf="">10 次工具调用,每次:<span leaf="">  
<span leaf="">  - 工具描述: 2K tokens (输入)<span leaf="">  
<span leaf="">  - 工具结果: 5K tokens (输入)<span leaf="">  
<span leaf="">  - Agent 思考: 1K tokens (输出)<span leaf="">  
<span leaf="">最终响应: 3K tokens (输出)<span leaf="">  
<span leaf=""> <span leaf="">  
<span leaf="">总计: <span leaf="">  
<span leaf="">输入: 10K + 10 * (2K + 5K) = 80K tokens = $0.24<span leaf="">  
<span leaf="">输出: 10 * 1K + 3K = 13K tokens = $0.195<span leaf="">  
<span leaf=""> <span leaf="">  
<span leaf="">单次任务成本: ~$0.44，如果使用 Claude Opus 4.5单次任务成本约为$0.73。</p></section><span leaf="">  
</section><span leaf="">  

假设应用每天处理 1000 个这样的任务：

• • 使用 Sonnet 4.5 的月成本约 $13,200

• • 使用 Opus 4.5 月成本骤升到约 $21,900

对于成本敏感的应用，你可能想使用更便宜的模型。2026 年 1 月的主流模型定价对比：

| 模型

|

定价

|

特点

Claude Haiku 4.5

|

5 per 1M tokens

|

速度最快，成本最低

| |

Claude Sonnet 4.5

|

15 per 1M tokens

|

性能与成本最佳平衡

| |

Claude Opus 4.5

|

25 per 1M tokens

|

最强性能，降价后更具竞争力

| |

GPT-5.2

|

14 per 1M tokens

|

400K 上下文窗口，性价比高

| |

Gemini 3 Pro

|

12 per 1M tokens (≤200K), 18 (>200K)

|

最大上下文窗口（1M-2M）

|

需要注意的是，Agent SDK 主要针对 Claude 优化。虽然理论上可以通过其他框架使用非 Claude 模型，但会失去 SDK 提供的原生集成优势。

部署和运维的复杂性

考虑到部署和运维的复杂性，使用 Claude Agent SDK 的生产环境需要封装成容器，下面给出一个简单例子：

<span leaf="">  
<section><span leaf="">  
<section><section><span leaf="">1</section><section><span leaf="">2</section><section><span leaf="">3</section><section><span leaf="">4</section><section><span leaf="">5</section><section><span leaf="">6</section><section><span leaf="">7</section><section><span leaf="">8</section><section><span leaf="">9</section><section><span leaf="">10</section><section><span leaf="">11</section><section><span leaf="">12</section><section><span leaf="">13</section><section><span leaf="">14</section><section><span leaf="">15</section><section><span leaf="">16</section><section><span leaf="">17</section><section><span leaf="">18</section><section><span leaf="">19</section><section><span leaf="">20</section></section><span leaf="">  
<section><p><span leaf=""># Dockerfile 示例<span leaf="">  
<span leaf="">FROM<span leaf=""> node:<span leaf="">20<span leaf="">  
<span leaf="">  
<span leaf=""># 安装 Claude Code CLI(额外的依赖)<span leaf="">  
<span leaf=""># 注意：截至2026年1月，最新版本是 Claude Code 2.1.1<span leaf="">  
<span leaf=""># 该版本包含109项CLI改进和多语言输出支持<span leaf="">  
<span leaf="">RUN<span leaf=""> npm install -g @anthropic-ai/claude-code@2.1.1<span leaf="">  
<span leaf="">  
<span leaf=""># 安装应用<span leaf="">  
<span leaf="">COPY<span leaf=""> package.json .<span leaf="">  
<span leaf="">RUN<span leaf=""> npm install<span leaf="">  
<span leaf="">  
<span leaf=""># 需要持久化 Claude Code 的配置<span leaf="">  
<span leaf="">VOLUME<span leaf=""> /root/.claude<span leaf="">  
<span leaf="">  
<span leaf=""># 环境变量<span leaf="">  
<span leaf="">ENV<span leaf=""> ANTHROPIC_API_KEY=sk-xxx<span leaf="">  
<span leaf="">ENV<span leaf=""> CLAUDE_CODE_USE_BEDROCK=<span leaf="">1<span leaf="">  # 如果使用 AWS<span leaf="">  
<span leaf="">  
<span leaf="">CMD<span leaf=""> [<span leaf="">"node"<span leaf="">,<span leaf=""> "app.js"<span leaf="">]</p></section><span leaf="">  
</section><span leaf="">  

’ fill=’%23FFFFFF’%3E%3Crect x=‘249’ y=‘126’ width=‘1’ height=‘1’%3E%3C/rect%3E%3C/g%3E%3C/g%3E%3C/svg%3E)

这也比单纯的 API 调用复杂得多：

• • 容器镜像更大（多了 Claude Code CLI）

• • 启动时间更长（需要初始化 Claude Code）

• • 需要管理额外的配置文件和缓存

• • 进程间通信可能成为性能瓶颈

对开源社区的挑战

最后对开源社区也是有相当挑战性，Claude Agent SDK 本身是开源的，但它依赖的 Claude Code CLI 和 Claude 模型不是，这意味着：

• • 可以看到 SDK 的源代码

• • 可以修改和扩展 SDK

• • 但无法替换核心运行时（Claude Code CLI）

• • 也无法使用非 Claude 的模型而不牺牲性能

这种半开源的状态让社区难以真正创新和扩展生态。

应该选择 Claude Agent SDK 吗？

深入了解 Claude Agent SDK 的底层依赖关系后，我对这个设计有了更全面的认识。这是一个有明确权衡的技术选择。

一方面，Claude Agent SDK 深度依赖 Claude Code CLI 和 Claude 模型。这限制了模型选择的灵活性，增加了系统的复杂性，创造了一定程度的生态耦合。

但同时，这种专用化也带来了显著的优势：

• • 经过生产验证的成熟架构

• • 针对 Claude 优化的卓越 Agent 性能

• • 具有丰富的工具和集成生态（MCP、Skills、Subagents）

• • 持续的功能迭代和改进

对于开发者而言，关键是理解这些权衡，并在特定场景下做出明智的决策：

• • 关键业务应用，Agent 质量至关重要 → Claude Agent SDK 是优秀的选择

• • 实验性项目，需要快速迭代 → 考虑更灵活的方案

• • 成本敏感的大规模应用 → 混合架构可能更合适（Haiku 4.5 或 Opus 4.1 用于简单任务，Sonnet/Opus 4.5 处理复杂场景）