LangGraph Runtime 是什么？一文讲清Runtime与Context的作用及用法！

作者：袖梨 2026-07-03

本文深入解析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 !'}