structured output

28 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Structured output in agents returns data in structured_response key

When using create_agent with structured output, the agent captures, validates, and returns structured data in the 'structured_response' key of the agent's final state. This applies to both Python (structured_response) and JavaScript (structuredResponse).

create_agent response_format parameter types

The response_format parameter in create_agent accepts: ToolStrategy[StructuredResponseT], ProviderStrategy[StructuredResponseT], type[StructuredResponseT], or None. When a schema type is provided directly, LangChain automatically selects ProviderStrategy if the model supports native structured output, otherwise ToolStrategy.

JSON Schema must be wrapped in explicit strategy

JSON Schema dictionaries must be wrapped in an explicit strategy (ProviderStrategy or ToolStrategy) when passed to response_format. They are not automatically detected when passed directly.

Model profile structured_output attribute determines strategy selection

Support for native structured output is read dynamically from the model's profile data if using langchain>=1.1. If data are not available, you can specify manually using a custom profile with 'structured_output: True'. If tools are specified, the model must support simultaneous use of tools and structured output.

ProviderStrategy class definition and parameters

ProviderStrategy is a generic class with two fields: schema (required, type[SchemaT]) defining the structured output format, and strict (optional, bool | None, requires langchain>=1.2) to enable strict schema adherence supported by some providers like OpenAI and xAI. Defaults to None (disabled).

ProviderStrategy schema parameter accepts Pydantic models, dataclasses, TypedDict, and JSON Schema

ProviderStrategy schema parameter supports: Pydantic BaseModel subclasses (returns validated Pydantic instance), Python dataclasses with type annotations (returns dict), TypedDict typed dictionary classes (returns dict), and JSON Schema dictionaries with top-level 'title' and 'description' keys (returns dict).

ProviderStrategy uses provider-native structured output

ProviderStrategy uses provider-native structured output which provides high reliability and strict validation because the model provider enforces the schema. It is automatically used by create_agent when a schema type is passed directly and the model supports native structured output.

ToolStrategy class definition and parameters

ToolStrategy is a generic class with fields: schema (required, type[SchemaT]), tool_message_content (optional string for custom tool message content), and handle_errors (error handling strategy). Schema supports Pydantic models, dataclasses, TypedDict, JSON Schema, and Union types.

ToolStrategy handle_errors parameter options

handle_errors in ToolStrategy controls validation error handling with options: True (catch all errors with default template), str (custom error message for all errors), type[Exception] (catch specific exception type), tuple[type[Exception], ...] (catch multiple exception types), Callable[[Exception], str] (custom function returning error message), or False (no retry, let exceptions propagate). Defaults to True.

ToolStrategy uses tool calling for structured output

ToolStrategy achieves structured output through tool calling by creating an additional tool call. It works with all models that support tool calling (most modern models) and is used as fallback when native structured output is not available.

ToolStrategy tool_message_content customizes conversation history message

The tool_message_content parameter allows customization of the message that appears in the conversation history when structured output is generated. If not provided, defaults to a message showing the structured response data.

ToolStrategy Union types support multiple schema options

ToolStrategy schema parameter supports Union types allowing multiple schema options. The model will choose the most appropriate schema based on context.

Multiple structured outputs error handling

When a model incorrectly calls multiple structured output tools when only one is expected, the agent provides error feedback in a ToolMessage prompting the model to retry with message: 'Error: Model incorrectly returned multiple structured responses (Schema1, Schema2) when only one is expected. Please fix your mistakes.'

Schema validation error handling

When structured output doesn't match the expected schema, the agent provides specific error feedback: 'Error: Failed to parse structured output for tool 'ToolName': <validation_errors>. Please fix your mistakes.' The agent then prompts the model to retry.

Custom error handler function for structured output

A custom error handler function can be passed to handle_errors parameter. It receives an Exception and returns a string error message. Special exception types include StructuredOutputValidationError and MultipleStructuredOutputsError.

Pydantic model example for ProviderStrategy structured output

Example showing ProviderStrategy with Pydantic BaseModel. ContactInfo class with fields 'name' (string), 'email' (string), 'phone' (string) each with descriptions. Returns validated Pydantic instance when invoked.

Dataclass example for ProviderStrategy structured output

Example showing ProviderStrategy with Python dataclass. ContactInfo dataclass with fields 'name', 'email', 'phone'. Returns dict when invoked.

TypedDict example for ProviderStrategy structured output

Example showing ProviderStrategy with TypedDict. ContactInfo TypedDict with fields 'name', 'email', 'phone'. Returns dict when invoked.

JSON Schema example for ProviderStrategy

Example showing JSON Schema dictionary with ProviderStrategy. Must include 'title' (ContactInfo), 'type' (object), 'description', 'properties' with field definitions including type and description, and 'required' array listing required fields.

Pydantic model example for ToolStrategy

Example showing ToolStrategy with Pydantic BaseModel for ProductReview with fields: rating (int|None, 1-5), sentiment (Literal['positive', 'negative']), key_points (list[str]). Returns validated Pydantic instance.

ToolStrategy Union types example

Example showing ToolStrategy with Union[ProductReview, CustomerComplaint]. Model chooses appropriate schema. ProductReview has rating, sentiment, key_points. CustomerComplaint has issue_type, severity, description.

ToolStrategy custom tool_message_content example

Example showing ToolStrategy with MeetingAction schema and custom tool_message_content='Action item captured and added to meeting notes!'. Demonstrates how custom message appears in conversation history instead of default structured response output.

JavaScript createAgent response format types

In JavaScript, responseFormat parameter accepts: ZodSchema<StructuredResponseT> (Zod schema), StandardSchema<StructuredResponseT> (Standard Schema library), Record<string, unknown> (JSON Schema object), or array of these types.

JavaScript toolStrategy and providerStrategy functions

JavaScript provides toolStrategy() and providerStrategy() functions to control structured output behavior. providerStrategy uses native provider support when available. toolStrategy enforces tool calling strategy.

JavaScript ToolStrategyOptions parameters

toolStrategy function accepts options parameter with: toolMessageContent (custom content for tool message when structured output is generated), and handleError (error handling strategy: true, false, or function returning string or Promise<string>).

Tool input schema with Pydantic models

Define complex tool inputs using Pydantic BaseModel classes passed via args_schema parameter to @tool. Use Field with description for each parameter. Pydantic models support type hints like Literal for constrained values and boolean flags.

Tool input schema with JSON Schema

Define tool input schema using JSON Schema objects passed via args_schema parameter to @tool. Specify properties as a dict with type, description, and required fields.

Return object from tool

Return an object (dict) when the tool produces structured data that the model should inspect. The object is serialized and sent back as tool output. The model can read specific fields and reason over them. Like string returns, this does not directly update graph state. Use when downstream reasoning benefits from explicit fields instead of free-form text.

Give your agent this brain