第 7 章:工具调用怎么显示
用户不关心函数名,但关心"它到底在干什么、卡在哪、成没成"。工具调用的界面设计,本质是给这三件事找到位置。
学习目标
- 认出流式响应里工具调用的形状,知道参数是"拼"出来的
- 用三态(running / done / failed)驱动界面,而不是靠转圈
- 处理并行工具与参数解析时机
- 知道工具失败该由谁来兜底
7.1 它在流里长什么样
OpenAI 兼容的流式响应里,工具调用不是一个完整对象一次性到达,而是分片追加:
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_1","function":{"name":"parse_pdf"}}]}}]}
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\"fi"}}]}}]}
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"le\":\"a.pdf\"}"}}]}}]}
data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}]}关键点:
| 点 | 说明 |
|---|---|
index | 并行调用时用序号区分,不是数组下标,要按它归并 |
function.name | 通常第一片就完整,但不保证 |
function.arguments | 增量字符串,必须拼完才能 JSON.parse |
finish_reason | 出现 tool_calls 表示模型这轮说完了,等你执行 |
7.2 三态与之间的迁移
ts
type ToolState =
| { phase: "running"; startedAt: number }
| { phase: "done"; endedAt: number; result: unknown }
| { phase: "failed"; endedAt: number; reason: string };7.3 参数拼接:别边拼边解析
ts
const callAcc: Record<number, { name: string; args: string }> = {};
for (const tc of delta.tool_calls ?? []) {
const acc = (callAcc[tc.index] ??= { name: "", args: "" });
if (tc.function?.name) acc.name += tc.function.name;
if (tc.function?.arguments) acc.args += tc.function.arguments;
}
// 收到 finish_reason === "tool_calls" 之后才统一解析
for (const [i, acc] of Object.entries(callAcc)) {
let args: unknown;
try {
args = acc.args ? JSON.parse(acc.args) : {};
} catch {
markFailed(i, "参数不是合法 JSON"); // 罕见但真实存在
continue;
}
runTool(acc.name, args);
}为什么不能边拼边解析:{"fi 不是合法 JSON,{"file":"a 也不是。只有拼完才可能合法。
7.4 并行工具
模型一轮可能同时发多个调用(比如"查库存"和"查价格"):
两条实践:
- 界面上按 index 各自成卡片,不要"合并成一个正在执行的工具";
- 回传顺序按 index,别按完成先后,否则模型对不上号。
7.5 卡片怎么设计
一个够用的工具卡片包含四样:
| 元素 | 作用 |
|---|---|
| 名称 + 图标 | 让用户一眼知道类别(检索/计算/写库) |
| 参数摘要 | 只显示关键字段,别把整坨 JSON 摊开 |
| 状态与耗时 | running 2.4s / done 0.8s |
| 结果 | 默认折叠,展开看详情 |
tsx
<div className="tool-card">
<span className={state.phase}>{iconFor(state.phase)}</span>
<span className="name">{name}</span>
<span className="summary">{summarize(args)}</span>
<span className="elapsed">{elapsed}s</span>
{state.phase !== "running" && <details>…</details>}
</div>summarize 的写法:挑 1–2 个字段,超过 20 字截断。用户要的是"它在干什么",不是参数全貌。
7.6 失败归谁处理
| 失败来源 | 谁兜底 | 界面表现 |
|---|---|---|
| 参数非法 | 前端 | 卡片 failed,说明原因,不重试 |
| 工具执行报错 | 后端 | 结果里带错误,回传给模型 |
| 工具超时 | 前端 + 后端 | 卡片超时态,可手动重试 |
| 模型放弃继续 | 模型 | 回答里说明"这一步没成功" |
原则:前端的失败尽量"回传给模型",而不是直接弹红框。模型看到"工具返回超时",通常会换个做法或解释原因,体验比"出错了"好得多。
7.7 一个反例
见过一个实现:工具一开始执行就把整块回答区域替换成"正在调用工具…",出来再换回文本。结果是:
- 用户看到已生成的文字消失又出现;
- 无法判断工具和文本的顺序关系;
- 停止按钮在此期间无效。
正确做法就是第 6 章的 parts:工具是回答里的一个片段,插在文本之间,不覆盖文本。
本章小结
| 要点 | 说明 |
|---|---|
| 流式形状 | name 与 arguments 都是增量,按 index 归并 |
| 解析时机 | 拼完且 finish_reason=tool_calls 后再 parse |
| 三态 | running / done / failed,禁止永久转圈 |
| 并行 | 各自卡片,回传按 index |
| 卡片 | 名称、参数摘要、耗时、折叠结果 |
| 失败 | 尽量回传模型,别直接弹红框 |
下一章
除了文字和工具,回答里还会有"引用"和"图表"。下一章讲这些富内容怎么放,以及怎么点回原文。