LangChain Reference home pageLangChain ReferenceLangChain Reference
  • GitHub
  • Main Docs
Deep Agents
LangChain
LangGraph
Integrations
LangSmith
  • Overview
    • Overview
    • Caches
    • Callbacks
    • Documents
    • Document loaders
    • Embeddings
    • Exceptions
    • Language models
    • Serialization
    • Output parsers
    • Prompts
    • Rate limiters
    • Retrievers
    • Runnables
    • Utilities
    • Vector stores
    MCP Adapters
    Standard Tests
    Text Splitters
    ⌘I

    Chat LangChain

    What can I help with?

    Enter to send·Shift+Enter new line

    Menu

    OverviewCachesCallbacksDocumentsDocument loadersEmbeddingsExceptionsLanguage modelsSerializationOutput parsersPromptsRate limitersRetrieversRunnablesUtilitiesVector stores
    MCP Adapters
    Standard Tests
    Text Splitters
    Language
    Theme
    Pythonlangchain-corelanguage_modelschat_models
    Module●Since v1.8

    chat_models

    Chat models for conversational AI.

    Attributes

    Functions

    Classes

    Type Aliases

    Modules

    View source on GitHub
    attribute
    AnyMessage
    attribute
    RunnableMap: RunnableParallel
    attribute
    GATEWAY_METADATA_RESPONSE_KEY: str
    attribute
    LC_ID_PREFIX: str
    function
    beta
    function
    deprecated
    function
    suppress_langchain_deprecation_warning
    function
    get_llm_cache
    function
    achunks_to_events
    function
    amessage_to_events
    function
    chunks_to_events
    function
    message_to_events
    function
    dumpd
    function
    dumps
    function
    convert_to_messages
    function
    is_data_content_block
    function
    message_chunk_to_message
    function
    convert_to_openai_image_block
    function
    merge_chat_generation_chunks
    function
    ensure_config
    function
    run_in_executor
    function
    convert_to_json_schema
    function
    convert_to_openai_tool
    function
    is_basemodel_subclass
    function
    from_env
    function
    generate_from_stream
    function
    agenerate_from_stream
    class
    BaseCache
    class
    AsyncCallbackManager
    class
    AsyncCallbackManagerForLLMRun
    class
    CallbackManager
    class
    CallbackManagerForLLMRun
    class
    BaseLanguageModel
    class
    LangSmithParams
    class
    AsyncChatModelStream
    class
    ChatModelStream
    class
    ModelProfile
    class
    AIMessage
    class
    AIMessageChunk
    class
    BaseMessage
    class
    JsonOutputKeyToolsParser
    class
    JsonOutputToolsParser
    class
    PydanticToolsParser
    class
    ChatGeneration
    class
    ChatGenerationChunk
    class
    ChatResult
    class
    Generation
    class
    LLMResult
    class
    RunInfo
    class
    ChatPromptValue
    class
    PromptValue
    class
    StringPromptValue
    class
    BaseRateLimiter
    class
    RunnableBinding
    class
    RunnablePassthrough
    class
    Runnable
    class
    RunnableConfig
    class
    BaseTool
    class
    BaseChatModel
    class
    SimpleChatModel
    typeAlias
    Callbacks: list[BaseCallbackHandler] | BaseCallbackManager | None
    typeAlias
    LanguageModelInput
    typeAlias
    StreamEvent
    module
    types

    A type representing any defined Message or MessageChunk type.

    Internal tracing/callback system identifier.

    Used for:

    • Tracing. Every LangChain operation (LLM call, chain execution, tool use, etc.) gets a unique run_id (UUID)
    • Enables tracking parent-child relationships between operations

    Decorator to mark a function, a class, or a property as beta.

    When marking a classmethod, a staticmethod, or a property, the @beta decorator should go under @classmethod and @staticmethod (i.e., beta should directly decorate the underlying callable), but over @property.

    When marking a class C intended to be used as a base class in a multiple inheritance hierarchy, C must define an __init__ method (if C instead inherited its __init__ from its own base class, then @beta would mess up __init__ inheritance when installing its own (annotation-emitting) C.__init__).

    Decorator to mark a function, a class, or a property as deprecated.

    When deprecating a classmethod, a staticmethod, or a property, the @deprecated decorator should go under @classmethod and @staticmethod (i.e., deprecated should directly decorate the underlying callable), but over @property.

    When deprecating a class C intended to be used as a base class in a multiple inheritance hierarchy, C must define an __init__ method (if C instead inherited its __init__ from its own base class, then @deprecated would mess up __init__ inheritance when installing its own (deprecation-emitting) C.__init__).

    Parameters are the same as for warn_deprecated, except for stacklevel; obj_type defaults to 'class' if decorating a class, 'attribute' if decorating a property, and 'function' otherwise.

    Suppress LangChain deprecation warnings within the current context.

    Silences warnings emitted through warn_deprecated and @deprecated. It does not modify the global warnings filters, so calling warnings.warn directly with LangChainDeprecationWarning is not suppressed; use warnings.filterwarnings for that.

    Suppression is stored in a context variable, not a process-wide filter. It applies to the current thread or asyncio task, and to tasks or copied contexts created inside the block (e.g. asyncio.create_task, asyncio.to_thread), which keep it even after the block exits. Other threads are unaffected.

    Get the value of the llm_cache global setting.

    Async variant of chunks_to_events.

    Async variant of message_to_events.

    Convert a stream of ChatGenerationChunk to protocol events.

    Blocks are tracked independently by source-side identifier. Providers such as Anthropic can interleave parallel tool-call chunks by index, so each first-seen block gets a content-block-start, deltas keep their stable wire index, and all open blocks are finalized at message end. Source-side identifiers (from the block's index field, which may be int or string) are translated to sequential uint wire indices.

    Replay a finalized message as a synthetic event lifecycle.

    For a message returned whole (from a graph node, checkpoint, or cache), produce the same message-start / per-block / message-finish event stream a live call would produce. Consumers downstream see a uniform event shape regardless of source.

    Text and reasoning blocks emit a single content-block-delta with the full accumulated content, and tool-call chunk blocks a single tool-call-delta with their full args. Already-finalized blocks (tool_call, server_tool_call, image, etc.) skip the delta and rely on the content-block-finish event alone.

    Return a dict representation of an object.

    Return a JSON string representation of an object.

    Convert a sequence of messages to a list of messages.

    Check if the provided content block is a data content block.

    Returns True for both v0 (old-style) and v1 (new-style) multimodal data blocks.

    Convert a message chunk to a Message.

    Convert ImageContentBlock to format expected by OpenAI Chat Completions.

    Merge a list of ChatGenerationChunks into a single ChatGenerationChunk.

    Ensure that a config is a dict with all keys present.

    Run a function in an executor.

    Convert a schema representation to a JSON schema.

    Convert a tool-like object to an OpenAI tool schema.

    OpenAI tool schema reference

    Check if the given class is a subclass of Pydantic BaseModel.

    Check if the given class is a subclass of any of the following:

    • pydantic.BaseModel in Pydantic 2.x
    • pydantic.v1.BaseModel in Pydantic 2.x

    Create a factory method that gets a value from an environment variable.

    Generate from a stream.

    Async generate from a stream.

    Interface for a caching layer for LLMs and Chat models.

    The cache interface consists of the following methods:

    • lookup: Look up a value based on a prompt and llm_string.
    • update: Update the cache based on a prompt and llm_string.
    • clear: Clear the cache.

    In addition, the cache interface provides an async version of each method.

    The default implementation of the async methods is to run the synchronous method in an executor. It's recommended to override the async methods and provide async implementations to avoid unnecessary overhead.

    Async callback manager that handles callbacks from LangChain.

    Async callback manager for LLM run.

    Callback manager for LangChain.

    Callback manager for LLM run.

    Abstract base class for interfacing with language models.

    All language model wrappers inherited from BaseLanguageModel.

    LangSmith parameters for tracing.

    Asynchronous per-message streaming object for a single LLM response.

    Returned by BaseChatModel.astream_events(version="v3"). Content-block events are fed into this object by a background producer task.

    Projections:

    • .text — async iterable of text deltas; awaitable for full text
    • .reasoning — async iterable of reasoning deltas; awaitable
    • .tool_calls — async iterable of ToolCallChunk deltas; awaitable for list[ToolCall]
    • .output — awaitable for assembled AIMessage

    Usage info is available on .output.usage_metadata once the stream has finished.

    Output shape is always v1 content blocks

    The assembled message's content is always a list of v1 protocol blocks, regardless of the model's output_version setting — see ChatModelStream for the full rationale.

    The stream itself is awaitable (msg = await stream) and async-iterable (async for event in stream).

    Synchronous per-message streaming object for a single LLM response.

    Returned by BaseChatModel.stream_events(version="v3"). Content-block protocol events are fed into this object and accumulated into typed projections.

    Projections (always return the same cached object):

    • .text — iterable of str deltas; str() for full text
    • .reasoning — same as .text for reasoning content
    • .tool_calls — iterable of ToolCallChunk deltas; .get() returns list[ToolCall]
    • .output — blocking property, returns assembled AIMessage

    Usage info is available on .output.usage_metadata once the stream has finished.

    Output shape is always v1 content blocks

    .output.content is always a list of v1 protocol blocks (text, reasoning, tool_call, image, …), regardless of the underlying model's output_version setting. That attribute only controls the legacy stream() / astream() / invoke() paths; ChatModelStream is built on the content-block protocol and emits v1 shapes by construction.

    Raw event iteration::

    for event in stream:
        print(event)  # MessagesData dicts
    

    Description of a chat model's capabilities, exposed via model.profile.

    See the model profiles guide for concepts and usage. Data is sourced from models.dev, augmented with additional fields, and generated by the langchain-model-profiles package (via its langchain-profiles CLI).

    Beta feature

    Fields and format are subject to change. This is a total=False TypedDict, so any field may be absent — guard accesses with .get().

    Message from an AI.

    An AIMessage is returned from a chat model as a response to a prompt.

    This message represents the output of the model and consists of both the raw output as returned by the model and standardized fields (e.g., tool calls, usage metadata) added by the LangChain framework.

    Message chunk from an AI (yielded when streaming).

    Base abstract message class.

    Messages are the inputs and outputs of a chat model.

    Examples include HumanMessage, AIMessage, and SystemMessage.

    Parse tools from OpenAI response.

    Parse tools from OpenAI response.

    Parse tools from OpenAI response.

    A single chat generation output.

    A subclass of Generation that represents the response from a chat model that generates chat messages.

    The message attribute is a structured representation of the chat message. Most of the time, the message will be of type AIMessage.

    Users working with chat models will usually access information via either AIMessage (returned from runnable interfaces) or LLMResult (available via callbacks).

    ChatGeneration chunk.

    ChatGeneration chunks can be concatenated with other ChatGeneration chunks.

    Use to represent the result of a chat model call with a single prompt.

    This container is used internally by some implementations of chat model, it will eventually be mapped to a more general LLMResult object, and then projected into an AIMessage object.

    LangChain users working with chat models will usually access information via AIMessage (returned from runnable interfaces) or LLMResult (available via callbacks). Please refer the AIMessage and LLMResult schema documentation for more information.

    A single text generation output.

    Generation represents the response from an "old-fashioned" LLM (string-in, string-out) that generates regular text (not chat messages).

    This model is used internally by chat model and will eventually be mapped to a more general LLMResult object, and then projected into an AIMessage object.

    LangChain users working with chat models will usually access information via AIMessage (returned from runnable interfaces) or LLMResult (available via callbacks). Please refer to AIMessage and LLMResult for more information.

    A container for results of an LLM call.

    Both chat models and LLMs generate an LLMResult object. This object contains the generated outputs and any additional information that the model provider wants to return.

    Information about a run.

    This is used to keep track of the metadata associated with a run.

    Chat prompt value.

    A type of a prompt value that is built from messages.

    Base abstract class for inputs to any language model.

    PromptValues can be converted to both LLM (pure text-generation) inputs and chat model inputs.

    String prompt value.

    Base class for rate limiters.

    Usage of the base limiter is through the acquire and aacquire methods depending on whether running in a sync or async context.

    Implementations are free to add a timeout parameter to their initialize method to allow users to specify a timeout for acquiring the necessary tokens when using a blocking call.

    Current limitations:

    • Rate limiting information is not surfaced in tracing or callbacks. This means that the total time it takes to invoke a chat model will encompass both the time spent waiting for tokens and the time spent making the request.

    Runnable to passthrough inputs unchanged or with additional keys.

    This Runnable behaves almost like the identity function, except that it can be configured to add additional keys to the output, if the input is a dict.

    The examples below demonstrate this Runnable works using a few simple chains. The chains rely on simple lambdas to make the examples easy to execute and experiment with.

    Base class for all LangChain tools.

    This abstract class defines the interface that all LangChain tools must implement.

    Tools are components that can be called by agents to perform specific actions.

    Base class for chat models.

    Simplified implementation for a chat model to inherit from.

    Note

    This implementation is primarily here for backwards compatibility. For new implementations, please use BaseChatModel directly.

    Input to a language model.

    Wrap a Runnable with additional functionality.

    A RunnableBinding can be thought of as a "runnable decorator" that preserves the essential features of Runnable; i.e., batching, streaming, and async support, while adding additional functionality.

    Any class that inherits from Runnable can be bound to a RunnableBinding. Runnables expose a standard set of methods for creating RunnableBindings or sub-classes of RunnableBindings (e.g., RunnableRetry, RunnableWithFallbacks) that add additional functionality.

    These methods include:

    • bind: Bind kwargs to pass to the underlying Runnable when running it.
    • with_config: Bind config to pass to the underlying Runnable when running it.
    • with_listeners: Bind lifecycle listeners to the underlying Runnable.
    • with_types: Override the input and output types of the underlying Runnable.
    • with_retry: Bind a retry policy to the underlying Runnable.
    • with_fallbacks: Bind a fallback policy to the underlying Runnable.

    Example: bind: Bind kwargs to pass to the underlying Runnable when running it.

    # Create a Runnable binding that invokes the chat model with the
    # additional kwarg `stop=['-']` when running it.
    from langchain_openai import ChatOpenAI
    
    model = ChatOpenAI()
    model.invoke('Say "Parrot-MAGIC"', stop=["-"])  # Should return `Parrot`
    # Using it the easy way via `bind` method which returns a new
    # RunnableBinding
    runnable_binding = model.bind(stop=["-"])
    runnable_binding.invoke('Say "Parrot-MAGIC"')  # Should return `Parrot`

    Can also be done by instantiating a RunnableBinding directly (not recommended):

    from langchain_core.runnables import RunnableBinding
    
    runnable_binding = RunnableBinding(
        bound=model,
        kwargs={"stop": ["-"]},  # <-- Note the additional kwargs
    )
    runnable_binding.invoke('Say "Parrot-MAGIC"')  # Should return `Parrot`

    A unit of work that can be invoked, batched, streamed, transformed and composed.

    Key Methods

    • invoke/ainvoke: Transforms a single input into an output.
    • batch/abatch: Efficiently transforms multiple inputs into outputs.
    • stream/astream: Streams output from a single input as it's produced.
    • astream_log: Streams output and selected intermediate results from an input.

    Built-in optimizations:

    • Batch: By default, batch runs invoke() in parallel using a thread pool executor. Override to optimize batching.

    • Async: Methods with 'a' prefix are asynchronous. By default, they execute the sync counterpart using asyncio's thread pool. Override for native async.

    All methods accept an optional config argument, which can be used to configure execution, add tags and metadata for tracing and debugging etc.

    Runnables expose schematic information about their input, output and config via the input_schema property, the output_schema property and config_schema method.

    Composition

    Runnable objects can be composed together to create chains in a declarative way.

    Any chain constructed this way will automatically have sync, async, batch, and streaming support.

    The main composition primitives are RunnableSequence and RunnableParallel.

    RunnableSequence invokes a series of runnables sequentially, with one Runnable's output serving as the next's input. Construct using the | operator or by passing a list of runnables to RunnableSequence.

    RunnableParallel invokes runnables concurrently, providing the same input to each. Construct it using a dict literal within a sequence or by passing a dict to RunnableParallel.

    For example,

    from langchain_core.runnables import RunnableLambda
    
    # A RunnableSequence constructed using the `|` operator
    sequence = RunnableLambda(lambda x: x + 1) | RunnableLambda(lambda x: x * 2)
    sequence.invoke(1)  # 4
    sequence.batch([1, 2, 3])  # [4, 6, 8]
    
    # A sequence that contains a RunnableParallel constructed using a dict literal
    sequence = RunnableLambda(lambda x: x + 1) | {
        "mul_2": RunnableLambda(lambda x: x * 2),
        "mul_5": RunnableLambda(lambda x: x * 5),
    }
    sequence.invoke(1)  # {'mul_2': 4, 'mul_5': 10}

    Standard Methods

    All Runnables expose additional methods that can be used to modify their behavior (e.g., add a retry policy, add lifecycle listeners, make them configurable, etc.).

    These methods will work on any Runnable, including Runnable chains constructed by composing other Runnables. See the individual methods for details.

    For example,

    from langchain_core.runnables import RunnableLambda
    
    import random
    
    def add_one(x: int) -> int:
        return x + 1
    
    def buggy_double(y: int) -> int:
        """Buggy code that will fail 70% of the time"""
        if random.random() > 0.3:
            print('This code failed, and will probably be retried!')  # noqa: T201
            raise ValueError('Triggered buggy code')
        return y * 2
    
    sequence = (
        RunnableLambda(add_one) |
        RunnableLambda(buggy_double).with_retry( # Retry on failure
            stop_after_attempt=10,
            wait_exponential_jitter=False
        )
    )
    
    print(sequence.input_schema.model_json_schema()) # Show inferred input schema
    print(sequence.output_schema.model_json_schema()) # Show inferred output schema
    print(sequence.invoke(2)) # invoke the sequence (note the retry above!!)

    Debugging and tracing

    As the chains get longer, it can be useful to be able to see intermediate results to debug and trace the chain.

    You can set the global debug flag to True to enable debug output for all chains:

    from langchain_core.globals import set_debug
    
    set_debug(True)

    Alternatively, you can pass existing or custom callbacks to any given chain:

    from langchain_core.tracers import ConsoleCallbackHandler
    
    chain.invoke(..., config={"callbacks": [ConsoleCallbackHandler()]})

    For a UI (and much more) checkout LangSmith.

    Configuration for a Runnable.

    Note

    Custom values

    The TypedDict has total=False set intentionally to:

    • Allow partial configs to be created and merged together via merge_configs
    • Support config propagation from parent to child runnables via var_child_runnable_config (a ContextVar that automatically passes config down the call stack without explicit parameter passing), where configs are merged rather than replaced
    Example
    # Parent sets tags
    chain.invoke(input, config={"tags": ["parent"]})
    # Child automatically inherits and can add:
    # ensure_config({"tags": ["child"]}) -> {"tags": ["parent", "child"]}

    Standard, multimodal content blocks for Large Language Model I/O.

    This module provides standardized data structures for representing inputs to and outputs from LLMs. The core abstraction is the Content Block, a TypedDict.

    Rationale

    Different LLM providers use distinct and incompatible API schemas. This module provides a unified, provider-agnostic format to facilitate these interactions. A message to or from a model is simply a list of content blocks, allowing for the natural interleaving of text, images, and other content in a single ordered sequence.

    An adapter for a specific provider is responsible for translating this standard list of blocks into the format required by its API.

    Extensibility

    Data not yet mapped to a standard block may be represented using the NonStandardContentBlock, which allows for provider-specific data to be included without losing the benefits of type checking and validation.

    Furthermore, provider-specific fields within a standard block are fully supported by default in the extras field of each block. This allows for additional metadata to be included without breaking the standard structure. For example, Google's thought signature:

    AIMessage(
        content=[
            {
                "type": "text",
                "text": "J'adore la programmation.",
                "extras": {"signature": "EpoWCpc..."},  # Thought signature
            }
        ], ...
    )
    Note

    Following widespread adoption of PEP 728, we intend to add extra_items=Any as a param to Content Blocks. This will signify to type checkers that additional provider-specific fields are allowed outside of the extras field, and that will become the new standard approach to adding provider-specific metadata.

    Note

    Example with PEP 728 provider-specific fields:

    # Content block definition
    # NOTE: `extra_items=Any`
    class TextContentBlock(TypedDict, extra_items=Any):
        type: Literal["text"]
        id: NotRequired[str]
        text: str
        annotations: NotRequired[list[Annotation]]
        index: NotRequired[int]
    from langchain_core.messages.content import TextContentBlock
    
    # Create a text content block with provider-specific fields
    my_block: TextContentBlock = {
        # Add required fields
        "type": "text",
        "text": "Hello, world!",
        # Additional fields not specified in the TypedDict
        # These are valid with PEP 728 and are typed as Any
        "openai_metadata": {"model": "gpt-5.5", "temperature": 0.7},
        "anthropic_usage": {"input_tokens": 10, "output_tokens": 20},
        "custom_field": "any value",
    }
    
    # Mutating an existing block to add provider-specific fields
    openai_data = my_block["openai_metadata"]  # Type: Any

    Example Usage

    # Direct construction
    from langchain_core.messages.content import TextContentBlock, ImageContentBlock
    
    multimodal_message: AIMessage(
        content_blocks=[
            TextContentBlock(type="text", text="What is shown in this image?"),
            ImageContentBlock(
                type="image",
                url="https://www.langchain.com/images/brand/langchain_logo_text_w_white.png",
                mime_type="image/png",
            ),
        ]
    )
    
    # Using factories
    from langchain_core.messages.content import create_text_block, create_image_block
    
    multimodal_message: AIMessage(
        content=[
            create_text_block("What is shown in this image?"),
            create_image_block(
                url="https://www.langchain.com/images/brand/langchain_logo_text_w_white.png",
                mime_type="image/png",
            ),
        ]
    )

    Factory functions offer benefits such as:

    • Automatic ID generation (when not provided)
    • No need to manually specify the type field