Method●Since v0.3

with_structured_output

Model wrapper that returns outputs formatted to match the given schema.

with_structured_output(
  self,
  schema: _DictOrPydanticClass | None = None,
  *,
  method: Literal['function_calling', 'json_mode', 'json_schema'] = 'json_schema',
  include_raw: bool = False,
  strict: bool | None = None,
  tools: list | None = None,
  **kwargs: Any = {}
) -> Runnable[LanguageModelInput, _DictOrPydantic]

Behavior changed in langchain-openai 0.3.0

method default changed from "function_calling" to "json_schema".

Behavior changed in langchain-openai 0.3.12

Support for tools added.

Behavior changed in langchain-openai 0.3.21

Pass kwargs through to the model.

Example: schema=Pydantic class, method='json_schema', include_raw=False, strict=True

Note, OpenAI has a number of restrictions on what types of schemas can be provided if strict = True. When using Pydantic, our model cannot specify any Field metadata (like min/max constraints) and fields cannot have default values.

See all constraints.

from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field

class AnswerWithJustification(BaseModel):
    '''An answer to the user question along with justification for the answer.'''

    answer: str
    justification: str | None = Field(
        default=..., description="A justification for the answer."
    )

model = ChatOpenAI(model="...", temperature=0)
structured_model = model.with_structured_output(AnswerWithJustification)

structured_model.invoke(
    "What weighs more a pound of bricks or a pound of feathers"
)

AnswerWithJustification(
    answer="They weigh the same",
    justification="Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.",
)

Example: schema=Pydantic class, method='function_calling', include_raw=False, strict=False

from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field

class AnswerWithJustification(BaseModel):
    '''An answer to the user question along with justification for the answer.'''

    answer: str
    justification: str | None = Field(
        default=..., description="A justification for the answer."
    )

model = ChatOpenAI(model="...", temperature=0)
structured_model = model.with_structured_output(
    AnswerWithJustification, method="function_calling"
)

structured_model.invoke(
    "What weighs more a pound of bricks or a pound of feathers"
)

AnswerWithJustification(
    answer="They weigh the same",
    justification="Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.",
)

Example: schema=Pydantic class, method='json_schema', include_raw=True

from langchain_openai import ChatOpenAI
from pydantic import BaseModel

class AnswerWithJustification(BaseModel):
    '''An answer to the user question along with justification for the answer.'''

    answer: str
    justification: str

model = ChatOpenAI(model="...", temperature=0)
structured_model = model.with_structured_output(
    AnswerWithJustification, include_raw=True
)

structured_model.invoke(
    "What weighs more a pound of bricks or a pound of feathers"
)

{
    "raw": AIMessage(
        content="",
        additional_kwargs={
            "tool_calls": [
                {
                    "id": "call_Ao02pnFYXD6GN1yzc0uXPsvF",
                    "function": {
                        "arguments": '{"answer":"They weigh the same.","justification":"Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ."}',
                        "name": "AnswerWithJustification",
                    },
                    "type": "function",
                }
            ]
        },
    ),
    "parsed": AnswerWithJustification(
        answer="They weigh the same.",
        justification="Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.",
    ),
    "parsing_error": None,
}

Example: schema=TypedDict class, method='json_schema', include_raw=False, strict=False

from typing_extensions import Annotated, TypedDict

from langchain_openai import ChatOpenAI

class AnswerWithJustification(TypedDict):
    '''An answer to the user question along with justification for the answer.'''

    answer: str
    justification: Annotated[
        str | None, None, "A justification for the answer."
    ]

model = ChatOpenAI(model="...", temperature=0)
structured_model = model.with_structured_output(AnswerWithJustification)

structured_model.invoke(
    "What weighs more a pound of bricks or a pound of feathers"
)

{
    "answer": "They weigh the same",
    "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.",
}

Example: schema=OpenAI function schema, method='json_schema', include_raw=False

from langchain_openai import ChatOpenAI

