;
};
Structured output lets the agent return typed, machine-readable data instead of plain text. Instead of rendering a single string, you get a structured object you can map to any UI: cards, tables, charts, step-by-step breakdowns, or domain-specific renderers.
## What is structured output?
Instead of returning a free-form text response, the agent uses a tool call to return a structured object conforming to a predefined schema. This gives you:
* **Type-safe data**: parse the response into a known TypeScript type
* **Precise rendering control**: render each field with its own UI treatment
* **Consistent formatting**: every response follows the same structure regardless of the underlying model
The agent accomplishes this by calling a "structured output" tool whose arguments contain the response data. The tool itself doesn't execute any logic and is purely a vehicle for returning typed data.
## Use cases
* **Product comparisons**: feature tables, pros/cons lists, ratings
* **Data analysis**: summaries with metrics, breakdowns, and highlights
* **Step-by-step guides**: ordered instructions with descriptions and code snippets
* **Recipes**: ingredients, steps, timings, and nutritional info
* **Math and science**: formulas rendered with LaTeX, step-by-step derivations
* **Travel planning**: itineraries with dates, locations, and cost estimates
## Define a schema
Define a TypeScript type for the structured data the agent returns. The shape of this schema determines how you render the UI.
Here's an example for a recipe assistant:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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;
}
```
| Field | Type | Description |
| ------------- | -------------- | -------------------------------------------- |
| `title` | `string` | Name of the recipe |
| `description` | `string` | Short summary of the dish |
| `servings` | `number` | Number of servings |
| `ingredients` | `Ingredient[]` | List of ingredients with amounts and units |
| `steps` | `RecipeStep[]` | Ordered preparation steps |
| `totalTime` | `string` | Estimated total preparation and cooking time |
Your schema can be anything. The pattern works the same way regardless of shape.
## Extract structured output from messages
The structured output lives in the `tool_calls` array of the last `AIMessage`. Extract it by finding the AI message and accessing the first tool call's arguments:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { AIMessage } from "@langchain/core/messages";
function extractStructuredOutput(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;
}
```
The structured output tool call may not have `args` populated until the agent finishes streaming. During streaming, `args` may be partially populated or undefined. Always check for completeness before rendering.
## Set up `useStream`
Import your agent and pass `typeof myAgent` as a type parameter to `useStream` for type-safe access to state values:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import type { myAgent } from "./agent";
```
```tsx React theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { useStream } from "@langchain/react";
import { AIMessage } from "@langchain/core/messages";
function RecipeChat() {
const stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "recipe_assistant",
});
const recipe = extractStructuredOutput(stream.messages);
return (
```
```ts Angular theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { Component, computed } from "@angular/core";
import { useStream } from "@langchain/angular";
@Component({
selector: "app-recipe-chat",
template: `
@if (!recipe() && !stream.isLoading()) {
}
@if (stream.isLoading()) {
}
@if (recipe()) {
}
`,
})
export class RecipeChatComponent {
stream = useStream({
apiUrl: "http://localhost:2024",
assistantId: "recipe_assistant",
});
recipe = computed(() =>
extractStructuredOutput(this.stream.messages())
);
handleSubmit(text: string) {
this.stream.submit({
messages: [{ type: "human", content: text }],
});
}
}
```
## Render the structured data
Once you have a typed object, build a component that maps each field to the
appropriate UI element. This is the core of the pattern: turning structured
data into a purpose-built interface.
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function RecipeCard({ recipe }: { recipe: Recipe }) {
return (
{recipe.title}
{recipe.description}
{recipe.servings} servings{recipe.totalTime}
Ingredients
{recipe.ingredients.map((ing, i) => (
{ing.amount} {ing.unit} {ing.name}
))}
Instructions
{recipe.steps.map((step, i) => (
Step {i + 1}
{step.instruction}
{step.duration && (
{step.duration}
)}
))}
);
}
```
The same approach works for any domain. Map each field to the UI element that best represents it:
| Data type | Rendering strategy |
| --------------- | ----------------------------------------- |
| Plain text | Paragraphs, headings, list items |
| Numbers/metrics | Stat cards, progress bars, badges |
| Arrays | Lists, tables, grids |
| Nested objects | Nested cards, accordion sections |
| Markdown | Markdown renderer (e.g. `react-markdown`) |
| LaTeX/math | KaTeX or MathJax |
| Dates/times | Formatted timestamps, relative time |
| URLs | Links, embedded previews |
## Handle partial streaming data
During streaming, the tool call arguments may be incomplete JSON. Guard against this in your extraction logic:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function extractStructuredOutput(
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;
const hasRequired = requiredFields.every(
(field) => args[field] !== undefined
);
if (requiredFields.length > 0 && !hasRequired) return null;
return args as T;
}
```
Use the `requiredFields` parameter to wait until critical fields are populated before rendering:
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const recipe = extractStructuredOutput(stream.messages, [
"title",
"ingredients",
"steps",
]);
```
## Render progressively during streaming
Rather than waiting for the complete structured output, render fields as they arrive. This gives users immediate feedback while the agent is still generating:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
function ProgressiveRecipeCard({ messages }: { messages: any[] }) {
const partial = extractStructuredOutput>(messages);
if (!partial) return null;
return (
);
}
```
Progressive rendering works well when the schema has a natural top-to-bottom
order: title, then description, then details. The agent typically generates
fields in schema order, so the UI fills in naturally.
## Reset and re-submit
To let the user submit a new query after viewing a result, add a button that starts a new thread:
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{recipe && (
)}
```
This clears the current conversation and lets the user begin a fresh interaction.
## Best practices
* **Validate before rendering**: always check that required fields exist before rendering, since streaming may deliver partial data
* **Use a generic extraction function**: parameterize your extraction logic with a type and required fields so it works across different schemas
* **Render progressively**: show fields as they arrive rather than waiting for the complete object, so users see immediate feedback
* **Provide fallback representations**: if a field supports rich rendering (LaTeX, Markdown, charts), also include a plain-text equivalent in your schema as a fallback
* **Keep schemas flat when possible**: deeply nested schemas are harder to render progressively and more likely to break during partial streaming
* **Match UI to data**: choose the rendering strategy that best represents each field type (tables for arrays, cards for nested objects, badges for status fields)
***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/frontend/structured-output.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).