Structured output in LangChain

Who this is for and what you will build

This article is for developers who want an agent to return data in a fixed shape rather than free text. By the end you will set the output shape with response_format, receive a validated object or dictionary, and know how LangChain chooses between the two strategies.

What structured output is

Structured output lets an agent return data in a predictable format, such as a JSON object, a Pydantic model or a dataclass. The application can use the result directly instead of parsing natural language^[1]. In Python, create_agent handles this automatically. The generated data is captured and validated, then returned under the structured_response key of the agent's final state^[1].

Setting the shape with response_format

The example below defines a contact model and passes it to response_format. When a type is passed directly, LangChain picks a strategy automatically, and the result is read from result["structured_response"]^[1]:

from pydantic import BaseModel, Field
from langchain.agents import create_agent


class ContactInfo(BaseModel):
    """Contact information for a person."""
    name: str = Field(description="The name of the person")
    email: str = Field(description="The email address of the person")
    phone: str = Field(description="The phone number of the person")

agent = create_agent(
    model="gpt-6.1-sol",
    response_format=ContactInfo  # Auto-selects ProviderStrategy
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Extract contact info from: John Doe, john@example.com, (555) 123-4567"}]
})

print(result["structured_response"])
# ContactInfo(name='John Doe', email='john@example.com', phone='(555) 123-4567')

The two strategies

response_format accepts ToolStrategy, ProviderStrategy, a schema type, or None^[1]. The two strategies differ as follows.

• ProviderStrategy uses the provider's native structured output, which is the most reliable method when the provider supports it. Providers that do include OpenAI, xAI (Grok), Gemini and Anthropic (Claude)^[1]. Its schema can be a Pydantic model, which returns a validated instance, a dataclass, a TypedDict, or a JSON Schema dictionary with top-level title and description keys, which returns a dict^[1]. The optional strict parameter enforces strict schema adherence. OpenAI and xAI support it, it defaults to None, and it requires langchain 1.2 or later^[1].
• ToolStrategy uses tool calling. It covers models without native structured output and works with most modern models that support tool calling^[1]. tool_message_content sets custom content for the tool message, and handle_errors defaults to True. That default catches all errors with the standard template. A custom string or callable can replace the message, a type or tuple can limit which exceptions are caught, and False lets exceptions propagate^[1]. The schema can also be a union type, and the model picks the most suitable member for the context^[1].

How the strategy is chosen

When a schema type is passed directly, LangChain uses ProviderStrategy if the model and provider support native structured output, and ToolStrategy otherwise^[1]. A JSON Schema dictionary is not detected automatically, so it must be wrapped explicitly in ProviderStrategy or ToolStrategy^[1].

If the capability data for a model is missing, you can declare it yourself. From langchain 1.1, native support is read from the model's profile data. When that data is absent, a custom profile can set structured_output to true^[1]:

custom_profile = {
    "structured_output": True,
    # ...
}
model = init_chat_model("...", profile=custom_profile)

If tools and structured output are used together, the model must support both^[1]. Dataclass and TypedDict schemas return dictionaries, and only Pydantic models return validated objects^[1].

When the model makes a mistake

With tool calling, the model can get the structured output wrong. For example, it may call several structured output tools at once. The agent then returns the error in a ToolMessage and asks the model to retry^[1].

JavaScript

In JavaScript, createAgent takes a responseFormat argument that accepts a Zod schema, any Standard Schema-compatible schema, or a JSON Schema object. The result is stored under the structuredResponse key of the state^[1]. The JavaScript agent uses tool calling by default and switches to native output when the model supports it. To choose a strategy explicitly, wrap the schema with providerStrategy or toolStrategy, both imported from langchain^[1].

Common problems

• The result is a dictionary rather than a class instance: this is how dataclass and TypedDict schemas behave. Use a Pydantic model when you want a validated object^[1].
• An error when combining tools and structured output: check that the model supports both^[1].
• Structured output outside an agent: this is a model-level feature, covered in the models material^[1].

Next steps

This article covers only use inside create_agent. For handling parsing errors in chains, LangChain's documentation has a dedicated section^[1].

Adapted from the Structured output page of LangChain's open-source documentation^[1], released under the MIT License.