load

Type alias for a callable that validates kwargs during deserialization.

The callable receives:

• class_path: A tuple of strings identifying the class being instantiated (e.g., ('langchain', 'schema', 'messages', 'AIMessage')).
• kwargs: The kwargs dict that will be passed to the constructor.

The validator should raise an exception if the object should not be deserialized.

Import an attribute from a module located in a package.

This utility function is used in custom __getattr__ methods within __init__.py files to dynamically import attributes.

Return a dict representation of an object.

Return a JSON string representation of an object.

Revive a LangChain class from a JSON string.

Equivalent to load(json.loads(text)).

Only classes in the allowlist can be instantiated. The default allowlist includes core LangChain types (messages, prompts, documents, etc.). See langchain_core.load.mapping for the full list.

Load LangChain objects from JSON strings or objects.

How it works

Each Serializable LangChain object has a unique identifier (its "class path"), which is a list of strings representing the module path and class name. For example:

• AIMessage -> ["langchain_core", "messages", "ai", "AIMessage"]
• ChatPromptTemplate -> ["langchain_core", "prompts", "chat", "ChatPromptTemplate"]

When deserializing, the class path from the JSON 'id' field is checked against an allowlist. If the class is not in the allowlist, deserialization raises a ValueError.

Threat model

A serialized LangChain payload crosses a trust boundary because the manifest may contain serialized objects and configuration that affect runtime behavior. For example, a payload can configure a chat model with a custom base_url, custom headers, a different model name, or other constructor arguments. These are supported features, but they also mean the payload contents should be treated as executable configuration rather than plain text.

Concretely, deserialization instantiates Python objects, so any constructor (__init__) or validator on an allowed class can run during load(). A crafted payload that is allowed to reach an unintended class — or an intended class with attacker-controlled kwargs — could cause network calls, file operations, or environment-variable access while the object is being built.

The allowed_objects parameter controls which classes can be deserialized:

• Explicit list of classes (recommended for untrusted input): only those specific classes are allowed.
• 'messages': chat-message classes only (e.g. AIMessage, HumanMessage). Safe for untrusted input.
• 'core' (current default) — unsafe with untrusted manifests. Classes defined in the serialization mappings under langchain_core (messages, documents, prompts, etc.).
• 'all' — unsafe with untrusted manifests. Every class in the serialization mappings, including partner chat models and LLMs and their constructor kwargs (endpoint URLs, headers, model names, etc.).

Import paths are also validated against trusted namespaces before any module is imported.

Best practices

• Use the most restrictive allowed_objects possible. For untrusted input, pass an explicit list of classes or 'messages'. 'core' and 'all' are unsafe with untrusted manifests — only use them when the source serves the entire payload, including its configuration.
• Keep secrets_from_env set to False (the default). If you must use it, ensure the serialized data comes from a fully trusted source, as a crafted payload can read arbitrary environment variables.
• When using secrets_map, include only the specific secrets that the serialized object requires.

Injection protection (escape-based)

During serialization, plain dicts that contain an 'lc' key are escaped by wrapping them: {"__lc_escaped__": {...}}. During deserialization, escaped dicts are unwrapped and returned as plain dicts, NOT instantiated as LC objects.

This is an allowlist approach: only dicts explicitly produced by Serializable.to_json() (which are NOT escaped) are treated as LC objects; everything else is user data.

Even if an attacker's payload includes __lc_escaped__ wrappers, it will be unwrapped to plain dicts and NOT instantiated as malicious objects.

Examples

from langchain_core.load import load
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.messages import AIMessage, HumanMessage

# Use default allowlist (classes from mappings) - recommended
obj = load(data)

# Allow only specific classes (most restrictive)
obj = load(
    data,
    allowed_objects=[
        ChatPromptTemplate,
        AIMessage,
        HumanMessage,
    ],
)

Serializable base class.

Init validators for deserialization security.

This module contains extra validators that are called during deserialization, ex. to prevent security issues such as SSRF attacks.

Each validator is a callable matching the InitValidator protocol: it takes a class path tuple and kwargs dict, returns None on success, and raises ValueError if the deserialization should be blocked.

Serialize LangChain objects to JSON.

Provides dumps (to JSON string) and dumpd (to dict) for serializing Serializable objects.

Escaping

During serialization, plain dicts (user data) that contain an 'lc' key are escaped by wrapping them: {"__lc_escaped__": {...original...}}. This prevents injection attacks where malicious data could trick the deserializer into instantiating arbitrary classes. The escape marker is removed during deserialization.

This is an allowlist approach: only dicts explicitly produced by Serializable.to_json() are treated as LC objects; everything else is escaped if it could be confused with the LC format.

Serialization mapping.

This file contains a mapping between the lc_namespace path for a given subclass that implements from Serializable to the namespace where that class is actually located.

This mapping helps maintain the ability to serialize and deserialize well-known LangChain objects even if they are moved around in the codebase across different LangChain versions.

For example, the code for the AIMessage class is located in langchain_core.messages.ai.AIMessage. This message is associated with the lc_namespace of ["langchain", "schema", "messages", "AIMessage"], because this code was originally in langchain.schema.messages.AIMessage.

The mapping allows us to deserialize an AIMessage created with an older version of LangChain where the code was in a different location.