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.

Security model

The allowed_objects parameter controls which classes can be deserialized:

• 'core' (default): Allow classes defined in the serialization mappings for langchain_core.
• 'all': Allow classes defined in the serialization mappings. This includes core LangChain types (messages, prompts, documents, etc.) and trusted partner integrations. See langchain_core.load.mapping for the full list.
• Explicit list of classes: Only those specific classes are allowed.

For simple data types like messages and documents, the default allowlist is safe to use. These classes do not perform side effects during initialization.

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

Best practices

• Use the most restrictive allowed_objects possible. Prefer an explicit list of classes over 'core' or 'all'.
• 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,
    ],
)

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.

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.

Serializable base class.