Consume typed agent data
Applications need reliable fields for downstream code, storage, or API responses.
AI Agents · Const
Structured outputs
Structured output lets a LangChain agent return validated data that conforms to a declared schema instead of free-form text. The result is available in the final state’s structuredResponse field.
How it works
An agent can be configured with a Zod, Standard Schema, or JSON Schema response format. LangChain validates the model's result and places the typed data in the agent state's structuredResponse field; it uses provider-native output when supported and otherwise falls back to tool calling.
Syntax
createAgent({ model, responseFormat: schemaOrStrategy })Parameters
| Name | Type | Description |
|---|---|---|
responseFormat | Zod schema, Standard Schema-compatible schema, JSON Schema object, ToolStrategy, or ProviderStrategy | The schema or response strategy that defines the agent's structured return value. |
Returns
The agent's final state, including the validated structured response in structuredResponse.
Key points
- Structured output gives an agent a predictable data contract rather than an unconstrained prose response.
- The response format supports Zod, Standard Schema-compatible, and JSON Schema definitions.
- Generated structured data is captured and validated before the application receives it.
- Supported models can use provider-native structured output rather than the fallback tool-calling approach.
- Tool calling provides structured output for models without native structured-output support.
Common mistakes
- Unless the model supports native structured output, the default strategy adds a tool call to produce the structured result.
- Read structuredResponse from the final agent state rather than expecting the structured object as the plain text message.
Example: Return a validated structured response
import { createAgent } from "langchain";
import { z } from "zod";
const Contact = z.object({
name: z.string(),
email: z.string().email(),
});
const agent = createAgent({
model: "openai:gpt-4.1-mini",
responseFormat: Contact,
});
const result = await agent.invoke({
messages: [{ role: "user", content: "Contact Ada at ada@example.com" }],
});
console.log(result.structuredResponse);Defines a Zod schema, configures an agent with it as its response format, and reads the validated structured response from the final state.
When to use it
Use provider-native structured output
A provider supports native schema-constrained generation and should be preferred.
Enforce a schema through tool calling
A model lacks native structured-output support but supports tool calling.
Interview questions
QWhat does structured output provide for an agent?
Structured output constrains an agent's result to a declared schema instead of free-form text. The agent validates the generated data and exposes it as structuredResponse in its final state.
Follow-up: How does strategy selection work? If the model supports native structured output, the agent can use a provider strategy; otherwise it uses tool calling.
QWhich schema formats can responseFormat accept?
The responseFormat option accepts a Zod schema, a Standard Schema-compatible schema, or a JSON Schema object. This gives the agent a concrete contract for the returned data.
Follow-up: Why use an explicit strategy wrapper? It lets you choose providerStrategy or toolStrategy instead of relying on automatic selection.
QHow are native and tool-calling strategies related?
The default behavior is tool calling, where an additional tool call constructs the structured result. Models with native structured-output support can use that provider-native strategy instead.
Follow-up: What should an application inspect after invocation? It should read the structuredResponse property from the final state and handle validation or invocation errors appropriately.
Related
createAgentresponseFormattoolStrategyproviderStrategystructuredResponse