Skip to main content

Documentation Index

Fetch the complete documentation index at: https://nvd-54.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

结构化输出让智能体返回类型化的、机器可读的数据而不是纯文本。你得到的不是渲染单个字符串，而是一个可以映射到任何 UI 的结构化对象：卡片、表格、图表、分步详解或领域特定的渲染器。

​
什么是结构化输出？

智能体不是返回自由格式的文本响应，而是使用工具调用返回符合预定义 schema 的结构化对象。这给你带来：
  • 类型安全的数据：将响应解析为已知的 TypeScript 类型
  • 精确的渲染控制：使用各自的 UI 处理方式渲染每个字段
  • 一致的格式：无论底层模型如何，每个响应都遵循相同的结构
智能体通过调用一个”结构化输出”工具来实现这一点，该工具的参数包含响应数据。工具本身不执行任何逻辑，纯粹是返回类型化数据的载体。

​
使用场景

  • 产品比较：功能表、优缺点列表、评分
  • 数据分析：包含指标、分解和亮点的摘要
  • 分步指南：带描述和代码片段的有序说明
  • 食谱：原料、步骤、时间和营养信息
  • 数学和科学：使用 LaTeX 渲染的公式、逐步推导
  • 旅行规划：包含日期、地点和费用估算的行程

​
定义 Schema

为智能体返回的结构化数据定义 TypeScript 类型。此 schema 的形状决定了你如何渲染 UI。 以下是食谱助手的示例： 
interface Ingredient {
  name: string;
  amount: string;
  unit: string;
}

interface RecipeStep {
  instruction: string;
  duration?: string;
}

interface Recipe {
  title: string;
  description: string;
  servings: number;
  ingredients: Ingredient[];
  steps: RecipeStep[];
  totalTime: string;
}
字段类型描述
titlestring食谱名称
descriptionstring菜品简短描述
servingsnumber份数
ingredientsIngredient[]包含数量和单位的原料列表
stepsRecipeStep[]有序的准备步骤
totalTimestring预计总准备和烹饪时间
你的 schema 可以是任何形状。无论形状如何，该模式的工作方式都相同。

​
从消息中提取结构化输出

结构化输出位于最后一个 AIMessage 的 tool_calls 数组中。通过查找 AI 消息并访问第一个工具调用的参数来提取： 
import { AIMessage } from "@langchain/core/messages";

function extractStructuredOutput<T>(messages: any[]): T | null {
  const aiMessages = messages.filter(AIMessage.isInstance);
  if (aiMessages.length === 0) return null;

  const lastAI = aiMessages[aiMessages.length - 1];
  const toolCall = lastAI.tool_calls?.[0];
  if (!toolCall) return null;

  return toolCall.args as T;
}
结构化输出工具调用的 args 可能在智能体完成流式输出之前不会被填充。在流式输出期间，args 可能只部分填充或未定义。在渲染之前始终检查完整性。

​
设置 useStream

导入你的智能体并将 typeof myAgent 作为类型参数传递给 useStream，以获得类型安全的状态值访问： 
import type { myAgent } from "./agent";

import { useStream } from "@langchain/react";
import { AIMessage } from "@langchain/core/messages";

function RecipeChat() {
  const stream = useStream<typeof myAgent>({
    apiUrl: "http://localhost:2024",
    assistantId: "recipe_assistant",
  });

  const recipe = extractStructuredOutput<Recipe>(stream.messages);

  return (
    <div>
      {!recipe && !stream.isLoading && (
        <PromptInput onSubmit={(text) =>
          stream.submit({ messages: [{ type: "human", content: text }] })
        } />
      )}
      {stream.isLoading && <LoadingIndicator />}
      {recipe && <RecipeCard recipe={recipe} />}
    </div>
  );
}

​
渲染结构化数据

