Alpha Notice: These docs cover the v1-alpha release. Content is incomplete and subject to change.For the latest stable version, see the v0 LangChain Python or LangChain JavaScript docs.
Structured output allows agents to return data in a specific, predictable format. Instead of parsing natural language responses, you get typed structured data.LangChain’s prebuilt ReAct agent createAgent handles structured output automatically. The user sets their desired structured output schema, and when the model generates the structured data, it’s captured, validated, and returned in the structuredResponse key of the agent’s state.
Copy
type ResponseFormat = ( | ZodSchema<StructuredResponseT> // a Zod schema | Record<string, unknown> // a JSON Schema)const agent = createAgent({ // ... responseFormat: ResponseFormat | ResponseFormat[]})
Controls how the agent returns structured data. You can provide either a Zod object or JSON schema. By default, the agent uses a tool calling strategy, in which the output is created by an additional tool call. Certain models support native structured output, in which case the agent will use that strategy instead.You can control the behavior by wrapping ResponseFormat in a toolStrategy or providerStrategy function call:
Copy
import { toolStrategy, providerStrategy } from "langchain/agents";const agent = createAgent({ // use a provider strategy if supported by the model responseFormat: providerStrategy(z.object({ ... })) // or enforce a tool strategy responseFormat: toolStrategy(z.object({ ... }))})
The structured response is returned in the structuredResponse key of the agent’s final state.
Some model providers support structured output natively through their APIs (currently only OpenAI and Grok). This is the most reliable method when available.To use this strategy, configure a ProviderStrategy:
Copy
function providerStrategy<StructuredResponseT>( schema: ZodSchema<StructuredResponseT> | JsonSchemaFormat): ProviderStrategy<StructuredResponseT>
The schema defining the structured output format. Supports:
Zod Schema: A zod schema
JSON Schema: A JSON schema object
LangChain automatically uses ProviderStrategy when you pass a schema type directly to createAgent.responseFormat and the model supports native structured output:
Copy
import { z } from "zod";import { createAgent, providerStrategy } from "langchain";const ContactInfo = z.object({ name: z.string().describe("The name of the person"), email: z.string().describe("The email address of the person"), phone: z.string().describe("The phone number of the person"),});const agent = createAgent({ model: "openai:gpt-5", tools: tools, responseFormat: providerStrategy(ContactInfo)});const result = await agent.invoke({ messages: [{"role": "user", "content": "Extract contact info from: John Doe, john@example.com, (555) 123-4567"}]});result.structuredResponse;// { name: "John Doe", email: "john@example.com", phone: "(555) 123-4567" }
Provider-native structured output provides high reliability and strict validation because the model provider enforces the schema. Use it when available.
If the provider natively supports structured output for your model choice, it is functionally equivalent to write responseFormat: contactInfoSchema instead of responseFormat: toolStrategy(contactInfoSchema). In either case, if structured output is not supported, the agent will fall back to a tool calling strategy.
For models that don’t support native structured output, LangChain uses tool calling to achieve the same result. This works with all models that support tool calling, which is most modern models.To use this strategy, configure a ToolStrategy:
Custom content for the tool message returned when structured output is generated.
If not provided, defaults to a message showing the structured response data.
Models can make mistakes when generating structured output via tool calling. LangChain provides intelligent retry mechanisms to handle these errors automatically.
You can customize how errors are handled using the handleErrors parameter:Custom error message:
Copy
const responseFormat = toolStrategy(ProductRating, { handleError: "Please provide a valid rating between 1-5 and include a comment.")// Error message becomes:// { role: "tool", content: "Please provide a valid rating between 1-5 and include a comment." }
Handle specific exceptions only:
Copy
import { ToolInputParsingException } from "@langchain/core/tools";const responseFormat = toolStrategy(ProductRating, { handleError: (error: ToolStrategyError) => { if (error instanceof ToolInputParsingException) { return "Please provide a valid rating between 1-5 and include a comment."; } return error.message; })// Only validation errors get retried with default message:// { role: "tool", content: "Error: Failed to parse structured output for tool 'ProductRating': ...\n Please fix your mistakes." }
Handle multiple exception types:
Copy
const responseFormat = toolStrategy(ProductRating, { handleError: (error: ToolStrategyError) => { if (error instanceof ToolInputParsingException) { return "Please provide a valid rating between 1-5 and include a comment."; } if (error instanceof CustomUserError) { return "This is a custom user error."; } return error.message; })