本文深入讲解 LangGraph 中 Runtime 机制的设计与作用，重点分析其如何解决 State 臃肿与运行依赖混杂的问题。结合 LangGraph 执行流程与 RunnableConfig、Context、Runtime 三大核心组件，并通过代码示例演示节点如何访问运行时信息，帮助开发者理解短期记忆、外部存储与 Agent 上下文管理的最佳实践，是构建高可维护 AI Agent 与 RAG 系统的重要参考内容。
在 LangGraph 中，节点执行时往往不仅需要业务数据（状态，State），还需要用户 ID、线程 ID、数据库连接、存储对象等运行环境信息。如果把这些内容都塞进 State，状态会很快变得臃肿，而且很多资源对象本身也不适合序列化或写入检查点。
因此，LangGraph 提供了 Runtime。它的作用不是替代 State，而是为节点提供统一的运行时入口，让图中的业务状态与系统资源保持分离。
1. Runtime 要解决什么问题
先看一个典型场景。一个节点可能需要下面两类信息：
业务数据，例如用户输入、历史消息、检索结果。 运行信息，例如 user_id、thread_id、数据库连接、Store 对象。
这两类内容职责不同。如果全部混在 State 中，会带来两个问题：一是 State 不再纯粹，二是数据库连接这类资源很难安全地持久化。
Runtime 的意义就在于，把这些“运行依赖”从 State 中分离出来。
2. Runtime 和 State 有什么区别
两者最核心的区别是职责不同。
State保存业务状态，也就是图在处理什么。Runtime提供运行环境，也就是节点依赖什么来完成处理。
换言之，State 负责数据流动，Runtime 负责环境注入。这样设计后，图的状态更清晰，节点也更容易维护。
3. LangGraph 中 Runtime 是如何工作的
在 LangGraph 中，调用 invoke() 时，框架会根据本次传入的 config 和 context，在节点执行阶段自动构造 Runtime 对象。
这里通常有三个角色：
State：保存输入、输出和中间业务结果。Context：承载要注入 Runtime 的上下文，例如user_id、数据库连接器。RunnableConfig：承载本次调用配置，例如thread_id。
节点执行时，就可以同时读取这三类来源的信息。
4. 示例：节点如何访问 Runtime
下面这段代码演示了最基本的用法：节点除了读取输入 state 之外，还从 config 中读取 thread_id，并从 runtime.context 中读取 user_id 和数据库名称。
1 from dataclasses import dataclass
2 from langchain_core.runnables import RunnableConfig
3 from langgraph.graph import START, StateGraph
4 from langgraph.runtime import Runtime
5 from typing_extensions import TypedDict
6
7 class State(TypedDict):
8 input: str
9 results: str
10
11 class DBConnector:
12 def __init__(self, db_name: str = None):
13 self.db_name = db_name
14
15 @dataclass
16 class Context:
17 user_id: str = "default"
18 db_connector: DBConnector = None
19
20 def my_node(state: State, config: RunnableConfig, runtime: Runtime):
21 thread_id = config["configurable"]["thread_id"]
22 user_id = runtime.context.user_id
23 db_name = runtime.context.db_connector.db_name
24 return {
25 "results": (
26 f"Hello, {state['input']}, I am {user_id} in thread {thread_id}, "
27 f"db_name = {db_name} !")}
28
29 if __name__ == "__main__":
30 builder = StateGraph(State, context_schema=Context)
31 builder.add_node("my_node", my_node)
32 builder.add_edge(START, "my_node")
33 graph = builder.compile()
34 config = RunnableConfig(
35 configurable={"thread_id": "fd1bd9f0-5d3c-487a-938e-b14513efa48k"})
36 context = Context(
37 user_id="demo_user",
38 db_connector=DBConnector(db_name="my_database.db"))
39 result = graph.invoke({"input": "Everyone"}, config=config, context=context)
40 print(result)
# {'input': 'Everyone', 'results': 'Hello, Everyone, I am demo_user in thread fd1bd9f0-5d3c-487a-938e-b14513efa48k, db_name = my_database.db !'}
这段代码说明了三件事：
state保存的是业务输入输出。config适合放线程级配置。runtime.context适合放用户信息和外部资源。
最终，节点可以在不污染 State 的前提下，拿到完整的运行环境。
5. 实际工程里 Runtime 常放什么
在真实项目中，Runtime 通常会承载下面几类内容：
thread_id：用于短期记忆和会话隔离。user_id：用于长期记忆的用户级隔离。Store、数据库连接：用于访问长期记忆或外部系统。RunnableConfig中的其他参数：用于传递本次调用的控制配置。
例如在 Mini ChatGPT 助手这类工程中，PostgresSaver 常用于短期检查点，PostgresStore 常用于长期记忆，而它们都更适合通过 Runtime 进入节点。
6. 小结
Runtime 的本质，是 LangGraph 为“运行环境”提供的一层正式抽象。
它把业务状态和系统资源分开管理，让 State 保持纯净，也让节点能够清晰地访问用户上下文、线程配置和外部存储对象。因此，Runtime 可以看作 LangGraph 中连接业务逻辑与底层资源的桥梁。