oai_schema = {
    "name": "AnswerWithJustification",
    "description": "An answer to the user question along with justification for the answer.",
    "parameters": {
        "type": "object",
        "properties": {
            "answer": {"type": "string"},
            "justification": {
                "description": "A justification for the answer.",
                "type": "string",
            },
        },
        "required": ["answer"],
    },
}

model = ChatOpenAI(model="...", temperature=0)
structured_model = model.with_structured_output(oai_schema)

structured_model.invoke(
    "What weighs more a pound of bricks or a pound of feathers"
)

{
    "answer": "They weigh the same",
    "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.",
}

Example: schema=Pydantic class, method='json_mode', include_raw=True

from langchain_openai import ChatOpenAI
from pydantic import BaseModel

class AnswerWithJustification(BaseModel):
    answer: str
    justification: str

model = ChatOpenAI(model="...", temperature=0)
structured_model = model.with_structured_output(
    AnswerWithJustification, method="json_mode", include_raw=True
)

structured_model.invoke(
    "Answer the following question. "
    "Make sure to return a JSON blob with keys 'answer' and 'justification'.\\n\\n"
    "What's heavier a pound of bricks or a pound of feathers?"
)

{
    "raw": AIMessage(
        content='{\\n    "answer": "They are both the same weight.",\\n    "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight." \\n}'
    ),
    "parsed": AnswerWithJustification(
        answer="They are both the same weight.",
        justification="Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight.",
    ),
    "parsing_error": None,
}

Example: schema=None, method='json_mode', include_raw=True

structured_model = model.with_structured_output(
    method="json_mode", include_raw=True
)

structured_model.invoke(
    "Answer the following question. "
    "Make sure to return a JSON blob with keys 'answer' and 'justification'.\\n\\n"
    "What's heavier a pound of bricks or a pound of feathers?"
)

{
    "raw": AIMessage(
        content='{\\n    "answer": "They are both the same weight.",\\n    "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight." \\n}'
    ),
    "parsed": {
        "answer": "They are both the same weight.",
        "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight.",
    },
    "parsing_error": None,
}

Parameters

Name	Type	Description
`schema`	`_DictOrPydanticClass \| None`	Default:`None` The output schema. Can be passed in as: an OpenAI function/tool schema, a JSON Schema, a `TypedDict` class, or a Pydantic class. If `schema` is a Pydantic class then the model output will be a Pydantic instance of that class, and the model-generated fields will be validated by the Pydantic class. Otherwise the model output will be a dict and will not be validated. See `langchain_core.utils.function_calling.convert_to_openai_tool` for more on how to properly specify types and descriptions of schema fields when specifying a Pydantic or `TypedDict` class.
`method`	`Literal['function_calling', 'json_mode', 'json_schema']`	Default:`'json_schema'` The method for steering model generation, one of: `'json_schema'`: Uses OpenAI's Structured Output API. See the docs for supported models. `'function_calling'`: Uses OpenAI's tool-calling API (formerly called function calling). `'json_mode'`: Uses OpenAI's JSON mode. Note that if using JSON mode then you must include instructions for formatting the output into the desired schema into the model call. Learn more about the differences between methods.
`include_raw`	`bool`	Default:`False` If `False` then only the parsed structured output is returned. If an error occurs during model output parsing it will be raised. If `True` then both the raw model response (a `BaseMessage`) and the parsed model response will be returned. If an error occurs during output parsing it will be caught and returned as well. The final output is always a `dict` with keys `'raw'`, `'parsed'`, and `'parsing_error'`.
`strict`	`bool \| None`	Default:`None` `True`: Model output is guaranteed to exactly match the schema. The input schema will also be validated according to the supported schemas. `False`: Input schema will not be validated and model output will not be validated. `None`: `strict` argument will not be passed to the model. If schema is specified via `TypedDict` or JSON schema, `strict` is not enabled by default. Pass `strict=True` to enable it. Note `strict` can only be non-null if `method` is `'json_schema'` or `'function_calling'`.
`tools`	`list \| None`	Default:`None` A list of tool-like objects to bind to the chat model. Requires that: `method` is `'json_schema'` (default). `strict=True` `include_raw=True` If a model elects to call a tool, the resulting `AIMessage` in `'raw'` will include tool calls. Example `from langchain.chat_models import init_chat_model from pydantic import BaseModel class ResponseSchema(BaseModel): response: str def get_weather(location: str) -> str: \"\"\"Get weather at a location.\"\"\" pass model = init_chat_model("openai:gpt-4o-mini") structured_model = model.with_structured_output( ResponseSchema, tools=[get_weather], strict=True, include_raw=True, ) structured_model.invoke("What's the weather in Boston?")` `{ "raw": AIMessage(content="", tool_calls=[...], ...), "parsing_error": None, "parsed": None, }`
`kwargs`	`Any`	Default:`{}` Additional keyword args are passed through to the model.

