> ## Documentation Index
> Fetch the complete documentation index at: https://langchain.idochub.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 上下文概览

<警告>
  **Alpha 版本提示：** 本文档涵盖的是 **v1-alpha** 版本。内容尚不完整，且可能随时更改。

  如需查阅最新稳定版本，请参阅当前的 [LangGraph Python 文档](https://langchain-ai.github.io/langgraph/) 或 [LangGraph JavaScript 文档](https://langchain-ai.github.io/langgraphjs/)。
</警告>

**上下文工程** 是构建动态系统的一种实践，旨在以恰当的格式提供正确的信息和工具，从而使 AI 应用能够完成特定任务。上下文可从两个关键维度进行描述：

1. 按 **可变性**：

* **静态上下文**：在执行期间不会改变的不可变数据（例如用户元数据、数据库连接、工具）
* **动态上下文**：随应用运行而不断变化的可变数据（例如对话历史、中间结果、工具调用观察）

2. 按 **生命周期**：

* **运行时上下文**：作用域限定于单次运行或调用的数据
* **跨会话上下文**：在多个对话或会话间持续存在的数据

<Tip>
  运行时上下文指的是本地上下文：即代码运行所需的各类数据与依赖项。它**不**指代：

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

  运行时上下文可用于优化 LLM 上下文。例如，你可以使用运行时上下文中的用户元数据来获取用户偏好，并将其输入到上下文窗口中。
</Tip>

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

| 上下文类型                                                         | 描述                   | 可变性 | 生命周期 | 访问方法                             |
| ------------------------------------------------------------- | -------------------- | --- | ---- | -------------------------------- |
| [**静态运行时上下文**](#static-runtime-context)                       | 启动时传入的用户元数据、工具、数据库连接 | 静态  | 单次运行 | `invoke`/`stream` 的 `context` 参数 |
| [**动态运行时上下文（状态）**](#dynamic-runtime-context-state)            | 在单次运行期间演变的可变数据       | 动态  | 单次运行 | LangGraph 状态对象                   |
| [**动态跨会话上下文（存储）**](#dynamic-cross-conversation-context-store) | 跨多个对话共享的持久化数据        | 动态  | 跨会话  | LangGraph 存储                     |

## 静态运行时上下文

**静态运行时上下文** 表示通过 `invoke`/`stream` 方法的 `context` 参数在运行开始时传入的不可变数据，如用户元数据、工具和数据库连接。这些数据在执行过程中不会发生变化。

```python {highlight={7}} theme={null}
@dataclass
class ContextSchema:
    user_name: str

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

1. 这是代理或图的调用。`invoke` 方法使用提供的输入运行底层图。
2. 此示例使用消息作为输入，这是常见做法，但您的应用程序可能采用不同的输入结构。
3. 在此处传入运行时数据。`context` 参数允许您提供代理在执行期间可以使用的额外依赖项。

<Tabs>
  <Tab title="代理提示词">
    ```python {highlight={6,20}} theme={null}
    from langchain_core.messages import AnyMessage
    from langgraph.runtime import get_runtime
    from langgraph.prebuilt.chat_agent_executor import AgentState
    from langgraph.prebuilt import create_react_agent

    def prompt(state: AgentState) -> list[AnyMessage]:
        runtime = get_runtime(ContextSchema)
        system_msg = f"You are a helpful assistant. Address the user as {runtime.context.user_name}."
        return [{"role": "system", "content": system_msg}] + state["messages"]

    agent = create_react_agent(
        model="anthropic:claude-3-7-sonnet-latest",
        tools=[get_weather],
        prompt=prompt,
        context_schema=ContextSchema
    )

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

    * 有关详细信息，请参阅 [代理](/oss/python/langchain/agents)。
  </Tab>

  <Tab title="工作流节点">
    ```python {highlight={3}} theme={null}
    from langgraph.runtime import Runtime

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

    * 有关详细信息，请参阅 [图 API](/oss/python/langgraph/graph-api#add-runtime-configuration)。
  </Tab>

  <Tab title="在工具中">
    ```python {highlight={4}} theme={null}
    from langgraph.runtime import get_runtime

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

    有关详细信息，请参阅 [工具调用指南](/oss/python/langchain/tools#configuration)。
  </Tab>
</Tabs>

<Tip>
  `Runtime` 对象可用于访问静态上下文及其他实用工具，如活动存储和流写入器。
  详情请参阅 \[Runtime]\[langgraph.runtime.Runtime] 文档。
</Tip>

<a id="state" />

## 动态运行时上下文

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

<Tabs>
  <Tab title="在代理中">
    示例展示了如何将状态整合进代理的**提示词**中。

    状态也可由代理的**工具**访问，工具可根据需要读取或更新状态。详情请参阅 [工具调用指南](/oss/python/langchain/tools#short-term-memory)。

    ```python {highlight={6,10,19}} theme={null}
    from langchain_core.messages import AnyMessage
    from langchain_core.runnables import RunnableConfig
    from langgraph.prebuilt import create_react_agent
    from langgraph.prebuilt.chat_agent_executor import AgentState

    class CustomState(AgentState): # (1)!
        user_name: str

    def prompt(
        state: CustomState
    ) -> list[AnyMessage]:
        user_name = state["user_name"]
        system_msg = f"You are a helpful assistant. User's name is {user_name}"
        return [{"role": "system", "content": system_msg}] + state["messages"]

    agent = create_react_agent(
        model="anthropic:claude-3-7-sonnet-latest",
        tools=[...],
        state_schema=CustomState, # (2)!
        prompt=prompt
    )

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

    1. 定义一个扩展 `AgentState` 或 `MessagesState` 的自定义状态模式。
    2. 将自定义状态模式传递给代理。这样代理便可在执行期间访问并修改状态。
  </Tab>

  <Tab title="在工作流中">
    ```python {highlight={5,9,13}} theme={null}
    from typing_extensions import TypedDict
    from langchain_core.messages import AnyMessage
    from langgraph.graph import StateGraph

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

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

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

    1. 定义一个自定义状态
    2. 在任意节点或工具中访问状态
    3. 图 API 设计为尽可能方便地与状态协同工作。节点的返回值表示对状态的请求更新。
  </Tab>
</Tabs>

<Tip>
  **启用记忆功能**
  有关如何启用记忆功能的更多详细信息，请参阅 [记忆指南](/oss/python/langgraph/add-memory)。这是一个强大的功能，允许您在多次调用之间持久化代理的状态。否则，状态的作用域仅限于单次运行。
</Tip>

<a id="store" />

## 动态跨会话上下文

**动态跨会话上下文** 表示跨越多个对话或会话的持久化可变数据，通过 LangGraph 存储进行管理。这包括用户档案、偏好设置和历史交互记录。LangGraph 存储在多次运行中充当[长期记忆](/oss/python/memory#long-term-memory)。可用于读取或更新持久性事实（例如用户档案、偏好、先前交互）。

## 参见

* [记忆概念概览](/oss/python/memory)
* [LangChain 中的短期记忆](/oss/python/langchain/short-term-memory)
* [LangChain 中的长期记忆](/oss/python/langchain/long-term-memory)
* [LangGraph 中的记忆](/oss/python/langgraph/add-memory)