Tool Calling 前端怎么接：工具进度、错误回传、权限边界

《AI 前端实战》第 4/8 篇上篇Streaming UI 工程化下篇预告生成式 UIJSON Schema → React第 23 篇解决了「模型会说话而且说的过程体验还行」。第 4 篇进入分水岭模型开始调用工具。前端此时不再只是对话框而要当「调度台」——展示进度、回收错误、守住权限。你将学到Tool Calling 的前端数据流工具进度组件怎么设计失败重试与 Human-in-the-loop权限白名单怎么落地一个双工具 Demo 的结构一、先看数据流前端视角用户输入 → 模型流式输出可能含 tool_call → 前端识别 tool_call展示「运行中」 → 前端/后端执行工具建议后端执行 → tool_result 回灌模型 → 模型继续生成最终回答关键点tool_call 不是最终答案只是中间事件UI 要用parts模型而不是一条纯文本气泡硬拼接工具执行尽量在服务端前端负责状态与确认承接第 3 篇的消息模型type ChatPart | { type: text; text: string } | { type: tool; id: string; name: string; args?: unknown; status: pending | running | done | error | cancelled; output?: string; error?: string; };二、工具进度组件用户要看见「它在干什么」最少展示 4 个信息字段例子工具名searchDocs状态运行中 / 成功 / 失败关键参数q退款规则注意脱敏结果摘要「找到 3 条文档」或错误原因示意function ToolCard({ part }: { part: ExtractChatPart, { type: tool } }) { return ( div classNamerounded-lg border p-3 text-sm div classNamefont-medium工具{part.name}/div div状态{part.status}/div {part.error div classNametext-red-500{part.error}/div} {part.output pre classNamemt-2 overflow-auto{part.output}/pre} /div ); }体验原则运行中可取消若业务允许成功默认折叠详情失败默认展开不要把敏感参数token、手机号明文甩在 UI三、错误回传失败也是给模型的上下文工具失败时前端/网关至少要回传结构化错误{ tool_call_id: call_123, ok: false, error_code: TIMEOUT, error_message: searchDocs timed out after 8s }然后让模型决定换参数重试、换工具、或向用户道歉并给建议。前端侧注意区分「工具失败」和「模型生成失败」同一tool_call_id只更新一个 part避免裂成多条自动重试要有上限并在 UI 显示「第 2/3 次重试」四、权限边界默认不信任模型生产环境建议三级级别例子策略L0 只读自动搜文档、查天气可自动执行L1 低风险写入创建草稿可自动或二次确认L2 高风险删数据、转账、发生产必须人工确认前端确认框示例逻辑async function maybeRunTool(tool: ToolCall) { const level permissionOf(tool.name); if (level L2) { const ok await askUserConfirm(tool); if (!ok) return { ok: false, error_code: USER_DENIED }; } return executeTool(tool); }白名单应来自服务端配置前端只做展示与确认不能只靠前端拦截。五、Human-in-the-loop把人嵌进环里而不是事后救火适合打断确认的时机参数看起来危险批量删除、对外发送模型连续两次工具失败费用敏感操作大额 API 调用UI 上给三个明确动作允许执行修改参数后再执行拒绝并让模型换方案这比「全自动」更慢一点但能上线。六、双工具 Demo结构即可目标用户问「北京天气怎么样并写进笔记草稿」。工具getWeather(city)saveNote(title, content)推荐状态序text(思考/开场) → tool(getWeather, running) → tool(getWeather, done) → text(简述天气) → tool(saveNote, pending_confirm) // L1/L2 → 用户确认 → tool(saveNote, done) → text(最终回复)前端只要保证每个 tool part 可独立更新确认动作绑定到具体tool.id。七、三个高频坑坑 1把 tool 结果直接当最终气泡用户会看到原始 JSON。应回灌模型再生成可读回答或对结果做摘要展示。坑 2前端直接拿着模型参数去打内网接口容易变成 SSRF / 越权。工具执行放 BFF前端只传tool_call_id与用户确认结果。坑 3停止生成后工具还在跑停止要同时abort 模型流 取消进行中的工具请求能取消的才取消 UI 标cancelled。八、和本系列前后篇的关系第 3 篇消息合并与重连给 tool parts 打底第 4 篇Tool Calling UI 与权限第 5 篇生成式 UI——工具不只返回文本还可返回界面描述若你做的是 Agent 产品这一篇是「能不能上线」的门槛之一。小结Tool Calling 前端三件事进度可见用户知道模型在调用什么错误可回传失败成为下一轮上下文而不是白屏权限可阻断高风险必须人确认把对话框升级成调度台你才算跨过 L2 → L3。下篇预告《AI 前端实战》第 5/8 篇生成式 UI 实战用 JSON Schema React 动态渲染 AI 界面。系列导航1 能力地图 · 2 流式 Chat · 3 Streaming 工程化