View source on GitHub

with_structured_output( self, schema: _DictOrPydanticClass | None = None, *, method: Literal['function_calling', 'json_mode', 'json_schema'] = 'json_schema', include_raw: bool = False, strict: bool | None = None, tools: list | None = None, **kwargs: Any = {} ) -> Runnable[LanguageModelInput, _DictOrPydantic]

from langchain_openai import ChatOpenAI from pydantic import BaseModel, Field class AnswerWithJustification(BaseModel): '''An answer to the user question along with justification for the answer.''' answer: str justification: str | None = Field( default=..., description="A justification for the answer." ) model = ChatOpenAI(model="...", temperature=0) structured_model = model.with_structured_output(AnswerWithJustification) structured_model.invoke( "What weighs more a pound of bricks or a pound of feathers" )

AnswerWithJustification( answer="They weigh the same", justification="Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.", )

from langchain_openai import ChatOpenAI from pydantic import BaseModel, Field class AnswerWithJustification(BaseModel): '''An answer to the user question along with justification for the answer.''' answer: str justification: str | None = Field( default=..., description="A justification for the answer." ) model = ChatOpenAI(model="...", temperature=0) structured_model = model.with_structured_output( AnswerWithJustification, method="function_calling" ) structured_model.invoke( "What weighs more a pound of bricks or a pound of feathers" )

from langchain_openai import ChatOpenAI from pydantic import BaseModel class AnswerWithJustification(BaseModel): '''An answer to the user question along with justification for the answer.''' answer: str justification: str model = ChatOpenAI(model="...", temperature=0) structured_model = model.with_structured_output( AnswerWithJustification, include_raw=True ) structured_model.invoke( "What weighs more a pound of bricks or a pound of feathers" )

{ "raw": AIMessage( content="", additional_kwargs={ "tool_calls": [ { "id": "call_Ao02pnFYXD6GN1yzc0uXPsvF", "function": { "arguments": '{"answer":"They weigh the same.","justification":"Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ."}', "name": "AnswerWithJustification", }, "type": "function", } ] }, ), "parsed": AnswerWithJustification( answer="They weigh the same.", justification="Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.", ), "parsing_error": None, }

from typing_extensions import Annotated, TypedDict from langchain_openai import ChatOpenAI class AnswerWithJustification(TypedDict): '''An answer to the user question along with justification for the answer.''' answer: str justification: Annotated[ str | None, None, "A justification for the answer." ] model = ChatOpenAI(model="...", temperature=0) structured_model = model.with_structured_output(AnswerWithJustification) structured_model.invoke( "What weighs more a pound of bricks or a pound of feathers" )

{ "answer": "They weigh the same", "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.", }

from langchain_openai import ChatOpenAI oai_schema = { "name": "AnswerWithJustification", "description": "An answer to the user question along with justification for the answer.", "parameters": { "type": "object", "properties": { "answer": {"type": "string"}, "justification": { "description": "A justification for the answer.", "type": "string", }, }, "required": ["answer"], }, } model = ChatOpenAI(model="...", temperature=0) structured_model = model.with_structured_output(oai_schema) structured_model.invoke( "What weighs more a pound of bricks or a pound of feathers" )

