Runtime, ToolRuntime & Managed Values — API reference
Runtime context injection, ToolRuntime for tools, ExecutionInfo, IsLastStep, RemainingSteps — how to access execution metadata and inject immutable context into nodes and tools.
Verified against langgraph==1.2.22 (modules: langgraph.runtime, langgraph.prebuilt.tool_node, langgraph.managed.is_last_step).
This page covers the three mechanisms LangGraph provides for injecting execution context into node and tool functions without threading values through graph state:
| Mechanism | Where it applies | Added in |
|---|---|---|
Runtime[ContextT] | Node functions | langgraph 0.6.0 |
ToolRuntime[ContextT, StateT] | Tool functions called by ToolNode | langgraph-prebuilt 1.0.2 |
IsLastStep / RemainingSteps | State schema fields (managed values) | before 0.4 (both in 0.4.10) |
Runtime[ContextT] — node-level injection
Section titled “Runtime[ContextT] — node-level injection”Runtime is a dataclass injected by the Pregel executor whenever a node function declares a runtime parameter. It bundles the execution context a node might need: the typed context object, the store, a stream writer, a heartbeat for idle timeouts, the Functional API’s previous value, execution metadata, and cooperative drain control.
Class definition
Section titled “Class definition”from dataclasses import dataclassfrom typing import Generic, TypeVar, Any
ContextT = TypeVar("ContextT")
@dataclassclass Runtime(Generic[ContextT]): context: ContextT # what you passed as invoke(..., context=...); None if nothing store: BaseStore | None # graph's store stream_writer: StreamWriter # write events to the custom stream channel heartbeat: Callable[[], None] # refresh an idle timeout (TimeoutPolicy) previous: Any # Functional API: the entrypoint's last saved value execution_info: ExecutionInfo | None # metadata about the current task server_info: ServerInfo | None # set inside the Agent Server, else None control: RunControl | None # cooperative drain handle # properties: drain_requested, drain_reasonField reference
Section titled “Field reference”| Field | Type | Description |
|---|---|---|
context | ContextT | The object passed as invoke(..., context=...) (or stream/ainvoke/astream). None if the caller passed none. context_schema types it; it is not validated against the schema. |
store | BaseStore | None | The graph’s persistent store (e.g. InMemoryStore, Postgres-backed store). None if no store was provided at compile time. |
stream_writer | StreamWriter | Callable that emits a value on the "custom" stream channel. Equivalent to injecting writer: StreamWriter directly. |
heartbeat | () -> None | Signals progress so a TimeoutPolicy(idle_timeout=...) does not fire. A no-op when no idle timeout is active. |
previous | Any | Functional API only: the value the @entrypoint returned (or saved) on the previous call in this thread. None in StateGraph nodes. |
execution_info | ExecutionInfo | None | Structured metadata: checkpoint ID, namespace, task ID, thread ID, run ID, attempt number and first-attempt time. Always set inside a node. |
server_info | ServerInfo | None | Populated when the graph runs in the Agent Server (LangSmith Deployment, a self-hosted server or langgraph dev). None when you call the graph in your own process. |
control | RunControl | None | Cooperative drain handle. External code calls control.request_drain(); a long node can check runtime.drain_requested and return early. See graceful shutdown. |
configis not onRuntime. If you needRunnableConfig(e.g. to pass toChatModel.invoke), add a separateconfig: RunnableConfigparameter to the node. Both parameters can coexist.
Injection pattern
Section titled “Injection pattern”Declare runtime as a typed parameter. LangGraph matches by the Runtime annotation — the parameter name itself does not matter, but runtime is conventional.
from dataclasses import dataclassfrom typing import Annotatedfrom langchain_core.messages import AnyMessage, HumanMessage, AIMessagefrom langchain_core.runnables import RunnableConfigfrom typing_extensions import TypedDictfrom langgraph.graph import StateGraph, START, ENDfrom langgraph.graph.message import add_messagesfrom langgraph.runtime import Runtimefrom langgraph.checkpoint.memory import InMemorySaverfrom langgraph.store.memory import InMemoryStore
@dataclassclass AppContext: user_id: str tenant_id: str
class State(TypedDict): messages: Annotated[list[AnyMessage], add_messages]
def personalized_response( state: State, runtime: Runtime[AppContext], config: RunnableConfig, # separate param — not on Runtime) -> dict: # Type-safe context access user_id = runtime.context.user_id tenant_id = runtime.context.tenant_id
# Read from the store (guard: store is None if graph was compiled without one) prefs = runtime.store.get(("users", user_id), "preferences") if runtime.store else None theme = prefs.value.get("theme", "light") if prefs else "light"
# Emit a progress event on the custom stream channel runtime.stream_writer({"status": "processing", "user": user_id})
# Execution metadata print(f"attempt #{runtime.execution_info.node_attempt}, thread={runtime.execution_info.thread_id}")
return {"messages": [AIMessage(f"Hello {user_id} (theme: {theme})")]}
store = InMemoryStore()builder = StateGraph(State, context_schema=AppContext)builder.add_node("respond", personalized_response)builder.add_edge(START, "respond")builder.add_edge("respond", END)graph = builder.compile(checkpointer=InMemorySaver(), store=store)
# Pass context at call time via the top-level `context=` keyword argumentresult = graph.invoke( {"messages": [HumanMessage("Hello")]}, {"configurable": {"thread_id": "t1"}}, context=AppContext(user_id="u123", tenant_id="acme"),)ExecutionInfo — execution metadata
Section titled “ExecutionInfo — execution metadata”ExecutionInfo is a frozen dataclass attached to runtime.execution_info. It gives structured access to IDs and counters that are otherwise scattered across RunnableConfig and the Pregel scratchpad.
Class definition
Section titled “Class definition”from dataclasses import dataclass, field
@dataclass(frozen=True, slots=True)class ExecutionInfo: checkpoint_id: str checkpoint_ns: str task_id: str thread_id: str | None # from config["configurable"]["thread_id"]; None if absent run_id: str | None # None if not set in RunnableConfig node_attempt: int = 1 # 1-indexed retry count (1 = first attempt) node_first_attempt_time: float | None = None # unix timestamp of first attemptField reference
Section titled “Field reference”| Field | Type | Description |
|---|---|---|
checkpoint_id | str | ID of the checkpoint this step runs from. |
checkpoint_ns | str | The task’s namespace, "<node>:<task_id>"; subgraphs add |-separated segments. |
task_id | str | ID of the Pregel task executing this node invocation. |
thread_id | str | None | Conversation thread identifier from the config, with or without a checkpointer. None when the config has none. |
run_id | str | None | Run ID from RunnableConfig. None if not supplied by the caller. |
node_attempt | int | How many times this node has been attempted for the current step (1-indexed). Increments on retries. |
node_first_attempt_time | float | None | Unix timestamp of the very first attempt. Useful for computing total time spent across retries. |
Usage example
Section titled “Usage example”import timefrom langgraph.runtime import Runtime
def resilient_node(state: State, runtime: Runtime) -> dict: info = runtime.execution_info
if info.node_attempt > 1: # node_first_attempt_time is float | None; guard against None defensively elapsed = time.time() - (info.node_first_attempt_time or time.time()) print(f"Retry #{info.node_attempt} after {elapsed:.1f}s on thread {info.thread_id}")
# Use task_id as an idempotency key for external API calls result = call_external_api( idempotency_key=info.task_id, payload=state["query"], ) return {"result": result}get_runtime() — function alternative
Section titled “get_runtime() — function alternative”get_runtime() retrieves the current Runtime from a context variable set by the executor. It is an alternative to parameter injection for cases where you cannot add parameters to the function signature (e.g. when wrapping third-party code).
from langgraph.runtime import get_runtimefrom langgraph.runtime import get_runtime
def my_node(state: State) -> dict: # Equivalent to declaring `runtime: Runtime` as a parameter runtime = get_runtime() user_id = runtime.context.user_id if runtime.context else None runtime.stream_writer({"event": "started"}) return {}get_runtime() raises RuntimeError: Called get_config outside of a runnable context if called outside a running node or task. Prefer parameter injection when the function signature is under your control — it is more explicit and easier to test.
ToolRuntime[ContextT, StateT] — tool-level injection
Section titled “ToolRuntime[ContextT, StateT] — tool-level injection”ToolRuntime is a separate dataclass for tool functions invoked by ToolNode. It is distinct from Runtime — it provides the tool with access to the current graph state, the triggering tool-call ID, the store, typed context, execution metadata and (in the Agent Server) server metadata.
Class definition
Section titled “Class definition”Verified against the installed langgraph-prebuilt==1.1.2 source (langgraph.prebuilt.tool_node):
@dataclassclass ToolRuntime(_DirectlyInjectedToolArg, Generic[ContextT, StateT]): state: StateT # current graph state context: ContextT # run context (None if not passed) config: RunnableConfig # runnable config passed to the tool stream_writer: StreamWriter # write events to the custom stream channel tool_call_id: str | None # ID of the ToolCall being executed store: BaseStore | None # graph's store tools: list[BaseTool] = field(default_factory=list) # tools registered with ToolNode execution_info: ExecutionInfo | None = None # execution metadata server_info: ServerInfo | None = None # Agent Server metadata (None outside the server)
def emit_output_delta(self, delta: Any) -> None: ... # partial output on stream_mode="tools"Field reference
Section titled “Field reference”| Field | Type | Description |
|---|---|---|
state | StateT | The current graph state at the time the tool is called. Lets tools read state without passing it through tool call arguments. |
context | ContextT | The run’s context object (None if the caller passed none). |
config | RunnableConfig | The full RunnableConfig. Unlike Runtime, ToolRuntime includes config directly. |
stream_writer | StreamWriter | Emit events on the custom stream channel (a no-op unless "custom" is streamed). |
tool_call_id | str | None | The ID of the ToolCall message that triggered this tool invocation. |
store | BaseStore | None | The graph’s persistent store (None if not compiled with one). |
tools | list[BaseTool] | All tools registered with the ToolNode. Lets one tool look up or delegate to another. |
execution_info | ExecutionInfo | None | Execution metadata (checkpoint ID, task ID, attempt number, thread ID). |
server_info | ServerInfo | None | Agent Server metadata (assistant/graph IDs, authenticated user). None outside the server. |
Usage example
Section titled “Usage example”from dataclasses import dataclassfrom typing import Annotatedfrom typing_extensions import TypedDictfrom langchain_core.messages import AnyMessagefrom langchain_core.tools import toolfrom langgraph.graph.message import add_messagesfrom langgraph.prebuilt import ToolNodefrom langgraph.prebuilt.tool_node import ToolRuntime
@dataclassclass AppContext: user_id: str
class State(TypedDict): messages: Annotated[list[AnyMessage], add_messages] user_tier: str
@tooldef fetch_user_data(query: str, runtime: ToolRuntime[AppContext, State]) -> str: """Fetch data for the current user.""" # Read typed context user_id = runtime.context.user_id
# Read graph state directly — no need to pass it via tool arguments tier = runtime.state["user_tier"] if runtime.state else "free"
# Persist a result to the store runtime.store.put( ("users", user_id, "searches"), runtime.tool_call_id, {"query": query, "tier": tier}, )
# Emit a streaming event (no-op unless stream_mode includes "custom") runtime.stream_writer({"tool": "fetch_user_data", "query": query})
return f"Results for {user_id} (tier={tier}): ..."
tool_node = ToolNode([fetch_user_data])ServerInfo — Agent Server metadata
Section titled “ServerInfo — Agent Server metadata”ServerInfo is a frozen dataclass injected into Runtime.server_info and ToolRuntime.server_info when the graph runs inside the LangGraph Agent Server (LangSmith Deployment, a standalone server, or langgraph dev). It is None when you call the graph directly in your own process.
from dataclasses import dataclassfrom langgraph_sdk.auth.types import BaseUser
@dataclass(frozen=True, slots=True)class ServerInfo: assistant_id: str """The assistant ID for the current execution."""
graph_id: str """The graph ID for the current execution."""
user: BaseUser | None = None """The authenticated user, if any. Implements BaseUser from langgraph_sdk.auth.types: supports both attribute access (user.identity) and dict access (user["identity"]). """Field reference
Section titled “Field reference”| Field | Type | Available | Description |
|---|---|---|---|
assistant_id | str | Agent Server only | Assistant identifier |
graph_id | str | Agent Server only | Graph ID from langgraph.json |
user | BaseUser | None | Agent Server + auth | Authenticated user from the server’s auth handler; None if no auth is configured |
Guard pattern — in-process vs server
Section titled “Guard pattern — in-process vs server”server_info is None outside the Agent Server. Always guard:
from langgraph.runtime import Runtime
def my_node(state: dict, runtime: Runtime) -> dict: if runtime.server_info is not None: assistant_id = runtime.server_info.assistant_id graph_id = runtime.server_info.graph_id print(f"Running in Agent Server: assistant={assistant_id}, graph={graph_id}") else: print("Running in-process") return stateAccessing the authenticated user
Section titled “Accessing the authenticated user”When the server has an auth handler (auth.path in langgraph.json), server_info.user is populated:
from langgraph.runtime import Runtime
def personalized_node(state: dict, runtime: Runtime) -> dict: user = runtime.server_info.user if runtime.server_info else None
if user is None: user_id = "anonymous" user_email = None else: # BaseUser supports both attribute and dict access user_id = user.identity # or user["identity"] user_email = getattr(user, "email", None)
return {"user_id": user_id, "user_email": user_email}Routing by graph identity (multi-graph deployments)
Section titled “Routing by graph identity (multi-graph deployments)”In a deployment that hosts multiple graphs, graph_id lets a shared node adjust behaviour per-graph:
GRAPH_CONFIGS = { "customer-support": {"max_steps": 10, "model": "gpt-6.1-sol"}, "internal-tools": {"max_steps": 50, "model": "gpt-6-luna"},}
from langgraph.runtime import Runtime
def adaptive_node(state: dict, runtime: Runtime) -> dict: graph_id = runtime.server_info.graph_id if runtime.server_info else "default" config = GRAPH_CONFIGS.get(graph_id, {"max_steps": 25, "model": "gpt-6-luna"}) # use config["model"] and config["max_steps"] ... return stateRuntime vs ToolRuntime comparison
Section titled “Runtime vs ToolRuntime comparison”| Attribute | Runtime[ContextT] | ToolRuntime[ContextT, StateT] |
|---|---|---|
| Used in | Node functions | Tool functions (via ToolNode) |
| Import | langgraph.runtime | langgraph.prebuilt.tool_node |
context | Yes | Yes |
store | Yes | Yes |
stream_writer | Yes | Yes |
config | No — add config: RunnableConfig separately | Yes (included directly) |
state | No — read from the state parameter | Yes — current graph state snapshot |
tool_call_id | No | Yes |
tools | No | Yes — all tools registered with ToolNode |
execution_info | Yes | Yes |
heartbeat | Yes | No |
previous | Yes — Functional API’s last saved value | No |
server_info | Yes (None outside the Agent Server) | Yes (None outside the Agent Server) |
control | Yes (RunControl) | No |
| Generic type params | Runtime[ContextT] | ToolRuntime[ContextT, StateT] |
| Added in | langgraph 0.6.0 | langgraph-prebuilt 1.0.2 |
Managed values — IsLastStep & RemainingSteps
Section titled “Managed values — IsLastStep & RemainingSteps”Managed values are state-field annotations that LangGraph fills in automatically from the Pregel executor’s scratchpad. They are declared in the state schema like any other field, but the graph — not node code — writes them at each step. Nodes read them as ordinary state fields.
Two managed values ship with LangGraph out of the box:
| Type alias | Module | Type | Value |
|---|---|---|---|
IsLastStep | langgraph.managed.is_last_step | bool | True on the last step the recursion limit allows |
RemainingSteps | langgraph.managed.is_last_step | int | Steps left before the limit, counting the current one |
Both are Annotated[T, <Manager>] type aliases (IsLastStepManager, RemainingStepsManager). The graph computes them for every step; a node that returns one of these keys has the write dropped with a logged warning (wrote to unknown channel ..., ignoring it).
Imports
Section titled “Imports”# Preferred import path (re-exported from the public managed package)from langgraph.managed import IsLastStep, RemainingSteps
# Direct module import (also valid)from langgraph.managed.is_last_step import IsLastStep, RemainingStepsMinimal runnable example
Section titled “Minimal runnable example”from typing import Annotatedfrom typing_extensions import TypedDictfrom langchain_core.messages import AnyMessage, HumanMessage, AIMessagefrom langgraph.graph import StateGraph, START, ENDfrom langgraph.graph.message import add_messagesfrom langgraph.managed import IsLastStep, RemainingSteps
class State(TypedDict): messages: Annotated[list[AnyMessage], add_messages] is_last_step: IsLastStep # bool — injected by the graph remaining: RemainingSteps # int — injected by the graph
def my_node(state: State) -> dict: if state["is_last_step"]: return {"messages": [AIMessage("Max steps reached — returning early.")]} print(f"Steps remaining: {state['remaining']}") return {"messages": [AIMessage("Still going...")]}
builder = StateGraph(State)builder.add_node("my_node", my_node)builder.add_edge(START, "my_node")builder.add_conditional_edges("my_node", lambda s: END if s["is_last_step"] else "my_node")
graph = builder.compile()# Set the limit explicitly: with the default (10007) this loop would run ~10,000 times.graph.invoke({"messages": [HumanMessage("Start")]}, {"recursion_limit": 5})IsLastStep
Section titled “IsLastStep”IsLastStep = Annotated[bool, IsLastStepManager]IsLastStep is True on the last step the run may take before GraphRecursionError. Use it to return a graceful partial result instead of raising.
from langgraph.managed import IsLastStep
class AgentState(TypedDict): messages: Annotated[list[AnyMessage], add_messages] is_last: IsLastStep
def agent(state: AgentState) -> dict: if state["is_last"]: return {"messages": [AIMessage("[truncated: recursion limit reached]")]} response = llm_with_tools.invoke(state["messages"]) return {"messages": [response]}Step-count details:
- Default recursion limit: 10007 steps (override with the
LANGGRAPH_DEFAULT_RECURSION_LIMITenvironment variable; releases up to 1.0.5 used 25, and 1.0.6 to 1.1.3 used 10000). That default is too high to act as a loop guard, so set it per call. - Override per-call:
graph.invoke(input, {"recursion_limit": 50}). - The input counts as a step. In the minimal example above, with
recursion_limit=5the node runs four times:RemainingStepsreads 4, 3, 2, 1 andIsLastStepisTrueon the fourth run.
RemainingSteps
Section titled “RemainingSteps”RemainingSteps = Annotated[int, RemainingStepsManager]RemainingSteps is the number of steps left, counting the current one, and decrements by 1 each step; it is 1 on the step where IsLastStep is True.
from langgraph.managed import RemainingSteps
class PipelineState(TypedDict): items: list[str] processed: list[str] steps_left: RemainingSteps
def process_one(state: PipelineState) -> dict: if state["steps_left"] <= 2: # Flush remaining items — not enough steps to process individually return {"processed": state["processed"] + [f"[skipped: {len(state['items'])} items]"]} first, *rest = state["items"] return {"items": rest, "processed": state["processed"] + [first.upper()]}Import reference
Section titled “Import reference”| Symbol | Canonical import | Notes |
|---|---|---|
Runtime | from langgraph.runtime import Runtime | |
get_runtime | from langgraph.runtime import get_runtime | |
ExecutionInfo | from langgraph.runtime import ExecutionInfo | Attached as runtime.execution_info |
ToolRuntime | from langgraph.prebuilt.tool_node import ToolRuntime | |
IsLastStep | from langgraph.managed import IsLastStep | Also at langgraph.managed.is_last_step |
RemainingSteps | from langgraph.managed import RemainingSteps | Also at langgraph.managed.is_last_step |
StreamWriter | from langgraph.types import StreamWriter | Type of runtime.stream_writer |
BaseStore | from langgraph.store.base import BaseStore | Type of runtime.store |
InMemoryStore | from langgraph.store.memory import InMemoryStore | Concrete store for local dev |
InMemorySaver | from langgraph.checkpoint.memory import InMemorySaver | Concrete checkpointer for local dev |
context_schema | StateGraph(..., context_schema=MyContext) | Graph constructor kwarg |
Patterns
Section titled “Patterns”ReAct agent with Runtime context and store
Section titled “ReAct agent with Runtime context and store”from dataclasses import dataclassfrom typing import Annotatedfrom typing_extensions import TypedDictfrom langchain_core.messages import AnyMessage, HumanMessage, AIMessagefrom langgraph.graph import StateGraph, START, ENDfrom langgraph.graph.message import add_messagesfrom langgraph.managed import IsLastStepfrom langgraph.runtime import Runtimefrom langgraph.checkpoint.memory import InMemorySaverfrom langgraph.store.memory import InMemoryStore
@dataclassclass UserContext: user_id: str locale: str = "en"
class AgentState(TypedDict): messages: Annotated[list[AnyMessage], add_messages] is_last: IsLastStep
def call_agent(state: AgentState, runtime: Runtime[UserContext]) -> dict: if state["is_last"]: return {"messages": [AIMessage("Step limit reached.")]}
user_id = runtime.context.user_id if runtime.context else "anon" history = runtime.store.get(("sessions", user_id), "history") if runtime.store else None prev_messages = history.value if history else []
runtime.stream_writer({"event": "agent_start", "user": user_id})
response = llm_with_tools.invoke(state["messages"] + prev_messages)
if runtime.store: runtime.store.put( ("sessions", user_id), "history", {"last_response": response.content}, ) return {"messages": [response]}
def router(state: AgentState) -> str: if state["is_last"]: return END last = state["messages"][-1] if hasattr(last, "tool_calls") and last.tool_calls: return "tools" return END
store = InMemoryStore()builder = StateGraph(AgentState, context_schema=UserContext)builder.add_node("agent", call_agent)builder.add_node("tools", tool_node)builder.add_edge(START, "agent")builder.add_conditional_edges("agent", router)builder.add_edge("tools", "agent")
graph = builder.compile(checkpointer=InMemorySaver(), store=store)
result = graph.invoke( {"messages": [HumanMessage("What is the weather?")]}, {"configurable": {"thread_id": "session-42"}}, context=UserContext(user_id="alice", locale="en-GB"), # not inside "configurable")Retry-aware node using ExecutionInfo
Section titled “Retry-aware node using ExecutionInfo”import timefrom langgraph.runtime import Runtime
def idempotent_node(state: State, runtime: Runtime) -> dict: info = runtime.execution_info
if info.node_attempt > 1: elapsed = time.time() - (info.node_first_attempt_time or time.time()) print(f"Retry {info.node_attempt} for task {info.task_id} after {elapsed:.1f}s")
# Use task_id as idempotency key — safe to retry result = post_to_external_api( idempotency_key=info.task_id, data=state["payload"], ) return {"result": result}Tool with ToolRuntime accessing state and context
Section titled “Tool with ToolRuntime accessing state and context”from dataclasses import dataclassfrom langchain_core.tools import toolfrom langgraph.prebuilt import ToolNodefrom langgraph.prebuilt.tool_node import ToolRuntime
@dataclassclass AppContext: api_key: str
class MyState(TypedDict): messages: Annotated[list[AnyMessage], add_messages] account_id: str
@tooldef look_up_account(query: str, runtime: ToolRuntime[AppContext, MyState]) -> str: """Look up account information.""" # Context gives the API key without putting it in state api_key = runtime.context.api_key
# State gives the current account_id without passing it via tool args account_id = runtime.state["account_id"] if runtime.state else "unknown"
runtime.stream_writer({"tool": "look_up_account", "account": account_id})
return call_accounts_api(api_key=api_key, account_id=account_id, query=query)
tool_node = ToolNode([look_up_account])get_runtime() for code you cannot annotate
Section titled “get_runtime() for code you cannot annotate”from langgraph.runtime import get_runtime
def third_party_wrapper(state: State) -> dict: # This function signature is fixed — cannot add a runtime param runtime = get_runtime() runtime.stream_writer({"event": "third_party_start"}) result = run_third_party_logic(state["data"]) return {"result": result}Combining RemainingSteps with Runtime
Section titled “Combining RemainingSteps with Runtime”from langgraph.managed import RemainingStepsfrom langgraph.runtime import Runtime
class PipelineState(TypedDict): stages: list[str] output: str steps_left: RemainingSteps
def pipeline_node(state: PipelineState, runtime: Runtime[AppContext]) -> dict: # Bail out early if steps are running low if state["steps_left"] <= 2: runtime.stream_writer({"warning": "low_steps", "remaining": state["steps_left"]}) return {"output": state["output"] + " [pipeline aborted: low steps]"}
stage, *rest = state["stages"] result = run_stage(stage, context=runtime.context) return {"stages": rest, "output": state["output"] + f"\n{stage}: {result}"}How managed values work (internals)
Section titled “How managed values work (internals)”Each managed value is a subclass of ManagedValue[T] with a get(scratchpad) static method. The Pregel executor calls get when it builds a node’s input and adds the result to the state the node sees. It is not a channel, so it never appears in checkpoints or get_state().
# Simplified internals — do not import these directlyfrom langgraph._internal._scratchpad import PregelScratchpad
class IsLastStepManager(ManagedValue[bool]): @staticmethod def get(scratchpad: PregelScratchpad) -> bool: return scratchpad.step == scratchpad.stop - 1
class RemainingStepsManager(ManagedValue[int]): @staticmethod def get(scratchpad: PregelScratchpad) -> int: return scratchpad.stop - scratchpad.stepPregelScratchpad.step is the thread’s current step number and stop is where this run must end: at the start of each invoke, stop = step + recursion_limit + 1. That is why every invoke gets the full limit again.
Gotchas
Section titled “Gotchas”-
configis not onRuntime. Addconfig: RunnableConfigas a separate parameter if you need it alongsideruntime: Runtime. -
ToolRuntimeis notRuntime. They are different classes from different modules. A node annotated withruntime: ToolRuntimewill not receive injection — it must useRuntime. The inverse also holds. -
Managed values are read-only. A node that returns a managed-value key has that write dropped, with only a logged warning.
-
Managed values do not appear in checkpoints. They are reconstructed from the scratchpad at runtime. You cannot read them from
StateSnapshotorget_state_historyresults. -
You never pass managed values in the input. A
TypedDictfield annotatedIsLastSteporRemainingStepsdoes not needtotal=Falseor a default; the graph fills it in for every node. -
recursion_limitis per-invoke, not per-graph. Different calls tograph.invokecan use different limits.IsLastStepandRemainingStepstrack whichever limit was active when the run started. -
The limit applies per
invoke. A newinvokeon an existing thread gets the fullrecursion_limitagain, even though the thread’s step number keeps increasing. -
get_runtime()raises outside a task context. Do not call it from module-level code, background threads, or any code path that runs outside the Pregel executor.