什么是LangChain Runtime?

是 LangChain 1.0 中以 Agent 为核心的运行时环境，基于 LangGraph 构建，是 Agent 执行的底层支撑，负责管理生命周期、上下文、存储与流式输出。

1. 核心定义

LangChain Runtime = LangChain 1.0 中 Agent 的核心工作环境
你用 LangChain.create_agent() 创建的 Agent，都运行在这个 Runtime 之上
生命周期：Agent 创建时自动生成；Agent 结束时销毁
作用：提供依赖注入、持久化、流式输出、状态管理等基础能力

2. Runtime 三大核心组件

Context（上下文）
- 静态信息集合：用户 ID、数据库连接、调用配置、依赖项
- 作用：不硬编码，运行时注入，让工具 / 中间件更可复用、可测试
Store（存储）
- 类型：BaseStore 实例
- 作用：长期记忆、跨轮次持久化状态
Stream Writer（流式写入器）
- 作用：支持 custom 流式模式，实时输出执行过程与结果

3. 与 LangChain / LangGraph 的关系

LangChain.create_agent() 是高层快速构建接口
底层运行在 LangGraph 的 Runtime
优点：高层快速开发 + 底层可灵活定制

LangChain Runtime 就是 Agent 的 “执行引擎 + 环境容器”，提供上下文、存储、流式输出与生命周期管理，让 Agent 稳定、可持久、可注入依赖地运行。

Runtime的创建（在create_agent中）

这是 LangChain 1.0 中为智能体（Agent）自定义 Context（上下文） 的完整流程，核心目的：让 Agent 运行时携带自定义的上下文数据，实现数据与 Agent 解耦、可注入、可复用。

核心流程分 3 步：

定义上下文结构：用 dataclass 定义要传给 Runtime 的上下文字段。
创建智能体并绑定上下文：创建 Agent 时指定上下文 schema。
调用时传入上下文：执行时把具体上下文数据传给 Agent。

步骤 1：定义上下文格式

from dataclasses import dataclass
from langchain.agents import create_agent

# 定义上下文结构：包含 user_name 字符串
@dataclass
class Context:
    user_name: str

用 dataclass 定义上下文数据结构。
这里只有一个字段：user_name（用户名）。

步骤 2：创建智能体并绑定上下文

# 创建智能体，绑定上下文格式
agent = create_agent(
    "gpt-4o",
    tools=[...],
    context_schema=Context,  # 绑定上下文结构
)

create_agent：创建智能体。
context_schema=Context：告诉 Runtime 这个 Agent 要使用的上下文格式。
此时 Agent 已 “注册” 上下文结构，运行时会预留该数据位置。

步骤 3：调用时传入具体上下文

# 调用智能体，传入上下文数据
agent.invoke(
    messages=[{"role": "user", "content": "what's my name?"}],
    context=Context(user_name="John Smith"),  # 传入具体上下文
)

执行时把 user_name="John Smith" 注入 Runtime。
Agent 可以在工具 / 推理中读取这个上下文。

作用：让 Agent 运行时携带自定义上下文，实现：

数据与 Agent 分离
可注入、可配置
多用户、多场景复用

在工具中访问Runtime数据

工具可以通过 ToolRuntime 读取 / 写入 Runtime 中的上下文、存储、流式输出等信息，实现工具与 Agent 运行环境的深度联动。

核心能力：

从 Runtime 读取上下文（Context）
读写持久化存储（Store）
自定义流式输出（StreamWriter）

from dataclasses import dataclass
from langchain.tools import tool
from langchain.agents import ToolRuntime

@dataclass
class Context:
    user_id: str
    
@tool("获取用户邮件偏好设置")
def tool_get_user_email_preferences(runtime: ToolRuntime) -> str:
    """获取用户邮件的偏好设置"""
    # 1. 从 Runtime 读取上下文里的 user_id
    user_id = runtime.context.user_id
    # 2. 从上下文获取用户偏好
    preferences = runtime.context.preferences
    return preferences

runtime: ToolRuntime：自动注入运行时对象
runtime.context：读取 Agent 传入的上下文数据
示例：获取 user_id 和用户偏好 preferences

Runtime 可访问能力总结