from langchain_openai import ChatOpenAI from pydantic import BaseModel class AnswerWithJustification(BaseModel): answer: str justification: str model = ChatOpenAI(model="...", temperature=0) structured_model = model.with_structured_output( AnswerWithJustification, method="json_mode", include_raw=True ) structured_model.invoke( "Answer the following question. " "Make sure to return a JSON blob with keys 'answer' and 'justification'.\\n\\n" "What's heavier a pound of bricks or a pound of feathers?" )

{ "raw": AIMessage( content='{\\n "answer": "They are both the same weight.",\\n "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight." \\n}' ), "parsed": AnswerWithJustification( answer="They are both the same weight.", justification="Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight.", ), "parsing_error": None, }

structured_model = model.with_structured_output( method="json_mode", include_raw=True ) structured_model.invoke( "Answer the following question. " "Make sure to return a JSON blob with keys 'answer' and 'justification'.\\n\\n" "What's heavier a pound of bricks or a pound of feathers?" )

{ "raw": AIMessage( content='{\\n "answer": "They are both the same weight.",\\n "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight." \\n}' ), "parsed": { "answer": "They are both the same weight.", "justification": "Both a pound of bricks and a pound of feathers weigh one pound. The difference lies in the volume and density of the materials, not the weight.", }, "parsing_error": None, }

Parameters

Name	Type	Description
`schema`	`_DictOrPydanticClass \| None`	Default:`None` The output schema. Can be passed in as: an OpenAI function/tool schema, a JSON Schema, a `TypedDict` class, or a Pydantic class. If `schema` is a Pydantic class then the model output will be a Pydantic instance of that class, and the model-generated fields will be validated by the Pydantic class. Otherwise the model output will be a dict and will not be validated. See `langchain_core.utils.function_calling.convert_to_openai_tool` for more on how to properly specify types and descriptions of schema fields when specifying a Pydantic or `TypedDict` class.
`method`	`Literal['function_calling', 'json_mode', 'json_schema']`	Default:`'json_schema'` The method for steering model generation, one of: `'json_schema'`: Uses OpenAI's Structured Output API. See the docs for supported models. `'function_calling'`: Uses OpenAI's tool-calling API (formerly called function calling). `'json_mode'`: Uses OpenAI's JSON mode. Note that if using JSON mode then you must include instructions for formatting the output into the desired schema into the model call. Learn more about the differences between methods.
`include_raw`	`bool`	Default:`False` If `False` then only the parsed structured output is returned. If an error occurs during model output parsing it will be raised. If `True` then both the raw model response (a `BaseMessage`) and the parsed model response will be returned. If an error occurs during output parsing it will be caught and returned as well. The final output is always a `dict` with keys `'raw'`, `'parsed'`, and `'parsing_error'`.
`strict`	`bool \| None`	Default:`None` `True`: Model output is guaranteed to exactly match the schema. The input schema will also be validated according to the supported schemas. `False`: Input schema will not be validated and model output will not be validated. `None`: `strict` argument will not be passed to the model. If schema is specified via `TypedDict` or JSON schema, `strict` is not enabled by default. Pass `strict=True` to enable it. Note `strict` can only be non-null if `method` is `'json_schema'` or `'function_calling'`.
`tools`	`list \| None`	Default:`None` A list of tool-like objects to bind to the chat model. Requires that: `method` is `'json_schema'` (default). `strict=True` `include_raw=True` If a model elects to call a tool, the resulting `AIMessage` in `'raw'` will include tool calls. Example `from langchain.chat_models import init_chat_model from pydantic import BaseModel class ResponseSchema(BaseModel): response: str def get_weather(location: str) -> str: \"\"\"Get weather at a location.\"\"\" pass model = init_chat_model("openai:gpt-4o-mini") structured_model = model.with_structured_output( ResponseSchema, tools=[get_weather], strict=True, include_raw=True, ) structured_model.invoke("What's the weather in Boston?")` `{ "raw": AIMessage(content="", tool_calls=[...], ...), "parsing_error": None, "parsed": None, }`
`kwargs`	`Any`	Default:`{}` Additional keyword args are passed through to the model.

with_structured_output

Parameters

LangChain Assistant

Menu

with_structured_output

Parameters