上下文¶

代理通常需要的不仅仅是一组消息列表，才能有效运作。它们需要**上下文**。

上下文包括*任何*消息列表之外的数据，这些数据可以影响代理行为或工具执行。这可能包括：

运行时传递的信息，如 user_id 或 API 凭据。
多步骤推理过程中更新的内部状态。
来自先前交互的持久化记忆或事实。

LangGraph 提供了三种主要方式来提供上下文：

类型	描述	可变性？	生命周期
Config	在运行开始时传递的数据	❌	每次运行
State	可在执行期间更改的动态数据	✅	每次运行或对话
Long-term Memory (Store)	可在对话之间共享的数据	✅	跨对话

你可以使用上下文来：

调整模型看到的系统提示
向工具提供必要的输入
在进行中的对话中跟踪事实

提供运行时上下文¶

在需要在运行时向代理注入数据时使用此方法。

配置（静态上下文）¶

配置用于不可变的数据，如用户元数据或 API 密钥。当您有在运行过程中不会改变的值时使用它。

使用一个名为 "configurable" 的键来指定配置，该键专为此目的保留：

agent.invoke(
    {"messages": [{"role": "user", "content": "hi!"}]},
    config={"configurable": {"user_id": "user_123"}}
)

状态（可变上下文）¶

状态在运行期间作为短期记忆。它保存可以在执行过程中演变的动态数据，例如从工具或 LLM 输出中派生的值。

class CustomState(AgentState):
    user_name: str

agent = create_react_agent(
    # 其他代理参数...
    state_schema=CustomState,
)

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

启用记忆

有关如何启用记忆的更多详细信息，请参阅记忆指南。这是一个强大的功能，允许您在多次调用之间持久化代理的状态。否则，状态仅限于单个代理运行的范围。

长期记忆（跨会话上下文）¶

对于跨越多个对话或会话的上下文，LangGraph 允许通过 store 访问 长期记忆。这可以用于读取或更新持久化的事实（例如用户档案、偏好、先前交互）。更多信息请参见记忆指南。

使用上下文自定义提示¶

提示定义了代理的行为。为了包含运行时上下文，你可以根据代理的状态或配置动态生成提示。

常见用例：

个性化
角色或目标自定义
条件行为（例如用户是管理员）

使用配置使用状态

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

def prompt(
    state: AgentState,
    config: RunnableConfig,
) -> list[AnyMessage]:
    user_name = config["configurable"].get("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=[get_weather],
    prompt=prompt
)

agent.invoke(
    ...,
    config={"configurable": {"user_name": "John Smith"}}
)

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):
    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,
    prompt=prompt
)

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

在工具中访问上下文¶

工具可以通过特殊参数注解访问上下文。

使用 RunnableConfig 进行配置访问
使用 Annotated[StateSchema, InjectedState] 用于代理状态

Tip

这些注解可以防止 LLM 尝试填充值。这些参数将对 LLM 隐藏。

使用配置使用状态

def get_user_info(
    config: RunnableConfig,
) -> str:
    """查找用户信息."""
    user_id = config["configurable"].get("user_id")
    return "用户是 John Smith" if user_id == "user_123" else "未知用户"

agent = create_react_agent(
    model="anthropic:claude-3-7-sonnet-latest",
    tools=[get_user_info],
)

agent.invoke(
    {"messages": [{"role": "user", "content": "查找用户信息"}]},
    config={"configurable": {"user_id": "user_123"}}
)

from typing import Annotated
from langgraph.prebuilt import InjectedState

class CustomState(AgentState):
    user_id: str

def get_user_info(
    state: Annotated[CustomState, InjectedState]
) -> str:
    """查找用户信息."""
    user_id = state["user_id"]
    return "用户是 John Smith" if user_id == "user_123" else "未知用户"

agent = create_react_agent(
    model="anthropic:claude-3-7-sonnet-latest",
    tools=[get_user_info],
    state_schema=CustomState,
)

agent.invoke({
    "messages": "查找用户信息",
    "user_id": "user_123"
})

从工具更新上下文¶

工具可以在执行过程中更新代理的上下文（状态和长期记忆）。这对于持久化中间结果或使信息对后续工具或提示可用非常有用。有关更多信息，请参阅 Memory 指南。