Skip to main content

​
概述

构建代理（或任何 LLM 应用程序）的难点在于使其足够可靠。虽然它们可能适用于原型，但在实际使用场景中往往会失败。

​
为什么代理会失败？

代理失败通常是因为代理中的 LLM 调用了错误的操作/未按预期执行。LLM 失败的原因有两个：
  1. 底层 LLM 不够强大
  2. 未向 LLM 提供“正确”的上下文
更多时候，实际上是第二个原因导致代理不够可靠。 上下文工程 是以正确的格式提供正确的信息和工具，使 LLM 能够完成任务。这是 AI 工程师的主要任务。这种缺乏“正确”上下文是更可靠代理的主要障碍，而 LangChain 的代理抽象设计独特，旨在促进上下文工程。
上下文工程新手？从概念概述开始，了解不同类型的上下文及其使用场景。

​
代理循环

一个典型的代理循环包括两个主要步骤：
  1. 模型调用 - 使用提示和可用工具调用 LLM，返回响应或执行工具的请求
  2. 工具执行 - 执行 LLM 请求的工具，返回工具结果
核心代理循环图
此循环持续进行，直到 LLM 决定完成。

​
您可以控制的内容

要构建可靠的代理，您需要控制代理循环每个步骤中发生的事情，以及步骤之间发生的事情。
上下文类型您可以控制的内容瞬态或持久
模型上下文模型调用中包含的内容（指令、消息历史、工具、响应格式）瞬态
工具上下文工具可以访问和生成的内容（读取/写入状态、存储、运行时上下文）持久
生命周期上下文模型和工具调用之间发生的事情（摘要、护栏、日志记录等）持久

瞬态上下文

代理单次调用中 LLM 看到的内容。您可以通过修改消息、工具或提示来改变内容，而不会改变状态。

持久上下文

跨回合保存的内容。生命周期钩子和工具写入会永久修改此内容。

​
数据源

在整个过程中，您的代理会访问不同的数据源：
数据源也称为范围示例
运行时上下文静态配置对话范围用户 ID、API 密钥、数据库连接、权限、环境设置
状态短期记忆对话范围当前消息、上传的文件、认证状态、工具结果
存储长期记忆跨对话用户偏好、提取的洞察、记忆、历史数据

​
如何工作

LangChain middleware 是在幕后使上下文工程对开发者使用 LangChain 实用的机制。 Middleware 允许您钩入代理生命周期中的任何步骤，并：
  • 更新上下文
  • 跳到代理生命周期中的不同步骤
在整个指南中，您会频繁看到 middleware API 的使用，作为实现上下文工程目标的手段。

​
模型上下文

控制每个模型调用中包含的内容 - 指令、可用工具、使用哪个模型、输出格式。这些决策直接影响可靠性和成本。

系统提示

开发者对 LLM 的基础指令。

消息

发送到 LLM 的完整消息列表（对话历史）。

工具

代理可以访问的工具。

模型

实际调用的模型（包括配置）。

响应格式

模型最终响应的 Schema 规范。
所有这些类型的模型上下文都可以从 状态（短期记忆）、存储（长期记忆）或 运行时上下文（静态配置）中获取。

​
系统提示

系统提示设置 LLM 的行为和能力。不同用户、上下文或对话阶段需要不同的指令。成功的代理会利用记忆、偏好和配置，为当前对话状态提供正确的指令。
从状态访问消息数量或对话上下文：
from langchain.agents import create_agent
from langchain.agents.middleware import dynamic_prompt, ModelRequest

@dynamic_prompt
def state_aware_prompt(request: ModelRequest) -> str:
    # request.messages is a shortcut for request.state["messages"]
    message_count = len(request.messages)

    base = "You are a helpful assistant."

    if message_count > 10:
        base += "\nThis is a long conversation - be extra concise."

    return base

agent = create_agent(
    model="gpt-4.1",
    tools=[...],
    middleware=[state_aware_prompt]
)

​
消息

消息构成了发送到 LLM 的提示。 管理消息内容至关重要，以确保 LLM 有正确的信息来做出良好响应。
从状态注入上传文件上下文，当与当前查询相关时：
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse
from typing import Callable

@wrap_model_call
def inject_file_context(
    request: ModelRequest,
    handler: Callable[[ModelRequest], ModelResponse]
) -> ModelResponse:
    """Inject context about files user has uploaded this session."""
    # Read from State: get uploaded files metadata
    uploaded_files = request.state.get("uploaded_files", [])

    if uploaded_files:
        # Build context about available files
        file_descriptions = []
        for file in uploaded_files:
            file_descriptions.append(
                f"- {file['name']} ({file['type']}): {file['summary']}"
            )

        file_context = f"""Files you have access to in this conversation:

{chr(10).join(file_descriptions)}

Reference these files when answering questions."""

        # Inject file context before recent messages
        messages = [
            *request.messages,
            {"role": "user", "content": file_context},
        ]
        request = request.override(messages=messages)

    return handler(request)

