Vercel 推出 AI SDK 7，增强流式处理和工具编排（3分钟阅读）

# AI SDK 7 现已发布 原文地址：https://vercel.com/blog/ai-sdk-7 AI SDK 是一款周下载量超过 1600 万的 TypeScript SDK，用于构建跨任意模型提供商的 AI 应用、功能、框架和智能体。它也是 Vercel 的开源智能体框架 EVE（https://vercel.com/eve） 所依赖的核心层。AI SDK 7 在五个方面为智能体工作流增添了生产级深度： - **开发智能体**：支持推理控制、工具与运行时上下文、提供商文件与技能上传、MCP 应用以及终端 UI。 - **运行智能体**：支持工具审批、持久化（`WorkflowAgent`）、超时和沙箱支持。 - **集成任意智能体框架**：例如 Codex、Claude Code、Deep Agents、OpenCode 或 Pi。 - **监控智能体**：支持遥测、Node.js 追踪通道、生命周期事件和性能统计。 - **超越文本智能体**：提供与提供商无关的实时语音支持和视频生成。 从 AI SDK 6 升级？运行 `npx @ai-sdk/codemod v7` 即可自动迁移，代码改动极小；或者使用迁移技能：`npx skills add vercel/ai --skill migrate-ai-sdk-v6-to-v7` ## 开发智能体（https://vercel.com/blog/ai-sdk-7#develop-agents） 构建行为良好的智能体需要对模型推理、工具上下文和文件处理进行精细控制。 ### 推理控制（https://vercel.com/blog/ai-sdk-7#reasoning-control） 大多数前沿模型支持可配置的推理，但每个提供商的 API 暴露方式各不相同。AI SDK 7 通过为 `generateText` 和 `streamText` 提供 `reasoning` 选项来标准化这一行为。它会映射到提供商原生的推理设置，让你用一行代码控制推理强度。当然，当需要更详细的提供商特定推理配置时，你仍然可以回退到提供商选项。 ``` import { generateText } from 'ai'; const result = await generateText({ model, prompt, reasoning: 'high', }); ``` 通过单个选项设置推理强度 了解更多信息，请参阅推理文档（https://ai-sdk.dev/docs/ai-sdk-core/reasoning）。 ### 工具上下文（https://vercel.com/blog/ai-sdk-7#tool-context） 工具越来越多地独立于特定智能体或应用进行开发。例如，第三方公司提供的工具使智能体能够使用其 API。因此，工具需要 LLM 不会生成的额外输入，例如 API 密钥或配置设置。AI SDK 7 增加了完全类型化的工具上下文，可以通过模式为每个工具指定。该上下文仅限于该工具，以防止第三方工具访问其不需要的上下文。 ``` const agent = new ToolLoopAgent({ model, tools: { weather: tool({ description, inputSchema, contextSchema: z.object({ apiKey: z.string(), }), execute: async (input, { context: { apiKey } }) => { // ... }, }), }, toolsContext: { weather: { apiKey: process.env.WEATHER_API_KEY! }, }, }); ``` 将 API 密钥范围限定到需要它的工具 了解更多关于工具上下文（https://ai-sdk.dev/docs/ai-sdk-core/runtime-and-tool-context#tool-context）的信息 ### 运行时上下文（https://vercel.com/blog/ai-sdk-7#runtime-context） 对于更复杂的智能体循环，你经常需要一些变量，可以在 `prepareStep` 中访问和修改这些变量，以调整提示、模型选择等。AI SDK 7 引入了类型化的运行时上下文，可在步骤准备和工具审批函数期间使用，并支持可选的遥测。这使得你能够将更多逻辑封装在 `ToolLoopAgent` 中，并共享包含这些内部逻辑的智能体。 ``` const agent = new ToolLoopAgent({ // 设置运行时上下文 runtimeContext: { var1: "something", }, prepareStep: async ({ runtimeContext, steps }) => { // 使用运行时上下文 // 返回更新后的运行时上下文 }, }); ``` 在步骤之间访问和更新类型化变量 了解更多关于运行时上下文（https://ai-sdk.dev/docs/ai-sdk-core/runtime-and-tool-context）的信息。 ### 提供商文件上传（https://vercel.com/blog/ai-sdk-7#provider-file-uploads） 许多智能体工作流需要处理大型输入，例如 PDF、图像、数据集或其他产物。将这些文件内联发送既慢又浪费，尤其是在无状态推理中，它们会被反复发送。AI SDK 7 添加了顶层的 `uploadFile` API，允许你上传文件一次，然后在后续模型调用中传递一个轻量级引用。这避免了重复上传相同字节，使推理更快，并在重复或多步骤运行期间节省带宽。`uploadFile` 可用于任何提供文件上传端点的提供商。该函数返回一个可在不同提供商之间移植的提供商引用对象。 ``` const { providerReference } = await uploadFile({ api: openai.files(), data: readFileSync('./photo.png'), filename: 'photo.png', }); const result = await streamText({ model: openai.responses('gpt-5.5'), messages: [ { role: 'user', content: [ { type: 'text', text: '描述你在图片中看到的内容。' }, { type: 'file', mediaType: 'image', data: providerReference }, ], }, ], }); ``` 上传文件一次，将引用传递给后续模型调用 了解更多关于提供商文件上传（https://ai-sdk.dev/docs/ai-sdk-core/file-uploads）的信息。 ### 提供商技能上传（https://vercel.com/blog/ai-sdk-7#provider-skill-uploads） 将技能内联发送到提供商管理的容器环境每次请求都会遇到与内联发送文件相同的开销问题。AI SDK 7 添加了顶层的 `uploadSkill` API，允许你上传技能一次，然后在后续推理调用中使用它的引用。与 `uploadFile` 类似，该函数返回一个提供商引用对象。 ``` const { providerReference } = await uploadSkill({ api: anthropic.skills(), files: [ { path: 'my-skill/SKILL.md', content: readFileSync('./SKILL.md'), }, ], displayTitle: '我的技能', }); const result = await streamText({ model: anthropic('claude-sonnet-4-6'), tools: { code_execution: anthropic.tools.codeExecution_20260120(), }, prompt: '使用 my-skill 技能完成任务。', providerOptions: { anthropic: { container: { skills: [{ type: 'custom', providerReference }], }, } satisfies AnthropicLanguageModelOptions, }, }); ``` 上传技能一次，跨推理调用引用它 了解更多关于提供商技能上传（https://ai-sdk.dev/docs/ai-sdk-core/skill-uploads）的信息。 ### MCP 应用（https://vercel.com/blog/ai-sdk-7#mcp-apps） MCP 已成为连接智能体与工具和资源的常见方式。但并非每个工具都应对模型可见，某些 MCP 服务器需要在其工具旁暴露专门的 UI。AI SDK 7 增加了对 MCP 应用的支持。MCP 服务器现在可以将模型可见工具与应用专用工具分离、保留应用元数据，并在沙箱化的 iframe 中渲染应用 UI。一个 JSON-RPC 桥接器连接了工具、资源和显示交互。这让你能够构建更丰富的智能体体验：模型可以使用它需要的工具，而用户则可以看到一个应用特定的界面用于审查、配置或交互。 一个在沙箱化 iframe 中渲染仪表盘 UI 的 MCP 应用，与智能体输出并列 一个在沙箱化 iframe 中渲染仪表盘 UI 的 MCP 应用，与智能体输出并列 一个在智能体输出旁边渲染其 UI 的 MCP 应用 ``` import { experimental_MCPAppRenderer as MCPAppRenderer } from '@ai-sdk/react'; import { isToolUIPart } from 'ai'; { messages.map(message => message.parts.map(part => isToolUIPart(part) ? ( <MCPAppRenderer uri={part.customData.appUri} fetchComponent={() => fetch(`/api/mcp-apps?uri=${app.resourceUri}`)} handlers={{ allowedTools: ['refreshDashboard'] }} /> ) : null, ), ); } ``` 在模型输出旁渲染 MCP 应用 UI 立即使用 AI SDK 开始构建你的第一个 MCP 应用（https://ai-sdk.dev/docs/ai-sdk-core/mcp-apps）。 ### 终端 UI（TUI）（https://vercel.com/blog/ai-sdk-7#tui） 在开发智能体时，你需要能够快速测试它们，而无需编写完整的应用。AI SDK 7 增加了一个终端 UI（TUI）包，让你只需几行代码即可运行智能体：TUI 是交互式的，支持推理和工具，并将 markdown 渲染为格式化文本。 一个在终端 UI 中交互式运行的智能体，显示推理步骤和工具调用 一个在终端 UI 中运行的智能体 ``` import { runAgentTUI } from '@ai-sdk/tui'; await runAgentTUI({ agent }); ``` 在终端中运行智能体 了解更多关于创建你自己的终端智能体（https://ai-sdk.dev/docs/ai-sdk-harnesses/terminal-ui）的信息。 ## 运行智能体（https://vercel.com/blog/ai-sdk-7#run-agents） 随着智能体变得更加自主和运行时间更长，对审批、持久化、沙箱化和健壮性的需求也在增加。 ### 工具审批（https://vercel.com/blog/ai-sdk-7#tool-approvals） AI SDK 7 支持智能体级别的工具审批，可以是自动的，也可以包含人工环节，审批类型如下： - 针对特定工具的简单 `user-approval`。 - 针对特定工具的工具审批函数，可以自动批准、自动拒绝或转发给用户审批。 - 通用的兜底工具审批函数。 工具审批定义在 `ToolLoopAgent`、`generateText` 和 `streamText` 上，因为特定工具的使用场景驱动了对审批的需求。 ``` const agent = new ToolLoopAgent({ model, tools: { weather: weatherTool }, toolApproval: { weather: 'user-approval', }, }); ``` 在工具执行前要求用户审批 对于风险较高的工作流，AI SDK 7 引入了可选的 HMAC 签名工具审批，以防止伪造的审批。SDK 还通过重新验证工具输入和策略来强化重放行为，然后再继续执行。了解工具审批的工作方式（https://ai-sdk.dev/docs/agents/tool-approvals）。 ### WorkflowAgent（持久化）（https://vercel.com/blog/ai-sdk-7#workflowagent-(durability)） 当智能体运行跨越多个步骤或等待人工审批时，中途的进程重启或部署意味着从头开始。AI SDK 7 引入了 `@ai-sdk/workflow` 和 `WorkflowAgent`，用于持久化、可恢复的智能体执行，能够承受进程重启、部署、中断和延迟的审批。`WorkflowAgent` 支持基于工作流的流式传输、工具、审批、回调、`prepareCall` 以及跨工作流步骤边界的提供模型序列化。它还支持类型化的运行时上下文以共享智能体状态，以及稳定的遥测。回调现在包含更丰富的执行数据，例如步骤编号、先前结果、持续时间和成功/失败信息。无效的工具调用将被保留而不执行无效的工具，并且工具的 `toModelOutput` 转换可以保留原始输出，用于 UI 和回调。了解如何使用 WorkflowAgent 构建智能体（https://ai-sdk.dev/docs/agents/workflow-agent）。 ### 超时（https://vercel.com/blog/ai-sdk-7#timeouts） 智能体可能以比简单请求更多的方式停滞：提供商可能打开一个流然后停止发送数据块、工具可能卡住、或者多步骤运行可能超出总预算。AI SDK 7 在文本生成和智能体 API 中添加了一流的超时配置，包括总超时、每步超时、每块超时和每工具超时限制。超时中止使用 `TimeoutError`，中止原因会通过流和 UI 协议传播。 ``` const result = await generateText({ model, tools: { weather: weatherTool, slowApi: slowApiTool }, timeout: { totalMs: 60000, // 总共 60 秒 stepMs: 10000, // 每步 10 秒 chunkMs: 2000, // 如果 2 秒内未收到数据块则中止 toolMs: 5000, // 所有工具的默认值 tools: { weatherMs: 3000, // 天气工具 3 秒 slowApiMs: 10000, // 慢速 API 工具 10 秒 }, }, prompt: '旧金山的天气如何？', }); ``` 配置总超时、每步超时和每工具超时限制 了解更多关于超时（https://ai-sdk.dev/docs/ai-sdk-core/settings#timeout）的信息。 ### 沙箱支持（https://vercel.com/blog/ai-sdk-7#sandbox-support） 运行 shell 命令、读写文件或执行生成代码的智能体需要一致的执行环境，但底层沙箱在本地开发、CI 和生产环境之间往往不同。AI SDK 7 添加了一流的 `SandboxSession` 抽象，用于在工具和智能体中执行可移植的命令。工具可以独立于任何特定沙箱进行开发，并且你可以将任何沙箱感知的工具与任何沙箱提供商一起使用。沙箱环境，例如 Vercel 沙箱（https://vercel.com/sandbox），非常适合此目的。 ## 集成任意智能体框架（https://vercel.com/blog/ai-sdk-7#integrate-any-agent-harness） 智能体运行时正在超越单一的应用服务器。团队希望在同一智能体逻辑在编码环境、托管沙箱、本地会话和第三方框架中运行。 ### HarnessAgent（https://vercel.com/blog/ai-sdk-7#harnessagent） AI SDK 7 引入了实验性的框架抽象和 `HarnessAgent`：一个 API 即可运行完全配置的、成熟的智能体框架，例如 Claude Code、Codex 和 Pi。框架可以使用沙箱进行操作、自定义指令、技能和工具进行配置。通过一致的接口运行成熟的框架，独立配置每一个框架，并在不更改集成层的情况下替换一个框架。 在底层，该抽象由一个 v1 适配器规范、桥接支持和用于创建和恢复会话的扩展沙箱会话原语组成。框架会话可以暂停和恢复，甚至单个轮次也可以在中途中断和恢复。`HarnessAgent` 实现了 AI SDK 的 `Agent` 接口，因此其 `generate` 和 `stream` 的返回值与现有的 AI SDK 集成完全兼容，并且 `useChat()` 和新的 TUI 无需任何额外接线即可工作。 ``` const agent = new HarnessAgent({ harness: claudeCode, sandbox: createVercelSandbox({ runtime: 'node24', ports: [4000], }), instructions: '你是一个细心的编码助手。更喜欢小的修改并解释权衡。', skills: [ { name: 'review-github-pr', description: '审查 GitHub 拉取请求。当被要求审查拉取请求时使用。', content: '使用 `readGitHubPullRequest` 工具获取用户要求你审查的相关拉取请求的上下文。' + '如果拉取请求引用了一个 issue，也使用 `readGitHubIssue` 工具获取相关的 issue 上下文。', }, ], tools: { readGitHubIssue, readGitHubPullRequest }, }); ``` 将 Claude Code 配置为具有沙箱和自定义技能的 HarnessAgent 了解更多关于 AI SDK 框架（https://ai-sdk.dev/v7/docs/ai-sdk-harnesses）的信息。 ## 监控智能体（https://vercel.com/blog/ai-sdk-7#observe-agents） 了解你的智能体在生产环境中的行为是具有挑战性的。AI SDK 7 将可观测性作为构建智能体的一流部分。 ### 遥测（https://vercel.com/blog/ai-sdk-7#telemetry） AI SDK 7 围绕一个单一的、可扩展的集成系统重新设计了遥测。不再需要将生命周期回调连接到每个 `generateText` 或 `streamText` 调用，而是在应用启动时注册一次遥测： ``` import { registerTelemetry, generateText } from 'ai'; import { OpenTelemetry } from '@ai-sdk/otel'; registerTelemetry(new OpenTelemetry()); const result = await generateText({ model: "google/gemini-3.5-flash", prompt: '编写一个关于猫的短篇故事。', telemetry: { functionId: `story-agent`, }, }); ``` 在应用启动时注册一次 OpenTelemetry 重新设计包括： - 用于第三方提供商集成的专用遥测接口 - 通过一次注册全局覆盖所有 AI SDK 函数 - 使用最新的 GenAI 语义约定的可选 OpenTelemetry 集成 - Node.js 追踪通道支持 可观测性集成：Datadog、Langfuse、Braintrust、Raindrop、Sentry、Laminar、Langsmith。 追踪现在捕获 AI 操作的完整形态，包括根生成、每次模型调用、各个步骤、工具执行、嵌入、重排序、以