本文深入解析LangGraph Runtime机制，帮你理清状态管理与运行环境分离的关键设计，提升AI Agent开发效率。
核心内容：
1. Runtime解决State臃肿与运行依赖混杂的核心问题
2. Runtime、State、Context三大组件的职责与协作关系
3. 节点如何访问运行时信息，实现高效上下文管理

本文深入讲解 LangGraph 中 Runtime 机制的设计与作用，重点分析其如何解决 State 臃肿与运行依赖混杂的问题。结合 LangGraph 执行流程与 RunnableConfig、Context、Runtime 三大核心组件，并通过代码示例演示节点如何访问运行时信息，帮助开发者理解短期记忆、外部存储与 Agent 上下文管理的最佳实践，是构建高可维护 AI Agent 与 RAG 系统的重要参考内容。

本文最佳排版阅读体验请电脑端访问：https://mlwithme.github.io/agent/chapter05/5c1cad54efa54c31/

在 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 中连接业务逻辑与底层资源的桥梁。

往期精选推荐

[1] Agent的记忆机制与管理之长期记忆与短期记忆！

[2] 从 2-Step RAG 到 Agentic RAG：检索范式的升级之路！

[3] LangChain 短期记忆持久化：Agent 会话状态保存与使用！

[4] 为什么 AI Agent 都离不开 Function Calling ？

[5] 如何从零动手实现一个MiniChatGPT？附超详细注释学习源码！

[6] 彻底搞懂 KV Cache 大模型推理加速的核心！

[7] 基于两阶段索引的 RAG Agent 搭建！

点击下图购买作者编著新书

登录查看剩余 70% 内容