Stainless：API 编译器如何成为 Agent 基础设施的核心层
引子：从 Stripe 的 SDK 噩梦说起
在 Stripe 做 API 平台的那些年，Alex Rattray 面临一个看似无解的问题：维护 7 种语言的 SDK 需要一支全职工程师团队，每天盯着 API 变更、手动打开数百个 PR、在 Python 的 snake_case 和 Go 的显式错误处理之间反复横跳。任何一个 API 字段的修改，都可能让某个语言的 SDK 出现类型不匹配。
这不只是 Stripe 的痛点。OpenAI 发布新模型参数，Anthropic 调整响应格式，Cloudflare 增加 Workers AI 端点——每次 API 变更都意味着所有语言的 SDK 都要跟进。
Stainless 的答案很简单，也很极端：把 SDK 生成当成编译问题。不是模板填空，不是字符串拼接，而是像 GCC 编译 C 代码一样——多遍分析、类型推导、目标代码生成。输入的 OpenAPI 规范就是"源码"，输出的 TypeScript/Python/Go/Java/Kotlin/C#/Swift SDK 就是"可执行文件"。
解析 $ref / oneOf / allOf"] B --> C["语义分析
构建完整类型图"] C --> D["端点分组
paths → Service 类"] D --> E["惯用化转换
语言特定规则"] E --> F1[TypeScript SDK] E --> F2[Python SDK] E --> F3[Go SDK] E --> F4[Java SDK]
核心技术：一个真正的编译器，而非模板引擎
理解 Stainless 的关键在于区分"模板生成器"和"编译器"。传统的 OpenAPI Generator 本质上是在模板中做变量替换——拿一个预定义的 Python 模板，把 API 参数填进去。这能工作，但生成的代码机械、不一致，开发者宁可手写 HTTP 请求。
Stainless 的编译器则执行真正的多遍分析：
第一遍：Schema 解析与展开
递归展开所有 $ref 引用，解析 oneOf/anyOf/allOf 组合，构建完整的、无引用的类型依赖图。这一遍的输出是一个"扁平化的"类型系统，每个类型都是自包含的。
第二遍：端点语义分组
不是简单地把每个 path 映射为一个方法，而是按资源语义聚类。比如 Stripe 的 /v1/customers、/v1/customers/:id、/v1/customers/:id/sources 会被归入同一个 CustomerService 类，生成 client.customers.list()、client.customers.retrieve() 等语义化方法。
第三遍：语言惯用化
这是 Stainless 与所有模板生成器的分水岭。每种语言有独立的惯用化规则：
- Python: snake_case 命名，context manager 支持，
auto_paging()生成器模式 - TypeScript: discriminated unions（对 oneOf 的精确建模），Promise-based API，SSE stream → AsyncIterator
- Go: 显式 error return，
context.Context参数，struct tags - Java/Kotlin: Builder 模式，checked exceptions 映射
关键区别：这些规则不是模板中的 if-else，而是编译器的后端 codegen 阶段。每种语言有一个独立的 codegen 模块，将中间表示（IR）翻译为目标代码。
| 能力 | 传统模板生成器 | Stainless 编译器 |
|---|---|---|
| 类型安全 | 部分 — 枚举常映射为 string | 完全 — 枚举→union type，oneOf→discriminated union |
| 分页 | 无抽象 — 用户手动翻页 | autoPaging() 懒加载迭代器 |
| 流式处理 | 原始 HTTP 响应体 | SSE → AsyncIterator，自动重连 |
| 错误处理 | 通用 HTTPError + status code | 细粒度类型: NotFoundError, RateLimitError, AuthError |
| 版本管理 | 无 | 语义化版本，自动 changelog，发布到包管理器 |
范式转移：当 API 的主要消费者变成 Agent
如果 Stainless 只是一个高质量的 SDK 生成器，它不会成为"核心基础设施"。真正让它质变的是 2025 年的一个发现：AI Agent 正在取代人类开发者成为 API 的主要消费者。
看看谁在用 Stainless 生成的 SDK：
7 语言输出"] end subgraph "SDK 消费者" OPENAI["OpenAI SDK
全球数千万开发者+Agent"] ANTHROPIC["Anthropic SDK
Claude Code / Cursor / Copilot"] META["Meta SDK
Llama 企业接入"] CF["Cloudflare SDK
Workers AI / R2"] end CORE --> OPENAI CORE --> ANTHROPIC CORE --> META CORE --> CF style CORE fill:#2563eb,stroke:#1d4ed8,color:#fff style OPENAI fill:#10b981,stroke:#059669,color:#fff style ANTHROPIC fill:#10b981,stroke:#059669,color:#fff
当你查看任何一个 AI Agent 的 tool calling 流程——无论是 Claude Code 调用 API、Cursor 执行代码生成、还是 Copilot 与外部服务交互——底层执行的就是 Stainless 生成的 SDK。Stainless 已经成为 Agent ↔ API 通信的事实标准中间层。
SDK Code Mode：Agent 调用 API 的最优范式
2025 年，Anthropic 和 Cloudflare 几乎同时发布了一篇技术文章，核心洞察完全一致：让 Agent 生成代码（而非 JSON），通过 SDK 执行，比传统的 function calling 更高效、更准确。
Stainless 将其形式化为 SDK Code Mode——一个结合了 MCP 协议和 SDK 执行环境的 Agent 交互模式：
为什么 SDK Code Mode 更优？
1. 类型检查前置
传统模式下，Agent 构造的 JSON 参数可能字段名拼错、类型不对。这些错误要等到 API 返回 400 后，Agent 重新推理才能修复——一轮失败 + 一轮修复 = 2x API 调用开销。SDK Code Mode 在代码执行时就捕获类型错误（TypeScript 编译期、Python 运行时），错误不会传递到推理层。
2. 错误信息更精确
原始 API 返回的是 HTTP 429 + JSON body。Agent 需要解析 JSON、理解 retry-after 语义、自行实现退避。SDK 将其转化为 RateLimitError(retry_after=5.0)——Agent 不需要理解 HTTP 细节，直接处理语义化异常。
3. 分页透明化
传统模式下，Agent 需要：读取第一页 → 检查是否有 next_cursor → 构造下一页请求 → 循环。每个循环都是一次额外的推理轮次。SDK 的 for item in client.items.auto_paging() 对 Agent 是完全透明的——Agent 只需要写一个循环，SDK 在幕后处理所有分页逻辑。
4. Token 经济性
一段 Python 代码比等价的 JSON schema + 参数值紧凑得多。在上下文窗口是稀缺资源的 Agent 场景中，代码的"信息密度"远高于 JSON。
基准测试
| 指标 | 传统 MCP / 原始 HTTP | SDK Code Mode |
|---|---|---|
| 任务完成率 | 基线 | 显著更高 |
| 请求轮次 | 基线 | 更少 30-50% |
| Token 消耗 | 基线 | 显著更低 |
| 错误恢复 | Agent 自行处理 | SDK 语义化错误 |
注：基准数据来自 Stainless 使用 Increase banking API + Claude 4.6 Opus 的评估测试。
Agent Experience (AX) 全栈
Stainless 的远见在于，他们不只停留在"生成更好的 SDK"——他们在构建 Agent 时代的 API 消费全栈：
API 定义源"] SDK["多语言 SDK
TypeScript/Python/Go/..."] MCP["MCP Server
标准化工具接口"] SKILL["Agent Skills
可复用指令包"] AGENTS["AGENTS.md
Agent 项目上下文"] DOCS["Agent Docs
结构化 API 文档"] SPEC --> SDK SDK --> MCP SDK --> SKILL SDK --> AGENTS SDK --> DOCS style SPEC fill:#7c3aed,stroke:#6d28d9,color:#fff style SDK fill:#2563eb,stroke:#1d4ed8,color:#fff style MCP fill:#10b981,stroke:#059669,color:#fff
- MCP Server: 从 SDK 自动生成。Agent 通过标准化的 MCP 协议调用，而非原始 HTTP
- Agent Skills: 描述如何使用 SDK 完成特定任务的可复用指令包。Agent 加载后直接获得领域知识
- AGENTS.md: 放在 SDK 仓库根目录。当 Coding Agent（Claude Code、Cursor）打开项目时自动加载，告诉 Agent 如何使用这个 SDK
- Agent Docs: 为 Agent 优化的文档——结构化、类型标注、代码示例优先。不是传统的长篇叙述，而是可被 Agent 高效解析的格式
这套栈解决了一个根本问题：每个 API 现在都有了一种标准化的方式与 Agent 通信。Agent 开发者不再需要手动为每个 API 编写 tool definition——SDK + MCP Server + AGENTS.md 已经提供了完整的接口。
在 Agent 基础设施中的价值链定位
将 Stainless 放在完整的 Agent 基础设施栈中，它的位置变得清晰：
对话管理、工具编排、记忆"] end subgraph "API 网关层" GATEWAY["LiteLLM / Portkey / Cloudflare AI GW
统一接入、路由、限流、成本控制"] end subgraph "类型安全通信层 ★ Stainless" SDKs["多语言 SDK 生成"] MCP2["MCP Server 自动生成"] AX["Agent Experience 全栈"] end subgraph "API Provider 层" OAI["OpenAI"] ANTH["Anthropic"] CF2["Cloudflare"] META2["Meta"] end HERMES --> GATEWAY GATEWAY --> SDKs SDKs --> OAI SDKs --> ANTH SDKs --> CF2 SDKs --> META2 MCP2 --> GATEWAY style HERMES fill:#f59e0b,stroke:#d97706,color:#000 style GATEWAY fill:#8b5cf6,stroke:#7c3aed,color:#fff style AX fill:#2563eb,stroke:#1d4ed8,color:#fff
Stainless 位于 API 网关层和 API Provider 层之间——它不替代 LiteLLM 的负载均衡和成本控制，也不替代 Hermes 的 Agent 运行时。它解决的是一个更底层的、此前被忽视的问题：Agent 如何可靠地、类型安全地与任何 API 通信。
这是一个"编译器在通信层"的经典案例。就像 TypeScript 编译器在人类开发者写出错误代码之前捕获类型错误，Stainless 编译器在 Agent 调用 API 之前就确保了类型安全性。Agent 不需要自己处理 HTTP 细节、解析 JSON 错误、实现分页逻辑——SDK 已经封装了这一切。
关键洞察与未来展望
洞察 1：API 的主要消费者正在迁移
2024 年，API 的主要消费者是人类开发者。2026 年，AI Agent 正在成为至少同等重要的消费者。这对 API 设计有深远影响：API 不仅要"对人类友好"（好的文档、直观的命名），还要"对 Agent 友好"（类型安全、确定性行为、结构化响应）。
洞察 2：编译器比运行时更适合 Agent 的错误处理
Agent 的每一次失败重试都是有成本的（API 费用 + 推理时间）。将错误从"运行时推理"移到"编译时检查"是最高杠杆的优化。Stainless 的编译器 + SDK Code Mode 正是利用了这个原则。
洞察 3：Anthropic 收购 Stainless 的战略意义
2026 年初 Anthropic 收购 Stainless，这不仅是人才收购，更是一个强烈的信号：Agent 基础设施公司认识到，API↔Agent 通信的类型安全层是 Agent 生态的核心组件，不是一个可有可无的附加功能。Claude Code + MCP + Stainless SDK 的组合将定义 Agent 调用外部 API 的标准范式。
洞察 4：对 NPU/AI 芯片软件生态的启示
如果你在构建 Ascend NPU 的软件生态，Stainless 模式提供了一个至关重要的参考：提供完整的多语言 SDK（C++/Python/Java/Go）+ MCP Server + AGENTS.md，是让 Agent 能够发现、调用和管理 NPU 算力的关键通路。没有类型安全的 SDK，Agent 只能通过原始 CLI 或 REST 与算力交互——低效且容易出错。
总结
Stainless 表面上是一个 SDK 生成器。实际上，它是一个 AOT 编译器，输入 OpenAPI 规范，输出 7 种语言的类型安全 SDK。但真正让它成为核心基础设施的，是它正在构建的 Agent Experience 全栈——SDK Code Mode、MCP Server 自动生成、Agent Skills、AGENTS.md——这解决了 Agent 生态最根本的碎片化问题：每个 API 如何被 Agent 可靠地消费。
在 Agent 基础设施的版图中，Stainless 占据了一个此前被忽视但至关重要的位置：API 和 Agent 之间的类型安全通信层。