AI SDK v5 到 v6 迁移指南：在 Cloudflare Agents 与 @cloudflare/ai-chat 中平滑升级你的 AI Agent-北京尧图网络

AI SDK v5 到 v6 迁移指南在 Cloudflare Agents 与 cloudflare/ai-chat 中平滑升级你的 AI Agent【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents这篇指南完整覆盖从 AI SDK v5 升级到 v6 时在cloudflare/ai-chat应用中所需要的全部改动从安装命令的版本固定、五个 Breaking Changes 的逐一对照改造到needsApproval、onToolCall等新工具模式的服务端/客户端落地再到一份可直接照做的迁移检查清单。读完你可以把现有 v5 代码库安全升级到 v6同时了解仓库内examples/ai-chat、examples/dynamic-tools等真实示例的 v6 写法避免在迁移途中误装 AI SDK v7。安装先钉住 v6 兼容的大版本迁移的第一步是固定依赖版本确保升级过程不会顺带装上 AI SDK v7npm install ai^6 ai-sdk/react^3 ai-sdk/openai^3ai钉在^6即^6.0.0ai-sdk/react钉在^3即^3.0.0ai-sdk/openai以及其他 provider 包钉在^3即^3.0.0。当前agents与cloudflare/ai-chat的发布版本同时支持 AI SDK v6 与 v7本指南只针对 v6。值得注意的是从仓库源码结构看示例项目已经跑在更新的 major 上——例如 examples/ai-chat/package.json 中依赖为ai: ^7.0.0workers-ai-provider为^4.0.0这佐证了当前 Cloudflare 包与较新 AI SDK 的兼容路径。同时v4 到 v5 的迁移文档明确提示当前 Cloudflare 包不再支持 v5如果应用仍停留在 v4需要先应用 v4→v5 的中间步骤content到parts、parameters到inputSchema、ai/react到ai-sdk/react等再继续本页的 v6 迁移且不得在云包旁边安装 AI SDK v5。Breaking Changes 逐项改造1.convertToModelMessages()变为异步这是最直接的破坏性变更所有调用点都需要加await。// v5 —— 同步调用 const result streamText({ messages: convertToModelMessages(this.messages), model: openai(gpt-4o) }); // v6 —— 需要 await const result streamText({ messages: await convertToModelMessages(this.messages), model: openai(gpt-4o) });从仓库中真实运行在 v6 的示例看这一点已经贯穿始终。examples/ai-chat/src/server.ts 中不仅使用了await convertToModelMessages(...)还展示了它和pruneMessages的组合用法——pruneMessages可以裁剪toolCalls、reasoning等历史内容来节省 token并允许每个工具的toModelOutput在回放历史时压缩持久化结果messages: pruneMessages({ messages: await convertToModelMessages(this.messages, { tools }), toolCalls: before-last-2-messages, reasoning: before-last-message }),注意这里convertToModelMessages还接收了第二个参数{ tools }用于在历史回放时让每个工具自行收缩其输出例如浏览器截图类的大体积结果这是 v6 迁移后值得利用的能力。2.CoreMessage被移除v6 中消息类型体系发生了更名CoreMessage更名为ModelMessageconvertToCoreMessages()更名为convertToModelMessages()。// v5 import { convertToCoreMessages, type CoreMessage } from ai; // v6 import { convertToModelMessages, type ModelMessage } from ai;配合第一项完整的改造形如import { streamText, convertToModelMessages, type ModelMessage } from ai; const messages: ModelMessage[] await convertToModelMessages(this.messages);3. Tool 模式优先采用服务端工具v6 引入needsApproval工具调用前的人机确认与onToolCall回调。对大多数应用推荐把工具定义在服务端使用ai包的tool()配合 Zod 获得完整的类型安全。v5 时代的写法客户端定义工具实验性自动解析// Client defined tools with AITool type useAgentChat({ agent, tools: clientTools, experimental_automaticToolResolution: true, toolsRequiringConfirmation: [askConfirmation] });v6 推荐写法服务端统一定义工具// Server: all tools defined here const tools { getWeather: tool({ description: Get weather, inputSchema: z.object({ city: z.string() }), execute: async ({ city }) fetchWeather(city) }), getLocation: tool({ description: Get user location, inputSchema: z.object({}) // No execute -- client handles via onToolCall }), processPayment: tool({ description: Process payment, inputSchema: z.object({ amount: z.number() }), needsApproval: async ({ amount }) amount 100, execute: async ({ amount }) charge(amount) }) }; // Client: handle tools via callbacks useAgentChat({ agent, onToolCall: async ({ toolCall, addToolOutput }) { if (toolCall.toolName getLocation) { const pos await getPosition(); addToolOutput({ toolCallId: toolCall.toolCallId, output: { lat: pos.coords.latitude, lng: pos.coords.longitude } }); } } });这一模式在仓库的 examples/ai-chat/src/server.ts 中有完整落地getWeather是带execute的服务端工具自动执行getUserTimezone是没有execute的客户端工具由客户端的onToolCall提供结果calculate则展示了needsApproval的条件化用法——当计算涉及绝对值超过 1000 的大数字时才要求用户确认。客户端侧 examples/ai-chat/src/client.tsx 通过useAgentChat的onToolCall回调接收工具调用并用addToolOutput回传结果。动态客户端工具SDK / 平台模式如果你在构建一个 SDK 或平台工具由宿主应用在运行时动态定义那么useAgentChat上的tools选项和服务端的createToolsFromClientSchemas()仍然被完整支持// Server: accept whatever tools the client sends const tools { ...createToolsFromClientSchemas(options.clientTools), ...serverTools }; // Client: register tools dynamically useAgentChat({ agent, tools: dynamicTools, onToolCall: async ({ toolCall, addToolOutput }) { const tool dynamicTools[toolCall.toolName]; if (tool?.execute) { const output await tool.execute(toolCall.input); addToolOutput({ toolCallId: toolCall.toolCallId, output }); } } });仓库中的 examples/dynamic-tools/src/server.ts 就是这一模式的样板服务端不在部署时定义任何工具而是通过createToolsFromClientSchemas(options?.clientTools)动态注册客户端发来的工具 schemaexamples/dynamic-tools/src/client.tsx 侧则用AITool类型描述运行时工具getPageTitle、getCurrentTime、getScreenInfo、getColorScheme等浏览器能力工具通过tools: activeTools把 schema 自动发送给服务端并在onToolCall中执行。客户端工具通过浏览器 API 实现例如document.title、window.innerWidth、navigator相关能力。4.generateObject的mode选项被移除从generateObject调用中删除mode: json之类的选项直接调用即可。5.isToolUIPart与getToolName现在包含动态工具v6 中这两个函数同时检查静态与动态工具 part。需要旧行为时改用isStaticToolUIPart与getStaticToolName。对大多数用户而言无需任何改动——例如 examples/dynamic-tools/src/client.tsx 中渲染工具调用时依然直接使用isToolUIPart(part)与getToolName(part)来统一处理动态工具。已废弃的 API 与替代方案已废弃 API替代方案toolsRequiringConfirmation服务端工具上的needsApprovalexperimental_automaticToolResolutiononToolCall回调addToolResult()addToolOutput()或addToolApprovalResponse()并未废弃AITool、createToolsFromClientSchemas()、extractClientToolSchemas()以及useAgentChat上的tools选项它们仍然支持工具在运行时由宿主应用动态定义的 SDK / 平台场景。关于替代方案的细节仓库文档可以进一步佐证human-in-the-loop.md 详细说明了needsApproval的用法它可以接收一个返回布尔值的异步函数做条件审批如金额大于 100 才审批也可以直接设为true无条件要求确认inputSchema不限于 Zod还可以用 Valibot、标准 JSON Schema 兼容 schema或通过jsonSchema()包装的原始 JSON Schema。客户端配合addToolApprovalResponse({ id, approved: true | false })完成审批工具 part 会经历approval-requested→output-denied/output-available等状态。client-tools-continuation.md 则解释了onToolCall与自动续跑的配合客户端工具无execute默认启用autoContinueAfterToolResult工具结果经CF_AGENT_TOOL_RESULT回传后服务端会自动再次调用onChatMessage()继续同一轮对话用户看到的是一条无缝响应。迁移检查清单依赖包ai升级到^6.0.0ai-sdk/react升级到^3.0.0ai-sdk/openai及其他 provider升级到^3.0.0代码改动给所有convertToModelMessages()调用加上await将CoreMessage替换为ModelMessage将convertToCoreMessages()替换为convertToModelMessages()从generateObject调用中移除mode选项将静态工具定义迁移到服务端使用tool()对大多数应用推荐在useAgentChat中使用onToolCall处理客户端侧工具执行将toolsRequiringConfirmation替换为needsApproval将addToolResult()替换为addToolOutput()或addToolApprovalResponse()验证步骤参照仓库各示例的写法运行npm run typecheck修复剩余类型错误对于旧版本遗留的已存储消息v4/v5 时代的content字符串等格式会在加载时由AIChatAgent的autoTransformMessages()自动转换无需手工迁移详见 v4 到 v5 迁移文档中的Migration utilities一节。延伸阅读Human in the Loop ——needsApproval与addToolApprovalResponse的完整人机确认方案包括审批超时、多审批人、升级提醒等进阶模式Client-Side Tools and Auto-Continuation ——onToolCall与自动续跑的工作机制、autoContinueAfterToolResult开关及与needsApproval的组合Chat Agents ——AIChatAgent与useAgentChat的完整参考examples/ai-chat —— 同时包含服务端工具、客户端工具与needsApproval审批的端到端示例examples/dynamic-tools —— SDK / 平台模式的动态工具注册示例【免费下载链接】agentsBuild and deploy AI Agents on Cloudflare项目地址: https://gitcode.com/GitHub_Trending/agents1/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

AI SDK v5 到 v6 迁移指南：在 Cloudflare Agents 与 @cloudflare/ai-chat 中平滑升级你的 AI Agent

相关推荐

科研论文配色避坑指南：从原理到实操，打造专业级学术图表

Sanity Studio 定时发布（Scheduled Publishing）：从文档编辑器到 Schedules 工具的全栈指南

AR-NAR混合Transformer模型YuE2实战部署指南

更多资讯

gogcli 读取 Google Sheets 数据源表（Connected Sheets Extract）：`gog sheets datasource table read` 实战指南

累亏超9亿、营收增速骤降，加特兰冲刺科创板，能否解决“增长从哪来”难题？

SolidWorks模板配置指南：零件/装配体/工程图模板与自定义属性

1300 张 H200 完胜 10 万张芯片！Periodic Neon 开辟 AI 变强新路径

软件项目文档管理实战：需求、设计、测试、验收四类文档这样写

编码器停产EOL替代实战：选型、参数对标与PLC适配

今日更新

AWS无服务器应用开发指南：从Lambda到SAM的架构与实践

SpringBoot+Vue人事系统实战：解决HR数据断点与事务一致性

MATLAB手写紧束缚模型计算石墨烯能带结构

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？