Vercel AI SDK：聊天页里那张“等待确认”的卡片，怎样接上真正的工具

给聊天页接一个模型，很快就能看到文字逐段出现。继续做下去，问题会变得具体：用户问某座城市的天气，系统正在查询还是已经拿到结果？模型想执行一次操作，确认按钮放在哪里？用户点了拒绝，后面的回答该怎么接？Vercel AI SDK 把这些过程拆成可以传递、检查和展示的消息部分，适合正在把聊天原型做成应用的开发者。

它是 TypeScript 工具库，提供模型调用、工具执行和前端消息交互等能力。这里最值得认识的，是一条回复可以同时包含文字、工具输入、执行状态和工具输出。应用因此有机会把过程画清楚，而不用猜模型是不是已经做完。

跟着官方天气示例，看一次调用怎样完成

当前官方工具使用示例安排了三种工具：服务端执行的天气查询、在浏览器中处理的位置获取，以及需要用户回答的确认工具。用户发出问题，模型先决定调用哪项工具，相关调用随消息流到达前端；完成后，结果再进入后续对话。

有个细节值得先读代码：示例中的天气工具从几种天气描述里随机选择，位置工具也使用演示城市。它们用来展示调用顺序，不能拿输出当真实气象数据。这个区分直接影响原型下一步要做什么：消息流已经能接通，真实查询服务仍要自己接入。

猫目编辑依据官方 v7 文档绘制的流程示意，说明需要用户批准的工具路径；拒绝时不执行该工具。这不是现成确认卡界面或运行截图。打开清晰原图。

如果把教学任务换成“帮我查一下杭州周末天气，再决定是否安排户外活动”，合理的工作链需要先取得真实天气数据，再让模型根据数据组织建议。工具调用里出现了杭州，只说明参数已经形成；工具返回结果，才说明这次查询有了可供处理的材料。界面可以把两个时刻分开显示，避免用户把一段像样的回答误认为已完成查询。

消息有状态，界面就能少猜一步

当前文档把工具消息放在 parts 中，并区分输入准备、输出可用、输出错误等状态。开发者可以在输入还未完成时显示准备中，拿到结果后显示结果卡，调用失败时保留具体错误位置。文字仍能逐段展示，工具进度也能有自己的呈现。

这对检查结果很实际。假设应用展示了一张天气卡，正文随后写“建议改在室内”，开发者可以追到卡片对应的工具输出，判断建议是否建立在那次查询上。若输出错误，就应让用户知道查询没成功，而不能只因为文字流结束便显示整个任务完成。

流协议文档列出了工具输入与输出等事件。它解释了前后端怎样交换这类信息，也提醒开发者，单纯把文本片段拼起来只能得到文字。需要工具卡、来源或其他结构化交互时，服务端发送与客户端读取的协议要配套。

“需要确认”可以成为执行前的一步

当前 SDK 支持工具执行审批：服务端工具可以先请求用户批准，收到批准后才执行。这与让模型先输出一句“请确认”有明显差别。前者把用户答复放进实际执行流程；后者如果没有程序约束，仍可能只是一句话。

接线时，当前 v7 示例先在服务端的 toolApproval 中为指定工具配置 user-approval。调用进入 approval-requested 后，界面展示工具输入和批准、拒绝选项；用户的决定经 addToolApprovalResponse 交回消息流程，再由显式发送或配好的自动续轮继续。批准后执行对应工具，拒绝则不执行这次调用。按钮因此改变的是后续执行路径，而不只是屏幕上多出一句答复。

以教学情境里的“导出一份筛选后的客户名单”为例，界面应该让用户看见筛选条件和准备导出的字段，得到确认后再执行导出。输入结构校验能够检查字段形状，账号权限、可导出范围和数据校验仍属于应用自己的业务。SDK 提供连接交互的结构，不会凭空拥有这些规则。

从现有应用的一项能力开始

比较合适的起点，是挑一项已经可调用、结果容易检查的只读能力，把参数、状态和返回值接进聊天界面，再补确认或写入操作。这样能够先回答一个很具体的问题：用户是否看得懂系统刚才做了什么，以及结果来自哪里。

项目仓库当前说明需要 Node.js 22 及以上，代码采用 Apache-2.0；模型服务、网关和部署资源的费用与条款另算。既可采用网关，也可使用相应提供商包直接连接模型。模型与工具支持随提供商而异，旧版文章中的返回方法和消息字段也不宜混用，应沿当前文档选择同一版本。

如果只是需要一个现成聊天工具，它不会替你省掉开发工作；如果已有应用和业务接口，正准备让模型调用它们，这套对状态和消息的整理就有采用价值。先把一个真实工具的完整过程做清楚，比一开始接入许多按钮更容易看出它帮到了哪里。