读写上下文：runtime.context → 读取 / 写入运行时上下文
读写存储：runtime.store → 持久化记忆、长期状态
自定义流式输出：runtime.stream_writer → 实时输出、自定义更新

工具通过 ToolRuntime 直接访问 Agent 运行时的上下文、存储、流式能力，让工具能感知环境、持久化状态、实时输出。

在中间件中访问Runtime数据

LangChain 1.0 中间件（Middleware）访问 Runtime 的三种典型用法：

动态提示词中间件：在请求模型前修改提示词，读取 Runtime 上下文。
模型前后处理中间件：在模型调用前 / 后执行逻辑，读写上下文。
创建智能体时挂载中间件：把中间件绑定到 Agent 运行时。

核心：中间件可以通过 ModelRequest 拿到 Runtime，从而读写上下文、状态等信息。

动态提示词中间件

from dataclasses import dataclass
from langchain.agents.middleware import dynamic_prompt, ModelRequest

@dataclass
class Context:
    user_name: str

@dynamic_prompt
async def dynamic_runtime_system_prompt(request: ModelRequest) -> str:
    # 从 Runtime 上下文获取用户名
    user_name = request.runtime.context.user_name
    # 构造动态系统提示词
    return f"You are a helpful assistant. The user's name is {user_name}."

解读

@dynamic_prompt：动态提示词装饰器。
request.runtime.context：读取运行时上下文。
作用：根据上下文动态生成系统提示词。

模型前后处理中间件

from langchain.agents.middleware import before_model, after_model, ModelRequest

# 模型调用前
@before_model
async def before_model(state: dict, runtime: RuntimeContext) -> dict | None:
    print("正在调用模型：", runtime.context.user_name)
    return None

# 模型调用后
@after_model
async def after_model(state: dict, runtime: RuntimeContext) -> dict | None:
    print("模型调用完成：", runtime.context.user_name)
    return None

解读

@before_model：模型调用前执行。
@after_model：模型调用后执行。
可用于日志、统计、上下文修改等

创建智能体时挂载中间件

from langchain.agents import create_agent

agent = create_agent(
    "gpt-4o",
    tools=[...],
    middleware=[
        dynamic_runtime_system_prompt,
        before_model,
        after_model,
    ],
    context_schema=Context,
)

# 调用并传入上下文
agent.invoke(
    messages=[{"role": "user", "content": "what's my name?"}],
    context=Context(user_name="John Smith"),
)

解读

middleware=[...]：创建 Agent 时挂载中间件。
执行时自动触发：动态提示词 → 模型前 → 模型后。
上下文通过 context= 传入。

总结

中间件 = Agent 执行流程的钩子。
可在模型前 / 后、提示词生成阶段读写 Runtime 上下文。
用于：动态提示、日志、统计、上下文注入、后处理等。

最佳实践

LangChain Runtime 开发的最佳实践与性能优化指南，核心目标：提升 Agent 运行效率、减少资源消耗、优化执行速度。

1️⃣ 上下文（Context）优化

明确上下文结构：明确定义 Context 数据结构，提升代码可维护性与运行时性能。
按需加载：仅在需要时加载 Runtime 组件，避免不必要的资源开销。
清理无效数据：运行时主动清理无用数据（如 runtime.store），避免内存占用过高。

2️⃣ 存储（Store）优化

设计合理存储策略：根据业务设计存储结构，避免大粒度数据，尤其在多用户场景。
使用缓存 / 分片：用缓存、分片等方式减少频繁读写与计算开销。

3️⃣ 工具（Tool）优化

工具职责单一：每个工具只负责一个具体功能，保持职责清晰、逻辑简单。
减少计算 / 请求：工具内部减少重复计算、外部请求，提升执行效率。

4️⃣ 中间件（Middleware）优化

合理使用中间件：避免滥用中间件，过多中间件会增加执行链路、降低性能。
异步化与缓存：中间件逻辑尽量异步、可缓存，缩短整体执行时间。

核心总结

通过精简上下文、优化存储、工具拆分、精简中间件，实现 更低资源占用 + 更快执行速度 + 更高可维护性。

Jean's Blog

LangChain Runtime运行时环境