Vercel AI SDK 7：从流式调用库到全周期 AI 代理基础设施
阅读时间: 大约 11 分钟
Vercel AI SDK 7：从流式调用库到全周期 AI 代理基础设施
2026 年中，Vercel 发布了 AI SDK 7。官方称该 SDK 周下载量已超过 1600 万次，是 Vercel 自家开源代理框架 eva 所依赖的同一层 TypeScript SDK。与以往版本聚焦”把模型流式输出接到前端”不同，v7 的主题是”production depth for agent work”——把代理从 demo 推向生产。本文依据 Vercel 官方发布博客，梳理这次升级到底加了什么、哪些仍是实验性边界。
一、背景：为什么 SDK 要”代理化”
早期 AI SDK 解决的是一个很窄的问题：前端如何优雅地消费 ChatGPT 式的流式响应。但随着代理（agent）变长、变自主，开发者遇到的工程问题不再是”怎么流式渲染”，而是：工具调用要不要人审批？进程重启后跑到一半的代理怎么续？不同模型的 reasoning 参数各家叫什么？线上 trace 怎么接？
v7 的判断是：这些横切关注点（审批、持久化、超时、沙箱、观测）不应该由每个应用自己手写一遍，而应下沉到 SDK。官方把新能力归为五个领域：开发代理、运行代理、集成任意代理框架、观测代理、超越文本的代理。
二、开发期：把”模型差异”抹平
- 统一 reasoning 控制：各前沿模型都支持可配置推理强度，但 provider API 叫法不一。v7 在
generateText/streamText上提供统一的reasoning: 'high'选项，一行映射到 provider 原生推理设置，同时保留回退到 provider options 的能力。 - 按工具隔离的上下文（Tool Context）：第三方工具常需要 LLM 不会生成的输入（如 API Key）。v7 为每个工具声明
contextSchema，并通过toolsContext注入；上下文被限制在该工具内，避免第三方工具越权读取它不需要的凭证。 - 运行时上下文（Runtime Context）：在
prepareStep与工具审批函数中可读写的类型化变量，用于跨步骤调整 prompt、选模型，且可带遥测。 - 文件与技能上传 API：
uploadFile让你把 PDF/图片等大文件上传一次，之后传一个轻量引用即可，避免无状态推理中反复重传字节；uploadSkill同理，面向 provider 托管的容器环境。官方明确：uploadFile仅适用于提供文件上传端点的 provider。 - MCP Apps：MCP 服务器可区分”模型可见工具”与”仅 App 工具”，并在沙箱 iframe 里渲染专用 UI，通过 JSON-RPC 桥接工具、资源与展示交互。
- 终端 UI（TUI）：新增
@ai-sdk/tui包，几行代码即可在终端里交互式跑代理、看推理步骤与工具调用。
三、运行期：审批、持久化、超时、沙箱
- 工具审批（Tool Approvals）：支持在
ToolLoopAgent、generateText、streamText上定义审批策略——简单用户审批、可自动批准/拒绝/转人工的审批函数、以及兜底审批函数。高风险场景额外提供 HMAC 签名审批以防伪造，并在继续执行前重新校验输入与策略。 - WorkflowAgent 持久化：新增
@ai-sdk/workflow，让代理执行能跨进程重启、部署、中断和延迟审批而不从头再来。它支持工作流式 streaming、工具、审批、回调，并在工作流步骤边界之间做 provider 模型序列化。 - 多层级超时：v7 提供一等公民超时配置——
totalMs（总预算）、stepMs（每步）、chunkMs（多久没收到 chunk 就中断）、toolMs（工具默认）以及tools.{x}Ms（单个工具）。超时抛TimeoutError，中止原因沿流与 UI 协议传播。 - 沙箱抽象（SandboxSession）：需要跑 shell、读写文件、执行生成代码的代理，本地/CI/生产沙箱常不一致。v7 抽象出可移植的命令执行会话，工具与具体沙箱解耦，官方点名 Vercel Sandbox 为理想环境。
四、集成与观测：一个 API 接所有 harness，一次注册全链路遥测
HarnessAgent（实验性）：v7 引入实验性 harness 抽象，用一个 API 跑已成熟的代理框架——Claude Code、Codex、Pi（官方还列了 Deep Agents、OpenCode）。harness 可配沙箱、自定义指令、技能与工具；会话可停放/恢复，单轮对话甚至可中途打断再续。由于 HarnessAgent 实现了 AI SDK 的 Agent 接口，其 generate/stream 返回值与现有 useChat()、TUI 无缝兼容。
遥测重做：旧版需要在每次调用里挂回调，v7 改为在应用启动时 registerTelemetry 一次即可全局覆盖所有函数。集成 OpenTelemetry（采用最新 GenAI 语义约定），官方列出的观测平台包括 Datadog、Langfuse、Braintrust、Raindrop、Sentry、Laminar、Langsmith。trace 现在记录根生成、每次模型调用、单步、工具执行、embedding、rerank、用量、错误以及选中的运行时/工具上下文。上图即 Langfuse 中一次”对比东京与巴黎天气”代理的实际 trace：根耗时 22.78s、成本 $0.034545，内部嵌套 researchCity 工具与两个城市子代理，每段都标注了耗时、token 数与费用。
此外，v7 新增 node:diagnostics_channel 支持，在 ai:telemetry 频道上发布结构化事件；并提供逐步性能统计（responseTimeMs、outputTokensPerSecond、timeToFirstOutputMs），可回答”首字花了多久、哪个工具最慢”。
五、超越文本：实时语音与视频生成
- Provider 无关的实时会话（实验性）：支持浏览器直连 WebSocket 会话、服务端签发临时 token，已提供 OpenAI、Google、xAI 的实现与一个 React realtime hook，覆盖音频转写与客户端工具调用。AI Gateway 也通过
gateway.experimental_realtime()提供归一化实时会话。 - 视频生成（实验性）：
experimental_generateVideo一行调用出片，provider 实现覆盖 fal、Google AI Studio、Google Vertex、Replicate，示例模型为google/veo-3.1-generate-001，带可配置大小上限与中止的有界下载处理。
六、口径与局限：哪些还是实验性
读官方博客时需要注意几个官方自己标注的边界：
- HarnessAgent、实时支持、视频生成、MCP App 渲染器均为 experimental——API 可能在正式版前变动，不宜直接当稳定契约用。
uploadFile/uploadSkill依赖 provider 能力——只有提供文件/技能上传端点的 provider 才能用，不是所有模型都支持。- “1600 万周下载”是 Vercel 自报数字，反映生态采用度，但不等于生产就绪度；发布博客未提供与 LangChain、LlamaIndex 等同类 SDK 的横向基准对比。
- 沙箱抽象仍需自行接入具体 provider——SDK 只定义接口，真正的隔离强度取决于你接的 Vercel Sandbox 或第三方沙箱。
七、客观分析：优势与谁该关注
优势：把代理生产化的横切能力（审批、持久化、分层超时、统一遥测）一次性下沉，TypeScript 全栈团队迁移成本低；npx @ai-sdk/codemod v7 可自动从 v6 迁移；HarnessAgent 让”用同一套观测/审批逻辑包住 Claude Code、Codex 等第三方框架”成为可能。
局限：实验性功能占比高，稳定面仍集中在文本代理；深度绑定 Vercel 生态（Sandbox、Gateway）时会有隐性偏好；对非 TypeScript 技术栈团队无直接价值。
适合谁：已在 Node.js/TypeScript 上构建 AI 应用、正从 demo 走向生产、需要统一观测与审批的团队；尤其适合想在自家应用里”托管”或”编排”多个第三方编码代理的平台型产品。