深入学LangChain官方文档(二十一)Agent 能力如何进入 UI——Tool Calling、Reasoning、Structured Output 与审批本篇对应的官方文档Tool calling说明useStream怎样把工具请求、执行结果和错误组装成可渲染的toolCalls。Reasoning tokens说明模型显式返回的 reasoning/text 内容块怎样通过AIMessage.contentBlocks进入前端。Structured output说明结构化参数怎样从 AIMessage 的 tool call 中提取并在流式期间处理部分数据。Human-in-the-Loop说明stream.interrupt、人工 decision 与 resume command 怎样组成审批闭环。本篇讲解范围本篇讲清工具卡、可见 reasoning 内容、结构化业务结果和人工审批怎样进入同一个 Agent UI并建立它们各自的状态与安全边界。浏览器侧工具、Time Travel 和 Generative UI 留给下一篇。企业采购助手收到一个看似普通的请求“为三名新员工购买笔记本优先选择现有库存预算控制在两万元以内。”如果前端只会显示用户消息和助手文本页面最多呈现一句“正在查询”随后给出一段采购建议。用户看不到系统查了哪些库存、预算工具是否成功、建议是否已经形成稳定业务对象也不知道提交订单前是否还需要主管批准。后端 Agent 实际经历了更丰富的过程模型发出库存和预算工具调用两个工具可能并行返回模型可能产生供应商明确提供的 reasoning 类型内容块采购建议以结构化对象出现真正下单前运行暂停并等待人类确认。它们都发生在同一个 thread 中却不是同一种 UI 数据。文本气泡只回答“说了什么”工具卡回答“系统正在做什么”结构化卡片回答“业务结果是什么”审批组件回答“现在谁拥有继续执行权”。四种问题如果挤进同一个 Markdown 字符串状态会被抹平用户也无法采取正确行动。Agent Frontend 的核心工作不是把输出装饰得更漂亮而是把运行时对象变成可理解、可操作、可恢复的产品状态。能力投影还改变了故障定位方式用户不再只看到“没有回复”而能分辨是工具仍在运行、结构化结果尚未完整还是执行权正在等待审批。后续每一类组件都要保留这种可解释状态。一、UI 渲染的是运行协议不是消息类型列表第 20 篇已经建立了threadId、队列、断线恢复和 checkpoint 分支。那些能力保证会话能够持续但“能接回同一条运行”还不等于“能正确解释运行”。当页面重新挂载后它可能同时拿到历史消息、尚未结束的工具调用、一个部分生成的结构化对象以及等待处理的 interrupt。前端需要知道每类数据的来源、生命周期和允许操作。useStream在这里承担的是投影层。它把后端 Agent 的消息、工具调用、中断和运行状态整理为响应式对象组件不用自己重放事件流才能猜出当前状态。但投影并不会替应用完成产品判断同一个running工具是否允许取消、reasoning 内容是否适合当前用户查看、结构化字段是否足够渲染、审批按钮由谁操作仍然属于应用合同。采购场景把同一条运行拆成四个职责稳定的观察面。它们共享 thread 身份和事件顺序但各自回答不同问题因此必须保留独立状态后再组合到时间线stream.messages保存用户请求和助手回复的消息上下文。stream.toolCalls保存库存、预算、供应商查询的调用状态。AIMessage.contentBlocks保存模型实际返回的 text、reasoning 等类型化内容。stream.interrupt保存待审动作以及恢复运行所需的人类决策。这些对象可以在视觉上相邻却不能共享一个状态机。消息已经到达不代表工具已经完成工具完成不代表结构化采购方案已经通过必要字段校验页面显示审批卡也不代表订单已经提交。UI 只有保留这些差异用户看到的“进度”才对应真实运行。二、callId 维持一次工具调用的身份工具卡最常见的错误是把工具名称当作唯一身份。采购 Agent 可能连续两次调用query_inventory分别查询开发机型和设计机型也可能同时调用query_inventory与check_budget。如果组件只按name更新后到的结果会覆盖先到的卡片错误也可能显示在另一次调用下面。LangChain Frontend 将工具调用组装为AssembledToolCall。其中name说明调用哪个工具input/args保存结构化参数output保存成功结果error保存失败信息status则在running、finished、error之间变化。真正串联一次调用的是callId它对应 AIMessage 中 tool call 的id也使后续ToolMessage能回到正确请求。这条关联决定了工具卡应该“原位更新”而不是每来一个事件就新增一张卡。模型刚发出调用时组件显示工具名和必要参数执行成功后同一callId对应的卡片进入finished并展示经过收窄的结果执行失败时它进入error并呈现可定位信息。用户因此看到的是一次动作的生命周期而不是三条互不相干的系统日志。工具卡还要绑定产生它的消息。一条 AIMessage 可以包含多个 tool call整个 thread 又有多条 AIMessage。渲染某条消息时应使用消息里记录的 tool call ID 集合筛选stream.toolCalls避免把后续轮次的库存结果挂到前一轮采购建议下面。三、并行工具不是一个总 loading采购 Agent 为了缩短等待时间可以同时查询库存、预算和员工配置标准。三个调用进入running的时间接近结束顺序却不确定预算接口可能先返回库存服务可能超时配置标准查询仍然成功。若页面只有一个isLoading任一工具结束都可能让整体加载状态提前消失若必须等全部完成才展示用户又会失去已经可用的结果。并行调用需要把技术状态和业务可用性分开。单个工具是否结束、它属于哪次模型决策、它的结果是否足以支撑采购结论是三个不同判断因此状态结构至少分成三层调用层以callId保存每个工具的running、finished或error。消息层说明这些调用属于哪次模型决策避免跨轮次串卡。业务层判断哪些结果是继续生成采购方案的必要条件哪些失败可以降级。例如库存失败时采购建议不能宣称“现货充足”但预算结果仍可显示员工配置标准失败时可以允许用户重新加载该工具而不是把整个 thread 清空。工具卡的局部错误和 Agent run 的整体错误必须分开否则一次可恢复的接口故障会被放大成整段会话失败。页面还需要一个通用 fallback。已知工具可以映射为库存表、预算进度条或供应商卡未知工具至少要显示工具名、经过脱敏的参数、状态和可折叠结果。没有 fallback 时新工具上线会表现成空白区域用户只看到对话突然停住。四、contentBlocks 保留内容类型也保留生成顺序工具状态解决“系统做了什么”contentBlocks解决“模型返回的内容由什么组成”。支持相应能力的模型可以在AIMessage.contentBlocks中返回reasoning和text类型块。前端据此把模型主动提供的 reasoning 内容放进可折叠区域把面向用户的正式回答放进普通消息区域。这里必须守住一个事实边界前端只能渲染实际收到的 reasoning 类型内容块。不是所有模型都返回这种块不是每条 AIMessage 都包含 reasoning也不能把普通文本、日志或应用自己的猜测包装成模型隐藏推理。供应商没有公开的内部计算过程不属于contentBlocks应用也不应声称能够读取。一个消息可能先产生 reasoning再生成一段 text随后继续 reasoning 并补充 text。若产品需要保留这种交错关系就应该按contentBlocks原始顺序渲染先把所有 reasoning 拼起来、再把所有 text 拼起来会改变用户看到的生成时间线。若产品只需要简化视图可以分别聚合但必须明确这是 UI 的展示选择不是消息原始结构。流式期间还要区分“没有 reasoning”和“reasoning 尚未到达”。空 reasoning 块应过滤只有 text 的消息直接显示普通气泡最后一条 AIMessage 且stream.isLoading为真时组件才把对应内容标为正在流式更新。否则历史消息重新挂载后可能一直显示“思考中”。产品体验上reasoning 区域通常应默认折叠并与正式回答使用明显不同的视觉层级。更重要的是隐私和权限模型返回的 reasoning 内容可能包含用户输入、检索片段或中间判断。应用不能因为字段类型叫reasoning就默认向所有角色展示面向终端用户、审核员和内部调试人员的可见范围应分别配置并在服务端先完成必要脱敏。这条边界使 reasoning 组件成为一种条件能力有内容、允许展示且通过脱敏时才出现其余情况回退到普通 text 渲染。UI 不因缺少 reasoning 块而报错也不以此推断模型没有进行内部计算。五、Structured Output 要从“类型断言”走到“运行时完整”采购建议适合表示为稳定业务对象而不是一段需要再次解析的 Markdown。可以定义PurchaseProposal包含候选设备、数量、总价、预算状态和风险提示。前端拿到对象后能直接映射为表格、金额组件和审批摘要也能在提交前做明确校验。LangChain Frontend 的 structured output 示例从相关 AIMessage 的tool_calls[].args读取对象。这里容易产生误解TypeScript 的as PurchaseProposal只在开发期帮助编辑器它不会验证运行时数据。流式过程中args可能只有部分字段甚至暂时为空模型或后端返回的值也可能不满足业务约束。结构化结果的视觉完整和业务可提交不是同一时刻。为了让用户尽早看到进展、又不让半成品进入订单系统UI 需要分别设置渲染门槛与提交门槛渲染门槛决定哪些字段出现后可以展示局部内容。例如候选设备名称到达后先显示骨架卡但总价未到达时不能显示“预算通过”。提交门槛决定对象何时可以参与真实业务动作。数量、单价、总价、币种和预算状态必须完整并通过运行时 schema 校验才能进入审批。渐进渲染并不等于渐进信任。页面可以边接收边展示但不应把半成品对象写入订单系统。对于数组字段还要处理元素尚未完整、索引变化或模型重新生成的情况Reactkey不应只用数组位置最好使用稳定业务标识。结构化结果也不能和普通工具输出混为一谈。工具输出通常说明一次外部调用的结果structured output 则表达 Agent 当前希望交付给产品层的业务对象。两者都可能位于 tool call 相关结构中但职责不同前者帮助解释执行过程后者驱动最终界面和后续业务动作。六、interrupt 把继续执行权交给人采购方案形成后submit_purchase_order会产生真实副作用。即使金额没有超过预算也不应该因为前端已经渲染了结构化卡片就自动提交。Human-in-the-loop 使用 interrupt 在工具执行前暂停运行并把待审动作带到stream.interrupt。标准 interrupt payload 包含actionRequests与reviewConfigs。前者记录工具名、参数和可选说明后者说明每个动作允许approve、reject、edit、respond中哪些决定。UI 不是自行发明按钮而是根据后端策略渲染当前动作允许的选择。主管点击批准后前端通过stream.submit(null, { command: { resume: response } })把 decision 交回同一 thread。后端从 checkpoint 保存的暂停位置继续而不是从采购请求开头重跑。页面刷新、审核入口切换或审核员从管理后台处理都不应破坏这个持久暂停点。审批卡至少要展示将执行的工具与业务动作经过脱敏但足以判断风险的参数允许的 decision当前 thread、待审动作或业务单据的稳定身份提交中、已提交、失败、已过期等状态。缺少稳定身份时用户双击批准或多个审核员同时操作可能产生重复 resume。前端按钮禁用只能减少误操作真正的幂等还需要后端以 interrupt/checkpoint、业务请求 ID 或版本号拒绝重复决策。七、四种 decision 不能只换按钮文案approve、reject、edit、respond都会恢复运行但它们交给 Agent 的语义不同。四种 decision 的状态边界要对比三个结果工具是否执行、参数是否改变以及 Agent 最终收到什么工具结果。四种 decision 的差异最终落在“工具是否执行、参数是否改变、什么内容作为工具结果返回”三个维度。组件必须依据reviewConfigs.allowedDecisions展示可选动作并让文案准确对应后端语义approve表示按原参数继续执行待审动作。reject表示工具不执行并把拒绝原因交给 Agent 决定下一步。对于有副作用的动作应明确要求 Agent 放弃、补充信息或改用安全替代方案。edit表示人类修改工具名或参数后再允许执行。采购场景可以把数量从三台改为两台但修改后的参数仍需重新校验权限、预算和 schema。respond表示人类直接提供“询问用户”类工具所需的结果工具本身不执行。它不等同于拒绝把拒绝写成respond会让模型把消息当成成功工具结果。多动作 interrupt 还要求 decisions 与actionRequests一一对应。库存锁定、创建订单和发送通知如果同时等待审查不能只提交一个总的“同意”。页面可以把它们拆成多张卡逐项选择但最终 resume payload 必须为每个待审动作提供明确 decision。否则后端无法判断遗漏项是默认批准、默认拒绝还是尚未处理。edit的 UI 尤其不能直接把任意 JSON 暴露给用户。每种高风险工具都应有自己的表单、字段类型、校验和说明修改金额、收件地址与邮件正文需要完全不同的控件。通用 JSON 编辑器可以作为内部 fallback但不适合普通业务用户。八、代码把三类交接落到对象采购界面不需要把所有状态塞进一个巨型组件。更稳定的做法是先把useStream返回的对象收窄为几个明确视图模型再让工具卡、采购方案卡和审批卡分别消费。下面的代码只聚焦三条交接工具按callId归属消息结构化对象通过必要字段门槛interrupt decision 通过 resume command 回到后端。import { AIMessage } from langchain; import type { AssembledToolCall, HITLResponse } from langchain; type PurchaseProposal { proposalId: string; items: Array{ sku: string; quantity: number; unitPrice: number }; totalAmount: number; withinBudget: boolean; }; // 作用选出指定 AIMessage 发出的工具调用输入为消息和全部组装调用输出为属于该消息的调用列表。 function selectMessageToolCalls( message: AIMessage, toolCalls: AssembledToolCall[], ) { const ids new Set(message.tool_calls?.map((call) call.id) ?? []); return toolCalls.filter((call) ids.has(call.callId)); } // 作用从最新 AIMessage 中读取完整采购方案输入为消息列表输出为通过必要字段检查的方案或 null。 function extractPurchaseProposal(messages: unknown[]): PurchaseProposal | null { const aiMessages messages.filter(AIMessage.isInstance); const latest aiMessages.at(-1); const args latest?.tool_calls?.[0]?.args as | PartialPurchaseProposal | undefined; if ( !args?.proposalId || !Array.isArray(args.items) || typeof args.totalAmount ! number || typeof args.withinBudget ! boolean ) { return null; } return args as PurchaseProposal; }第一段函数没有按工具名称筛选而是使用消息中的 tool call ID 与callId做连接因而支持同名重复调用和多工具并行。第二段函数没有看到args就立即断言成功而是等待采购方案的必要字段完整。真实项目还应使用 Zod 等运行时 schema 检查数组元素、金额范围和业务约束。审批恢复保持独立因为它改变的是运行控制权而不是普通消息内容type StreamController { submit( values: null, options: { command: { resume: HITLResponse } }, ): Promiseunknown; }; // 作用提交一次人工审批并防止界面重复触发输入为 stream、决策和本地锁状态输出为恢复请求 Promise。 async function resumeApproval( stream: StreamController, response: HITLResponse, submitting: boolean, ) { if (submitting) { throw new Error(审批正在提交请勿重复操作); } return stream.submit(null, { command: { resume: response } }); }本地submitting只负责即时交互保护不能替代服务端幂等。网络超时后前端必须重新读取 thread 状态判断 decision 是否已经生效再决定提示成功、重新提交或显示冲突而不是盲目重试副作用动作。九、生产界面要用状态矩阵验收当工具、内容块、结构化结果和审批同时存在时逐个检查组件并不足以证明界面可靠。更有效的方法是建立状态矩阵横轴是运行对象纵轴是等待、成功、失败、恢复和权限状态。每个格子都回答“用户看到什么、能做什么、下一步由谁负责”。状态矩阵把容易遗漏的组合变成可验收场景。每一个运行对象都要经过等待、成功、失败、恢复与权限检查尤其要覆盖以下会影响真实副作用或用户判断的边界并发与局部失败一个工具失败时其他成功结果仍能展示最终业务结论不会使用缺失证据。部分结构化数据渐进卡片不能提前触发提交必要字段和运行时 schema 未通过时保持只读。reasoning 缺失与权限没有 reasoning 块时正常显示 text存在时按用户角色、隐私和产品策略决定是否展示。过期 interrupt审批卡重新挂载后先核对当前 thread 状态已处理或被替代的动作不能再次 resume。重复操作按钮防抖、本地提交锁和服务端幂等共同工作任何一个都不能单独证明没有重复副作用。错误可恢复性工具重试、重新生成结构化结果和重新加载审批状态属于不同动作不能统一成“刷新页面”。可访问性loading、error、expanded、approved 等状态不仅依赖颜色折叠 reasoning 和审批按钮需要明确标签、键盘操作与 ARIA 状态。敏感信息工具参数、输出、reasoning 内容和审批 payload 在进入浏览器前完成最小化与脱敏前端日志也不能记录完整隐私数据。真正稳定的 Agent UI 会让用户理解当前状态而不是让用户猜系统是否卡住。库存工具运行时用户看见调用对象和等待状态预算结果到达后卡片原位更新采购方案逐步形成时未完成字段不冒充最终结论下单 interrupt 出现后继续执行权明确交给主管decision 提交后页面重新读取 thread 并展示真实结果。总结把 Agent 运行翻译成可操作界面Agent Frontend 不是消息列表外加几个漂亮卡片而是一层运行协议。toolCalls用callId保存工具动作的身份和生命周期contentBlocks保存模型实际返回的内容类型与顺序structured output 把稳定 schema 映射成业务组件但必须面对流式部分数据stream.interrupt则把高风险动作的继续执行权交给人并通过 resume command 回到持久运行。企业采购请求因此形成一条可以复述的链路用户提交需求后库存和预算工具分别进入独立状态机模型显式返回的内容块按类型渲染采购方案经过必要字段与运行时校验进入业务卡下单前 interrupt 暂停 Agent主管针对每个待审动作提交 decision后端从 checkpoint 继续执行前端最终以 thread 的真实状态确认订单结果。这套设计留下一个自然问题如果某些工具本来就应该在浏览器执行用户希望回到旧 checkpoint 重放运行或者 Agent 需要根据结果动态生成整块交互界面固定的工具卡和审批卡还够不够下一篇将进入 Headless Tools、Time Travel 与 Generative UI继续处理前端拥有执行能力、历史状态可回放以及界面结构动态生成时的控制边界。