agent = create_agent(
    model="gpt-4.1",
    tools=[...],
    middleware=[inject_file_context]
)
瞬态 vs 持久消息更新：上面的例子使用 wrap_model_call 做 瞬态 更新 - 修改单次调用发送给模型的消息，而不改变状态。对于 持久 更新，如 生命周期上下文 中的摘要例子，使用生命周期钩子如 before_model 或 after_model 来永久更新对话历史。参见 middleware 文档 获取更多细节。

​
工具

工具让模型与数据库、API 和外部系统交互。如何定义和选择工具直接影响模型是否能有效完成任务。

​
定义工具

每个工具需要一个清晰的名称、描述、参数名和参数描述。这些不仅仅是元数据——它们指导模型的推理，关于何时和如何使用工具。 
from langchain.tools import tool

@tool(parse_docstring=True)
def search_orders(
    user_id: str,
    status: str,
    limit: int = 10
) -> str:
    """Search for user orders by status.

    Use this when the user asks about order history or wants to check
    order status. Always filter by the provided status.

    Args:
        user_id: Unique identifier for the user
        status: Order status: 'pending', 'shipped', or 'delivered'
        limit: Maximum number of results to return
    """
    # Implementation here
    pass

​
选择工具

并非每个工具都适合每个情况。太多工具可能会让模型过载（上下文过载）并增加错误；太少则限制能力。动态工具选择根据认证状态、用户权限、功能标志或对话阶段适配可用工具集。
在达到一定对话里程碑后才启用高级工具：
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse
from typing import Callable

@wrap_model_call
def state_based_tools(
    request: ModelRequest,
    handler: Callable[[ModelRequest], ModelResponse]
) -> ModelResponse:
    """Filter tools based on conversation State."""
    # Read from State: check if user has authenticated
    state = request.state  
    is_authenticated = state.get("authenticated", False)
    message_count = len(state["messages"])

    # Only enable sensitive tools after authentication
    if not is_authenticated:
        tools = [t for t in request.tools if t.name.startswith("public_")]
        request = request.override(tools=tools)
    elif message_count < 5:
        # Limit tools early in conversation
        tools = [t for t in request.tools if t.name != "advanced_search"]
        request = request.override(tools=tools)

    return handler(request)

agent = create_agent(
    model="gpt-4.1",
    tools=[public_search, private_search, advanced_search],
    middleware=[state_based_tools]
)
See Dynamic tools for both filtering pre-registered tools and registering tools at runtime (e.g., from MCP servers).

​
模型

不同的模型有不同的优势、成本和上下文窗口。选择适合任务的模型，可能会在代理运行期间发生变化。
基于对话长度使用不同的模型：
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse
from langchain.chat_models import init_chat_model
from typing import Callable

# Initialize models once outside the middleware
large_model = init_chat_model("claude-sonnet-4-6")
standard_model = init_chat_model("gpt-4.1")
efficient_model = init_chat_model("gpt-4.1-mini")

@wrap_model_call
def state_based_model(
    request: ModelRequest,
    handler: Callable[[ModelRequest], ModelResponse]
) -> ModelResponse:
    """Select model based on State conversation length."""
    # request.messages is a shortcut for request.state["messages"]
    message_count = len(request.messages)

    if message_count > 20:
        # Long conversation - use model with larger context window
        model = large_model
    elif message_count > 10:
        # Medium conversation
        model = standard_model
    else:
        # Short conversation - use efficient model
        model = efficient_model

    request = request.override(model=model)

    return handler(request)

agent = create_agent(
    model="gpt-4.1-mini",
    tools=[...],
    middleware=[state_based_model]
)
See Dynamic model for more examples.

​
响应格式

结构化输出将非结构化文本转换为验证的、结构化的数据。当提取特定字段或返回数据给下游系统时，自由文本不足以满足需求。 如何工作： 当您提供一个 schema 作为响应格式时，模型的最终响应将保证符合该 schema。代理运行模型/工具调用循环，直到模型完成工具调用，然后最终响应被强制转换为提供的格式。

​
定义格式

Schema 定义指导模型。字段名、类型和描述指定了输出应遵循的确切格式。 
from pydantic import BaseModel, Field

class CustomerSupportTicket(BaseModel):
    """Structured ticket information extracted from customer message."""

    category: str = Field(
        description="Issue category: 'billing', 'technical', 'account', or 'product'"
    )
    priority: str = Field(
        description="Urgency level: 'low', 'medium', 'high', or 'critical'"
    )
    summary: str = Field(
        description="One-sentence summary of the customer's issue"
    )
    customer_sentiment: str = Field(
        description="Customer's emotional tone: 'frustrated', 'neutral', or 'satisfied'"
    )

​
选择格式

动态响应格式选择根据用户偏好、对话阶段或角色调整 schema——在复杂性增加时返回详细格式。
根据对话状态配置结构化输出：
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse
from pydantic import BaseModel, Field
from typing import Callable

class SimpleResponse(BaseModel):
    """Simple response for early conversation."""
    answer: str = Field(description="A brief answer")