一旦你有了类型化的对象，构建一个将每个字段映射到适当 UI 元素的组件。这是该模式的核心：将结构化数据转化为专门构建的界面。 
function RecipeCard({ recipe }: { recipe: Recipe }) {
  return (
    <div className="recipe-card">
      <div className="recipe-header">
        <h3>{recipe.title}</h3>
        <p className="recipe-description">{recipe.description}</p>
        <div className="recipe-meta">
          <span>{recipe.servings} 份</span>
          <span>{recipe.totalTime}</span>
        </div>
      </div>

      <div className="recipe-ingredients">
        <h4>原料</h4>
        <ul>
          {recipe.ingredients.map((ing, i) => (
            <li key={i}>
              <strong>{ing.amount} {ing.unit}</strong> {ing.name}
            </li>
          ))}
        </ul>
      </div>

      <div className="recipe-steps">
        <h4>步骤</h4>
        {recipe.steps.map((step, i) => (
          <div key={i} className="step">
            <div className="step-number">步骤 {i + 1}</div>
            <p className="step-instruction">{step.instruction}</p>
            {step.duration && (
              <span className="step-duration">{step.duration}</span>
            )}
          </div>
        ))}
      </div>
    </div>
  );
}
相同的方法适用于任何领域。将每个字段映射到最能代表它的 UI 元素：
数据类型渲染策略
纯文本段落、标题、列表项
数字/指标统计卡片、进度条、徽章
数组列表、表格、网格
嵌套对象嵌套卡片、手风琴节
MarkdownMarkdown 渲染器（如 react-markdown）
LaTeX/数学KaTeX 或 MathJax
日期/时间格式化时间戳、相对时间
URL链接、嵌入式预览

​
处理部分流式数据

在流式输出期间，工具调用参数可能是不完整的 JSON。在你的提取逻辑中对此进行防护： 
function extractStructuredOutput<T>(
  messages: any[],
  requiredFields: string[] = [],
): T | null {
  const aiMessages = messages.filter(AIMessage.isInstance);
  if (aiMessages.length === 0) return null;

  const lastAI = aiMessages[aiMessages.length - 1];
  const toolCall = lastAI.tool_calls?.[0];
  if (!toolCall?.args) return null;

  const args = toolCall.args as Record<string, unknown>;
  const hasRequired = requiredFields.every(
    (field) => args[field] !== undefined
  );

  if (requiredFields.length > 0 && !hasRequired) return null;
  return args as T;
}
使用 requiredFields 参数等待关键字段填充后再渲染： 
const recipe = extractStructuredOutput<Recipe>(stream.messages, [
  "title",
  "ingredients",
  "steps",
]);

​
流式输出期间渐进式渲染

不要等待完整的结构化输出，而是在字段到达时渲染它们。这在智能体仍在生成时给用户即时反馈： 
function ProgressiveRecipeCard({ messages }: { messages: any[] }) {
  const partial = extractStructuredOutput<Partial<Recipe>>(messages);
  if (!partial) return null;

  return (
    <div className="recipe-card">
      {partial.title && <h3>{partial.title}</h3>}
      {partial.description && <p>{partial.description}</p>}

      {partial.ingredients && partial.ingredients.length > 0 && (
        <div className="recipe-ingredients">
          <h4>原料</h4>
          <ul>
            {partial.ingredients.map((ing, i) => (
              <li key={i}>
                {ing.amount} {ing.unit} {ing.name}
              </li>
            ))}
          </ul>
        </div>
      )}

      {partial.steps && partial.steps.length > 0 && (
        <div className="recipe-steps">
          <h4>步骤</h4>
          {partial.steps.map((step, i) => (
            <div key={i} className="step">
              <div className="step-number">步骤 {i + 1}</div>
              <p>{step.instruction}</p>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}
当 schema 具有自然的从上到下顺序时，渐进式渲染效果很好：标题、然后描述、然后细节。智能体通常按 schema 顺序生成字段，因此 UI 自然填充。

​
重置和重新提交

要让用户在查看结果后提交新查询，添加一个启动新线程的按钮： 
{recipe && (
  <button onClick={() => stream.switchThread(null)}>
    重新开始
  </button>
)}
这会清除当前对话并让用户开始新的交互。

​
最佳实践

  • 渲染前验证：始终在渲染前检查必需字段是否存在，因为流式输出可能传递部分数据
  • 使用通用提取函数：用类型和必需字段参数化你的提取逻辑，使其跨不同 schema 工作
  • 渐进式渲染：在字段到达时显示而不是等待完整对象，让用户看到即时反馈
  • 提供回退表示：如果字段支持富渲染（LaTeX、Markdown、图表），也在 schema 中包含纯文本等价物作为回退
  • 尽可能保持 schema 扁平：深层嵌套的 schema 更难渐进式渲染，更可能在部分流式输出期间出错
  • 匹配 UI 与数据：选择最能代表每种字段类型的渲染策略（数组用表格，嵌套对象用卡片，状态字段用徽章）
将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。
在 GitHub 上编辑此页面 或 提交 issue。