Principle:Langchain ai Langgraph Serialization Protocol
| Attribute | Value |
|---|---|
| Knowledge Sources | LangGraph |
| Domains | Serialization, Protocol |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
The serialization protocol defines the foundational contracts -- SerializerProtocol, CipherProtocol, and supporting types -- that all serializers and ciphers in LangGraph's checkpoint and cache subsystems must satisfy.
Description
LangGraph's serialization layer is built on a set of runtime-checkable Protocol classes that establish uniform interfaces for data serialization, deserialization, and encryption.
SerializerProtocol is the primary interface, requiring two methods:
dumps_typed(obj) -> (type_string, bytes)-- Serializes an object to a type-tagged byte representation.loads_typed((type_string, bytes)) -> obj-- Deserializes from a type-tagged byte representation.
The typed approach preserves encoding metadata alongside the raw bytes, enabling heterogeneous storage backends to correctly reconstruct objects without out-of-band type information. For example, a serialized value carries a type string like "json" or "msgpack" to indicate which deserializer should be used.
CipherProtocol defines the encryption contract:
encrypt(plaintext) -> (cipher_name, ciphertext)decrypt(cipher_name, ciphertext) -> plaintext
The cipher name in the output supports multiple encryption algorithms and key rotation: data encrypted with different ciphers can coexist in the same store, and each blob carries enough information to select the correct decryptor.
UntypedSerializerProtocol supports simpler legacy serializers with dumps(obj) -> bytes and loads(data) -> obj. The SerializerCompat adapter wraps untyped serializers to conform to the typed protocol by using the object's class name as the type string. The maybe_add_typed_methods utility automatically detects and wraps legacy serializers, ensuring backwards compatibility.
The module also defines ChannelProtocol and SendProtocol -- lightweight protocol classes that mirror the channel and send interfaces for use in the serialization layer without importing the full channel module, preventing circular import dependencies. Five sentinel string constants (ERROR, SCHEDULED, INTERRUPT, RESUME, TASKS) identify special checkpoint channel names used for error states, scheduling, human-in-the-loop interrupts, resume signals, and task metadata respectively.
Usage
Use these protocols when implementing custom serializers or ciphers for LangGraph checkpointers and caches. Any object satisfying SerializerProtocol can be passed as the serde parameter to checkpoint savers and cache backends. The protocols also serve as contracts for runtime compatibility verification via isinstance checks since they are marked runtime_checkable.
Theoretical Basis
The serialization protocol implements the strategy pattern with structural typing: rather than requiring inheritance from a base class, any object that provides the required methods satisfies the protocol. This maximizes flexibility by allowing standard library modules, third-party serializers, and custom implementations to be used interchangeably.
The typed serialization format follows the self-describing message principle from distributed systems: each serialized payload carries enough metadata (the type string) to determine how to deserialize it. This eliminates the need for out-of-band schema registries and enables safe evolution of serialization formats within a single storage backend.
The CipherProtocol's inclusion of the cipher name in the output implements algorithm agility -- the ability to change encryption algorithms over time without losing the ability to read previously encrypted data. Combined with the SerializerProtocol's type string, this creates a composable layering where serialization format and encryption algorithm are independently versioned and identified.
The sentinel constants for special channel names implement a reserved namespace pattern, using double-underscore prefixes to avoid collision with user-defined channel names. Referencing these constants by name rather than by their string values ensures forward compatibility if the underlying values ever change.