011-6-StructuredOutput

结构化输出很可能并非一次性返回全部json，要求检查字段完备性，支持并鼓励渐进式渲染

符合预定义 schema 的 JSON 对象的各个字段是分步产出并推送，而不是作为一个完整的 JSON 块一次送达。

前端应对：提取函数必须处理 args 可能为 undefined 或部分字段缺失的情况，并通过检查“必需字段”来决定何时开始或更新 UI 渲染。

结构化输出的类型是普通文本吗？不是普通文本，而是直接返回代码对象。 LLM 能同时输出结构化内容 + 文本内容吗？不能在同一时刻同时输出两种类型，但可以在一次对话中先后出现。

当模式有自然的从上到下顺序：标题、描述、细节时，渐进渲染效果很好。代理通常按模式顺序生成字段，因此界面自然填充。

Reset and re-submit 重置并重新提交这就是一个“一键失忆”按钮，让 Agent 忘掉旧话题，开始新对话。

结构化输出 / Structured output 模式的核心是将 Agent 返回的数据从“供人读的文本”提升为“供程序用的类型化对象”，从而实现 UI 的精准渲染。其运作方式并非让模型直接生成对象，而是通过一个特殊的“工具调用”来承载数据：

定义数据契约：开发者预先定义一个 TypeScript 接口（如 Recipe），描述期望的数据结构。
工具作为载体：Agent 通过调用一个专门的“结构化输出工具”，将符合该接口的数据作为工具参数 (tool_calls[0].args) 返回。
提取与渲染：前端从 AIMessage 的 tool_calls 数组中提取出这个类型安全的数据对象，然后将其字段映射到定制的 UI 组件（如卡片、表格、图表）中。

【数据提取】Extract structured output from messages：必须从最后一条 AIMessage 的 tool_calls[0].args 中提取结构化对象。注意：在流式传输过程中，args 可能不完整或为 undefined，渲染前必须校验完整性。
【处理流式】Handle partial streaming data：
- 防止渲染不完整数据：应编写带 requiredFields 参数的提取函数，仅在必要字段就绪后才返回数据，避免UI崩溃。
- 渐进式渲染：为提升体验，不必等待完整对象，可以渲染已到达的字段（如先显示标题，再显示详情），让界面逐步填充。详见原文 Render progressively during streaming 小节。
【UI 映射】Render the structured data：应根据字段的数据类型选择最合适的渲染策略（例如，数组用列表/表格，数字用统计卡片，Markdown/LaTeX 用专门的渲染器）。
【回退与重置】Reset and re-submit：提供“重新开始”按钮，通过调用 stream.switchThread(null) 创建新会话，让用户发起新查询。
【健壮性设计】：
- 提供纯文本回退：若字段支持富文本渲染（如 LaTeX），建议在 Schema 中同时包含纯文本版本作为回退 (fallback)。
- 保持 Schema 扁平：深层嵌套的对象更难进行渐进式渲染，且在流式传输中更容易损坏。

性能相关：文档通过讲解如何处理部分流式数据和渐进式渲染，覆盖了在数据尚不完整时的性能与体验优化。
安全相关：无直接安全内容。
技术细节：已涵盖数据提取方式、流式传输中的数据完整性校验、requiredFields 的使用、渐进式渲染策略，以及如何将不同数据类型映射到 UI 组件。