class DetailedResponse(BaseModel):
    """Detailed response for established conversation."""
    answer: str = Field(description="A detailed answer")
    reasoning: str = Field(description="Explanation of reasoning")
    confidence: float = Field(description="Confidence score 0-1")

@wrap_model_call
def state_based_output(
    request: ModelRequest,
    handler: Callable[[ModelRequest], ModelResponse]
) -> ModelResponse:
    """Select output format based on State."""
    # request.messages is a shortcut for request.state["messages"]
    message_count = len(request.messages)

    if message_count < 3:
        # Early conversation - use simple format
        request = request.override(response_format=SimpleResponse)
    else:
        # Established conversation - use detailed format
        request = request.override(response_format=DetailedResponse)

    return handler(request)

agent = create_agent(
    model="gpt-4.1",
    tools=[...],
    middleware=[state_based_output]
)

​
工具上下文

工具是特殊的，因为它们既读又写上下文。 在最简单的情况下，当工具执行时，它接收 LLM 的请求参数并返回工具消息。工具完成工作并产生结果。 工具也可以获取对模型有用的重要信息，使模型能够完成任务。

​
读取

大多数现实世界的工具需要的不仅仅是 LLM 的参数。它们需要用户 ID 进行数据库查询，API 密钥用于外部服务，或当前会话状态来做出决策。工具从状态、存储和运行时上下文读取信息。
从状态读取当前会话信息：
from langchain.tools import tool, ToolRuntime
from langchain.agents import create_agent

@tool
def check_authentication(
    runtime: ToolRuntime
) -> str:
    """Check if user is authenticated."""
    # Read from State: check current auth status
    current_state = runtime.state
    is_authenticated = current_state.get("authenticated", False)

    if is_authenticated:
        return "User is authenticated"
    else:
        return "User is not authenticated"

agent = create_agent(
    model="gpt-4.1",
    tools=[check_authentication]
)

​
写入

工具结果可以用于帮助代理完成给定任务。工具既可以将结果直接返回给模型，也可以更新代理的内存，使重要上下文在未来的步骤中可用。
写入 State 以使用 Command 跟踪会话特定信息：
from langchain.tools import tool, ToolRuntime
from langchain.agents import create_agent
from langgraph.types import Command

@tool
def authenticate_user(
    password: str,
    runtime: ToolRuntime
) -> Command:
    """Authenticate user and update State."""
    # Perform authentication (simplified)
    if password == "correct":
        # Write to State: mark as authenticated using Command
        return Command(
            update={"authenticated": True},
        )
    else:
        return Command(update={"authenticated": False})

agent = create_agent(
    model="gpt-4.1",
    tools=[authenticate_user]
)
See Tools for comprehensive examples of accessing state, store, and runtime context in tools.

​
生命周期上下文

控制核心代理步骤之间发生的事情 - 截获数据流以实现跨切割关注点，如摘要、护栏和日志记录。 正如您在 模型上下文 和 工具上下文 中看到的，middleware 是使上下文工程实用的机制。Middleware 允许您钩入代理生命周期中的任何步骤，并且可以：
  1. 更新上下文 - 修改状态和存储以持久化更改，更新对话历史或保存洞察
  2. 跳入生命周期 - 基于上下文跳到代理生命周期中的不同步骤（例如，如果条件满足则跳过工具执行，重复模型调用以修改上下文）
Middleware hooks in the agent loop

​
示例：摘要

最常见的生命周期模式之一是自动压缩过长的对话历史。与 模型上下文 中显示的瞬态消息修剪不同，摘要 持久地更新状态 - 永远地用摘要替换旧消息，保存给所有未来的回合。 LangChain 提供了内置的 middleware： 
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=[...],
    middleware=[
        SummarizationMiddleware(
            model="gpt-4.1-mini",
            trigger={"tokens": 4000},
            keep={"messages": 20},
        ),
    ],
)
当对话超过 token 限制时，SummarizationMiddleware 自动：
  1. 使用单独的 LLM 调用总结较早的消息
  2. 用摘要消息替换 State 中的旧消息（永久）
  3. 保持最近的消息完整以供上下文
总结后的对话历史是永久更新的 - 未来的回合将看到摘要而不是原始消息。
对于完整的内置 middleware 列表、可用钩子和如何创建自定义 middleware，参见 Middleware 文档。

​
最佳实践

  1. 开始简单 - 从静态提示和工具开始，需要时再添加动态
  2. 逐步测试 - 逐步添加上下文工程功能
  3. 监控性能 - 跟踪模型调用、token 使用和延迟
  4. 使用内置 middleware - 利用 SummarizationMiddleware, LLMToolSelectorMiddleware, 等
  5. 记录您的上下文策略 - 明确说明传递的上下文及其原因
  6. 理解瞬态 vs 持久：模型上下文变化是瞬态（每调用），而生命周期上下文变化是持久的

​
相关资源

Edit this page on GitHub or file an issue.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.