上下文概述

上下文工程是指构建动态系统的实践，这些系统以正确的格式提供正确的信息和工具，使AI应用能够完成任务。上下文可以从两个关键维度来理解：

根据可变性：
- 静态上下文：在执行过程中不会改变的不可变数据（例如，用户元数据、数据库连接、工具）。
- 动态上下文：随着应用运行而演变的可变数据（例如，对话历史、中间结果、工具调用观察）。
根据生命周期：
- 运行时上下文：作用域为单次运行或调用的数据。
- 跨会话上下文：在多个对话或会话中持久存在的数据。

运行时上下文指的是本地上下文：你的代码运行所需的数据和依赖项。它不是指：

LLM 上下文，即传递给 LLM 提示词中的数据。
“上下文窗口”，即可以传递给 LLM 的最大 token 数量。

运行时上下文是一种依赖注入形式，可用于优化 LLM 上下文。它允许你在运行时向你的工具和节点提供依赖项（如数据库连接、用户 ID 或 API 客户端），而不是将它们硬编码。例如，你可以在运行时上下文中使用用户元数据来获取用户偏好，并将其馈送到上下文窗口中。

LangGraph 提供了三种管理上下文的方式，它结合了可变性和生命周期维度：

上下文类型	描述	可变性	生命周期	访问方式
静态运行时上下文	启动时传递的用户元数据、工具、数据库连接	静态	单次运行	`invoke`/`stream` 的 `context` 参数
动态运行时上下文（状态）	单次运行中演变的可变数据	动态	单次运行	LangGraph 状态对象
动态跨会话上下文（存储）	跨对话共享的持久化数据	动态	跨会话	LangGraph 存储

静态运行时上下文

静态运行时上下文代表不可变数据，如用户元数据、工具和数据库连接，这些数据在运行开始时通过 invoke/stream 的 context 参数传递给应用程序。这些数据在执行过程中不会改变。

@dataclass
class ContextSchema:
    user_name: str

graph.invoke(
    {"messages": [{"role": "user", "content": "hi!"}]},
    context={"user_name": "John Smith"}
)

智能体提示词
工作流节点
在工具中

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


@dataclass
class ContextSchema:
    user_name: str

@dynamic_prompt
def personalized_prompt(request: ModelRequest) -> str:
    user_name = request.runtime.context.user_name
    return f"You are a helpful assistant. Address the user as {user_name}."

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[get_weather],
    middleware=[personalized_prompt],
    context_schema=ContextSchema
)

agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]},
    context=ContextSchema(user_name="John Smith")
)

详见智能体文档。

from langgraph.runtime import Runtime

def node(state: State, runtime: Runtime[ContextSchema]):
    user_name = runtime.context.user_name
    ...

详见图 API。

from langchain.tools import tool, ToolRuntime

@tool
def get_user_email(runtime: ToolRuntime[ContextSchema]) -> str:
    """根据用户 ID 检索用户信息。"""
    # 模拟从数据库获取用户信息
    email = get_user_email_from_db(runtime.context.user_name)
    return email

详见工具调用指南。

Runtime 对象可用于访问静态上下文以及其他实用程序，如活动存储和流写入器。详见 Runtime 文档。

动态运行时上下文

动态运行时上下文代表可变数据，这些数据可以在单次运行中演变，并通过 LangGraph 状态对象进行管理。这包括对话历史、中间结果以及从工具或 LLM 输出中派生的值。在 LangGraph 中，状态对象在运行期间充当短期记忆。

在智能体中
在工作流中

示例展示了如何将状态融入智能体的提示词中。状态也可以被智能体的工具访问，这些工具可以根据需要读取或更新状态。详见工具调用指南。

from langchain.agents import create_agent
from langchain.agents.middleware import dynamic_prompt, ModelRequest
from langchain.agents import AgentState


class CustomState(AgentState):
    user_name: str

@dynamic_prompt
def personalized_prompt(request: ModelRequest) -> str:
    user_name = request.state.get("user_name", "User")
    return f"You are a helpful assistant. User's name is {user_name}"

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[...],
    state_schema=CustomState,
    middleware=[personalized_prompt],
)

agent.invoke({
    "messages": "hi!",
    "user_name": "John Smith"
})

from typing_extensions import TypedDict
from langchain.messages import AnyMessage
from langgraph.graph import StateGraph

class CustomState(TypedDict):
    messages: list[AnyMessage]
    extra_field: int

def node(state: CustomState):
    messages = state["messages"]
    ...
    return {
        "extra_field": state["extra_field"] + 1
    }

builder = StateGraph(State)
builder.add_node(node)
builder.set_entry_point("node")
graph = builder.compile()

开启记忆功能 关于如何启用记忆功能，请参阅记忆指南。这是一个强大的功能，允许你在多次调用之间持久化智能体的状态。否则，状态的作用域仅限于单次运行。

动态跨会话上下文

动态跨会话上下文代表跨多个对话或会话存在的持久化、可变数据，并通过 LangGraph 存储进行管理。这包括用户资料、偏好和历史交互。LangGraph 存储在多次运行之间充当长期记忆。这可用于读取或更新持久化事实（例如，用户资料、偏好、先前交互）。

了解更多

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Tutorials

Conceptual overviews

Additional resources

静态运行时上下文

动态运行时上下文

动态跨会话上下文

了解更多

​静态运行时上下文

​动态运行时上下文

​动态跨会话上下文

​了解更多

静态运行时上下文

动态运行时上下文

动态跨会话上下文

了解更多