Principle:Langchain ai Langgraph Runtime Context
| Attribute | Value |
|---|---|
| Type | Principle |
| Knowledge Sources | LangGraph |
| Domains | Runtime, Configuration, Dependency_Injection |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
Runtime context injection provides graph nodes with access to run-scoped utilities and dependencies -- such as user context, persistent stores, and stream writers -- without requiring them to be part of the graph state.
Description
The `Runtime` dataclass is a frozen, generic container that bundles run-scoped context and utilities for graph node consumption. Introduced in LangGraph v0.6.0, it replaces the need for nodes to access configuration dictionaries directly, providing a clean, typed interface for runtime dependencies.
The `Runtime` object exposes four fields:
- `context` -- Static context for the graph run, parameterized by a generic type `ContextT`. This is where application-specific dependencies such as `user_id`, database connections, or API clients are provided. It is set via the `context` parameter when invoking the graph and defaults to `None`.
- `store` -- An optional `BaseStore` instance that provides persistence and memory capabilities. The store is set when compiling the graph and enables nodes to read and write persistent data across runs and threads.
- `stream_writer` -- A function that writes data to the custom stream, enabling nodes to emit real-time events to connected clients. Defaults to a no-op function when no streaming is configured.
- `previous` -- The previous return value for the given thread, available only when using the functional API with a checkpointer. This enables continuation patterns where a node can build upon its previous execution's output.
The `Runtime` object is immutable by design. When modifications are needed, the `merge` and `override` methods create new instances with updated fields, preserving the original. The `get_runtime()` helper function allows nodes to retrieve the current runtime from the active graph configuration without explicitly declaring it as a parameter.
Usage
Use `Runtime` when nodes need access to external dependencies or utilities that should not be stored in the graph state. Declare a `Runtime[MyContext]` parameter in the node function signature for automatic injection, or call `get_runtime()` from within the node body. Define a `context_schema` on the `StateGraph` to get type-safe context access. Use the `store` field for cross-session persistence and the `stream_writer` for real-time client communication.
Theoretical Basis
The `Runtime` dataclass implements the service locator pattern refined through dependency injection. Rather than having nodes discover their dependencies through global state or configuration lookups, the runtime bundles all external dependencies into a single, typed object that is injected into each node invocation. This makes dependencies explicit and testable.
The immutability of the `Runtime` object follows the value object pattern from domain-driven design: runtime instances are treated as values rather than entities, ensuring thread safety and preventing accidental mutation of shared state during parallel node execution within a superstep.
The generic parameterization via `ContextT` applies the type-safe configuration principle, enabling static type checkers to verify that nodes access context fields that actually exist on the provided context schema, catching configuration mismatches at development time rather than at runtime.