Principle:Langchain ai Langgraph Type System
| Attribute | Value |
|---|---|
| Type | Principle |
| Knowledge Sources | LangGraph |
| Domains | Types, Core, Framework_Infrastructure |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
The type system defines the core generic type variables used throughout the LangGraph framework to parameterize graphs, protocols, runtime objects, and node signatures, ensuring type safety across the entire graph lifecycle.
Description
LangGraph centralizes its generic type variable definitions in a single module, establishing a consistent vocabulary of types that flow through the framework from graph construction through compilation to execution.
All type variables are bound to `StateLike`, which constrains them to types that can serve as graph state -- typically `TypedDict` subclasses, dataclasses, or Pydantic `BaseModel` subclasses. The primary type variables are:
- `StateT` -- Represents the main state of a graph. Used to parameterize `StateGraph`, `PregelProtocol`, and the compiled graph.
- `ContextT` -- Represents run-scoped context (e.g., user information, database connections). Bound to `StateLike | None` with a default of `None`, meaning graphs that do not use context need not specify this parameter.
- `InputT` -- Represents the input schema of a graph. Defaults to `StateT`, meaning the input type matches the state type unless explicitly overridden.
- `OutputT` -- Represents the output schema of a graph. Defaults to `StateT`, following the same convention as `InputT`.
- `NodeInputT` -- Represents the input type for an individual node, used in node-level type parameterization.
The module also provides variance-annotated variants (`StateT_co`, `StateT_contra`, `ContextT_contra`, `NodeInputT_contra`) for use in protocol and interface definitions where covariance or contravariance is required -- for example, return types use covariant type variables while parameter types use contravariant ones.
Usage
End users typically interact with the type system indirectly through `StateGraph` and compiled graph type annotations. When defining a graph with separate input, output, and state schemas, the `InputT` and `OutputT` defaults provide sensible behavior: if only a state schema is provided, input and output types automatically match it. Library authors and framework extenders use the type variables directly when defining custom protocols or generic wrappers around LangGraph components.
Theoretical Basis
The type system applies parametric polymorphism from type theory, enabling the framework's core abstractions (graphs, protocols, runtimes) to be parameterized by the specific state and context types used in each application. This provides compile-time safety guarantees without sacrificing flexibility.
The use of bounded type variables (bound to `StateLike`) implements a form of structural subtyping constraint, ensuring that only types compatible with graph state semantics can be used, while still allowing the full range of supported state representations (TypedDict, dataclass, BaseModel).
The default type parameter feature (PEP 696) is used for `ContextT`, `InputT`, and `OutputT`, implementing the convention over configuration principle: common cases (no context, input/output matching state) require no additional type specification, while advanced cases (separate schemas) remain fully supported. The variance annotations follow the Liskov Substitution Principle, ensuring that protocol implementations correctly handle subtype relationships in both input and output positions.