智能体中的上下文工程

概述

构建智能体（或任何 LLM 应用）的难点在于使其足够可靠。虽然它们可能适用于原型，但在真实用例中常常失败。

为什么智能体会失败？

当智能体失败时，通常是因为智能体内部的 LLM 调用采取了错误的行动 / 没有达到我们的预期。LLM 失败有两个原因：

底层 LLM 能力不足
“正确”的上下文没有传递给 LLM

很多时候，实际上是第二个原因导致了智能体不可靠。 上下文工程 是以正确的格式提供正确的信息和工具，以便 LLM 能够完成任务。这是 AI 工程师的首要工作。这种“正确”上下文的缺乏是阻碍构建更可靠智能体的首要因素，而 LangChain 的智能体抽象体在设计上专门用于促进上下文工程。

刚接触上下文工程？请从概念概述开始，了解不同类型的上下文及其适用场景。

智能体循环

典型的智能体循环包含两个主要步骤：

模型调用 - 使用提示词和可用工具调用 LLM，返回响应或执行工具的请求
工具执行 - 执行 LLM 请求的工具，返回工具结果

这个循环会持续进行，直到 LLM 决定完成任务。

可控环节

要构建可靠的智能体，你需要控制智能体循环中每一步发生的事情，以及步骤之间发生的事情。

上下文类型	可控内容	瞬时或持久
模型上下文	模型调用的内容（指令、消息历史、工具、响应格式）	瞬时
工具上下文	工具可访问和生成的内容（对状态、存储、运行时上下文的读/写）	持久
生命周期上下文	模型和工具调用之间发生的事情（摘要、防护栏、日志记录等）	持久

瞬时上下文

LLM 在单次调用中看到的内容。你可以修改消息、工具或提示，而不会改变保存在状态中的内容。

持久上下文

跨轮次保存在状态中的内容。生命周期钩子和工具写入会永久修改此内容。

数据源

在整个过程中，你的智能体会访问（读取/写入）不同的数据源：

数据源	别称	作用域	示例
运行时上下文	静态配置	会话作用域	用户 ID、API 密钥、数据库连接、权限、环境设置
状态	短期记忆	会话作用域	当前消息、上传的文件、认证状态、工具结果
存储	长期记忆	跨会话	用户偏好、提取的见解、记忆、历史数据

工作原理

LangChain 中间件是底层机制，使上下文工程对使用 LangChain 的开发者来说变得实用。中间件允许你挂接到智能体生命周期中的任何步骤，并：

更新上下文
跳转到智能体生命周期中的不同步骤

在本指南中，你会看到频繁使用中间件 API 来实现上下文工程的目标。

模型上下文

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

系统提示

开发者向 LLM 提供的基础指令。

消息

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

工具

智能体可用于执行操作的实用程序。

模型

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

响应格式

模型最终响应的模式规范。

所有这些类型的模型上下文都可以来源于状态（短期记忆）、存储（长期记忆）或 运行时上下文（静态配置）。

系统提示

系统提示设定 LLM 的行为和能力。不同的用户、上下文或对话阶段需要不同的指令。成功的智能体会利用记忆、偏好和配置来为当前对话状态提供正确的指令。

状态
存储
运行时上下文

从状态中访问消息计数或对话上下文：

import { createAgent } from "langchain";

const agent = createAgent({
  model: "gpt-5.5",
  tools: [...],
  middleware: [
    dynamicSystemPromptMiddleware((state) => {
      // 从状态中读取：检查对话长度
      const messageCount = state.messages.length;

      let base = "You are a helpful assistant.";

      if (messageCount > 10) {
        base += "\nThis is a long conversation - be extra concise.";
      }

      return base;
    }),
  ],
});

从长期记忆中访问用户偏好：

import * as z from "zod";
import { createAgent, dynamicSystemPromptMiddleware } from "langchain";

const contextSchema = z.object({
  userId: z.string(),
});

type Context = z.infer<typeof contextSchema>;

const agent = createAgent({
  model: "gpt-5.5",
  tools: [...],
  contextSchema,
  middleware: [
    dynamicSystemPromptMiddleware<Context>(async (state, runtime) => {
      const userId = runtime.context.userId;

      // 从存储中读取：获取用户偏好
      const store = runtime.store;
      const userPrefs = await store.get(["preferences"], userId);

      let base = "You are a helpful assistant.";

      if (userPrefs) {
        const style = userPrefs.value?.communicationStyle || "balanced";
        base += `\nUser prefers ${style} responses.`;
      }

      return base;
    }),
  ],
});

从运行时上下文中访问用户 ID 或配置：

import * as z from "zod";
import { createAgent, dynamicSystemPromptMiddleware } from "langchain";

const contextSchema = z.object({
  userRole: z.string(),
  deploymentEnv: z.string(),
});

type Context = z.infer<typeof contextSchema>;

const agent = createAgent({
  model: "gpt-5.5",
  tools: [...],
  contextSchema,
  middleware: [
    dynamicSystemPromptMiddleware<Context>((state, runtime) => {
      // 从运行时上下文中读取：用户角色和环境
      const userRole = runtime.context.userRole;
      const env = runtime.context.deploymentEnv;

      let base = "You are a helpful assistant.";

      if (userRole === "admin") {
        base += "\nYou have admin access. You can perform all operations.";
      } else if (userRole === "viewer") {
        base += "\nYou have read-only access. Guide users to read operations only.";
      }

      if (env === "production") {
        base += "\nBe extra careful with any data modifications.";
      }

      return base;
    }),
  ],
});

消息

消息构成了发送给 LLM 的提示。管理消息的内容至关重要，以确保 LLM 拥有正确的信息来做出良好响应。

状态
存储
运行时上下文

当与当前查询相关时，从状态注入上传文件的上下文：

import { createMiddleware } from "langchain";

const injectFileContext = createMiddleware({
  name: "InjectFileContext",
  wrapModelCall: (request, handler) => {
    // request.state 是 request.state.messages 的快捷方式
    const uploadedFiles = request.state.uploadedFiles || [];

    if (uploadedFiles.length > 0) {
      // 构建关于可用文件的上下文
      const fileDescriptions = uploadedFiles.map(file =>
        `- ${file.name} (${file.type}): ${file.summary}`
      );

      const fileContext = `Files you have access to in this conversation:
${fileDescriptions.join("\n")}

Reference these files when answering questions.`;

      // 在最近消息之前注入文件上下文
      const messages = [  
        ...request.messages,  // 对话的其余部分
        { role: "user", content: fileContext }
      ];
      request = request.override({ messages });
    }

    return handler(request);
  },
});

const agent = createAgent({
  model: "gpt-5.5",
  tools: [...],
  middleware: [injectFileContext],
});

从存储注入用户的电子邮件写作风格以指导起草：

import * as z from "zod";
import { createMiddleware } from "langchain";

const contextSchema = z.object({
  userId: z.string(),
});

const injectWritingStyle = createMiddleware({
  name: "InjectWritingStyle",
  contextSchema,
  wrapModelCall: async (request, handler) => {
    const userId = request.runtime.context.userId;

    // 从存储中读取：获取用户的写作风格示例
    const store = request.runtime.store;
    const writingStyle = await store.get(["writing_style"], userId);

    if (writingStyle) {
      const style = writingStyle.value;
      // 从存储的示例构建风格指南
      const styleContext = `Your writing style:
- Tone: ${style.tone || 'professional'}
- Typical greeting: "${style.greeting || 'Hi'}"
- Typical sign-off: "${style.signOff || 'Best'}"
- Example email you've written:
${style.exampleEmail || ''}`;

      // 附加在末尾 - 模型更关注最后的消息
      const messages = [
        ...request.messages,
        { role: "user", content: styleContext }
      ];
      request = request.override({ messages });
    }

    return handler(request);
  },
});

根据用户的管辖权从运行时上下文注入合规规则：

import * as z from "zod";
import { createMiddleware } from "langchain";

const contextSchema = z.object({
  userJurisdiction: z.string(),
  industry: z.string(),
  complianceFrameworks: z.array(z.string()),
});

type Context = z.infer<typeof contextSchema>;

const injectComplianceRules = createMiddleware<Context>({
  name: "InjectComplianceRules",
  contextSchema,
  wrapModelCall: (request, handler) => {
    // 从运行时上下文中读取：获取合规要求
    const { userJurisdiction, industry, complianceFrameworks } = request.runtime.context;

    // 构建合规约束
    const rules = [];
    if (complianceFrameworks.includes("GDPR")) {
      rules.push("- Must obtain explicit consent before processing personal data");
      rules.push("- Users have right to data deletion");
    }
    if (complianceFrameworks.includes("HIPAA")) {
      rules.push("- Cannot share patient health information without authorization");
      rules.push("- Must use secure, encrypted communication");
    }
    if (industry === "finance") {
      rules.push("- Cannot provide financial advice without proper disclaimers");
    }

    if (rules.length > 0) {
      const complianceContext = `Compliance requirements for ${userJurisdiction}:
${rules.join("\n")}`;

      // 附加在末尾 - 模型更关注最后的消息
      const messages = [
        ...request.messages,
        { role: "user", content: complianceContext }
      ];
      request = request.override({ messages });
    }

    return handler(request);
  },
});

瞬时与持久消息更新：上面的示例使用 wrap_model_call 进行瞬时更新 - 修改单次调用发送给模型的消息，而不改变保存在状态中的内容。对于会修改状态的持久更新，你可以：

直接从 wrapModelCall 返回一个 Command，以从模型调用层注入状态更新。
使用生命周期钩子，如 beforeModel、afterModel 或 wrapToolCall（用于工具返回）来更新对话历史。更多详情请参阅中间件文档。

更多信息请参阅状态更新。

工具

工具使模型能够与数据库、API 和外部系统交互。定义和选择工具的方式直接影响模型能否有效完成任务。

定义工具

每个工具都需要一个清晰的名称、描述、参数名称和参数描述。这些不仅仅是元数据 - 它们引导模型推理何时以及如何使用该工具。

import { tool } from "@langchain/core/tools";
import { z } from "zod";

const searchOrders = tool(
  async ({ userId, status, limit }) => {
    // 此处为实现代码
  },
  {
    name: "search_orders",
    description: `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.`,
    schema: z.object({
      userId: z.string().describe("Unique identifier for the user"),
      status: z.enum(["pending", "shipped", "delivered"]).describe("Order status to filter by"),
      limit: z.number().default(10).describe("Maximum number of results to return"),
    }),
  }
);

选择工具

并非每个工具都适用于所有情况。工具过多可能会压垮模型（上下文过载）并增加错误；工具过少则会限制能力。动态工具选择会根据认证状态、用户权限、功能标志或对话阶段来调整可用工具集。

状态
存储
运行时上下文

仅在某些对话里程碑后启用高级工具：

import { createMiddleware } from "langchain";

const stateBasedTools = createMiddleware({
  name: "StateBasedTools",
  wrapModelCall: (request, handler) => {
    // 从状态中读取：检查认证和对话长度
    const state = request.state;
    const isAuthenticated = state.authenticated || false;
    const messageCount = state.messages.length;

    let filteredTools = request.tools;

    // 仅在认证后启用敏感工具
    if (!isAuthenticated) {
      filteredTools = request.tools.filter(t => t.name.startsWith("public_"));
    } else if (messageCount < 5) {
      filteredTools = request.tools.filter(t => t.name !== "advanced_search");
    }

    return handler({ ...request, tools: filteredTools });
  },
});

根据存储中的用户偏好或功能标志过滤工具：

import * as z from "zod";
import { createMiddleware } from "langchain";

const contextSchema = z.object({
  userId: z.string(),
});

const storeBasedTools = createMiddleware({
  name: "StoreBasedTools",
  contextSchema,
  wrapModelCall: async (request, handler) => {
    const userId = request.runtime.context.userId;

    // 从存储中读取：获取用户的启用功能
    const store = request.runtime.store;
    const featureFlags = await store.get(["features"], userId);

    let filteredTools = request.tools;

    if (featureFlags) {
      const enabledFeatures = featureFlags.value?.enabledTools || [];
      filteredTools = request.tools.filter(t => enabledFeatures.includes(t.name));
    }

    return handler({ ...request, tools: filteredTools });
  },
});

根据运行时上下文中的用户权限过滤工具：

import * as z from "zod";
import { createMiddleware } from "langchain";

const contextSchema = z.object({
  userRole: z.string(),
});

const contextBasedTools = createMiddleware({
  name: "ContextBasedTools",
  contextSchema,
  wrapModelCall: (request, handler) => {
    // 从运行时上下文中读取：获取用户角色
    const userRole = request.runtime.context.userRole;

    let filteredTools = request.tools;

    if (userRole === "admin") {
      // 管理员获得所有工具
    } else if (userRole === "editor") {
      filteredTools = request.tools.filter(t => t.name !== "delete_data");
    } else {
      filteredTools = request.tools.filter(t => t.name.startsWith("read_"));
    }

    return handler({ ...request, tools: filteredTools });
  },
});

关于过滤预注册工具和在运行时注册工具（例如，从 MCP 服务器）的更多信息，请参阅动态工具。

模型

不同的模型有不同的优势、成本和上下文窗口。为手头的任务选择合适的模型，这可能在智能体运行过程中发生变化。

状态
存储
运行时上下文

根据状态中的对话长度使用不同的模型：

import { createMiddleware, initChatModel } from "langchain";

// 在中间件外部初始化模型一次
const largeModel = initChatModel("claude-sonnet-4-6");
const standardModel = initChatModel("gpt-5.5");
const efficientModel = initChatModel("gpt-5.4-mini");

const stateBasedModel = createMiddleware({
  name: "StateBasedModel",
  wrapModelCall: (request, handler) => {
    // request.messages 是 request.state.messages 的快捷方式
    const messageCount = request.messages.length;
    let model;

    if (messageCount > 20) {
      model = largeModel;
    } else if (messageCount > 10) {
      model = standardModel;
    } else {
      model = efficientModel;
    }

    return handler({ ...request, model });
  },
});

使用存储中用户偏好的模型：

import * as z from "zod";
import { createMiddleware, initChatModel } from "langchain";

const contextSchema = z.object({
  userId: z.string(),
});

// 初始化可用模型一次
const MODEL_MAP = {
  "gpt-5.5": initChatModel("gpt-5.5"),
  "gpt-5.4-mini": initChatModel("gpt-5.4-mini"),
  "claude-sonnet": initChatModel("claude-sonnet-4-6"),
};

const storeBasedModel = createMiddleware({
  name: "StoreBasedModel",
  contextSchema,
  wrapModelCall: async (request, handler) => {
    const userId = request.runtime.context.userId;

    // 从存储中读取：获取用户偏好的模型
    const store = request.runtime.store;
    const userPrefs = await store.get(["preferences"], userId);

    let model = request.model;

    if (userPrefs) {
      const preferredModel = userPrefs.value?.preferredModel;
      if (preferredModel && MODEL_MAP[preferredModel]) {
        model = MODEL_MAP[preferredModel];
      }
    }

    return handler({ ...request, model });
  },
});

根据成本限制或环境从运行时上下文中选择模型：

import * as z from "zod";
import { createMiddleware, initChatModel } from "langchain";

const contextSchema = z.object({
  costTier: z.string(),
  environment: z.string(),
});

// 在中间件外部初始化模型一次
const premiumModel = initChatModel("claude-sonnet-4-6");
const standardModel = initChatModel("gpt-5.5");
const budgetModel = initChatModel("gpt-5.4-mini");

const contextBasedModel = createMiddleware({
  name: "ContextBasedModel",
  contextSchema,
  wrapModelCall: (request, handler) => {
    // 从运行时上下文中读取：成本层级和环境
    const costTier = request.runtime.context.costTier;
    const environment = request.runtime.context.environment;

    let model;

    if (environment === "production" && costTier === "premium") {
      model = premiumModel;
    } else if (costTier === "budget") {
      model = budgetModel;
    } else {
      model = standardModel;
    }

    return handler({ ...request, model });
  },
});

更多示例请参阅动态模型。

响应格式

结构化输出将非结构化文本转换为经过验证的结构化数据。当需要提取特定字段或为下游系统返回数据时，自由格式的文本是不够的。 工作原理： 当你提供一个模式作为响应格式时，模型的最终响应将保证符合该模式。智能体运行模型/工具调用循环，直到模型完成工具调用，然后最终响应被强制转换为提供的格式。

定义格式

模式定义引导模型。字段名称、类型和描述精确指定了输出应遵循的格式。

import { z } from "zod";

const customerSupportTicket = z.object({
  category: z.enum(["billing", "technical", "account", "product"]).describe(
    "Issue category"
  ),
  priority: z.enum(["low", "medium", "high", "critical"]).describe(
    "Urgency level"
  ),
  summary: z.string().describe(
    "One-sentence summary of the customer's issue"
  ),
  customerSentiment: z.enum(["frustrated", "neutral", "satisfied"]).describe(
    "Customer's emotional tone"
  ),
}).describe("Structured ticket information extracted from customer message");

选择格式

动态响应格式选择会根据用户偏好、对话阶段或角色来调整模式 - 在早期返回简单格式，随着复杂性增加而返回详细格式。

状态
存储
运行时上下文

根据对话状态配置结构化输出：

import { createMiddleware } from "langchain";
import { z } from "zod";

const simpleResponse = z.object({
  answer: z.string().describe("A brief answer"),
});

const detailedResponse = z.object({
  answer: z.string().describe("A detailed answer"),
  reasoning: z.string().describe("Explanation of reasoning"),
  confidence: z.number().describe("Confidence score 0-1"),
});

const stateBasedOutput = createMiddleware({
  name: "StateBasedOutput",
  wrapModelCall: (request, handler) => {
    // request.state 是 request.state.messages 的快捷方式
    const messageCount = request.messages.length;

    let responseFormat;
    if (messageCount < 3) {
      // 对话初期 - 使用简单格式
      responseFormat = simpleResponse;
    } else {
      // 对话深入后 - 使用详细格式
      responseFormat = detailedResponse;
    }

    return handler({ ...request, responseFormat });
  },
});

根据存储中的用户偏好配置输出格式：

import * as z from "zod";
import { createMiddleware } from "langchain";

const contextSchema = z.object({
  userId: z.string(),
});

const verboseResponse = z.object({
  answer: z.string().describe("详细答案"),
  sources: z.array(z.string()).describe("使用的来源"),
});

const conciseResponse = z.object({
  answer: z.string().describe("简要答案"),
});

const storeBasedOutput = createMiddleware({
  name: "StoreBasedOutput",
  wrapModelCall: async (request, handler) => {
    const userId = request.runtime.context.userId;

    // 从 Store 读取：获取用户偏好的响应样式
    const store = request.runtime.store;
    const userPrefs = await store.get(["preferences"], userId);

    const style = userPrefs?.value?.responseStyle || "concise";
    const responseFormat =
      style === "verbose" ? verboseResponse : conciseResponse;

    return handler({
      ...request,
      responseFormat,
    });
  },
});

根据运行时上下文（如用户角色或环境）配置输出格式：

import * as z from "zod";
import { createMiddleware } from "langchain";

const contextSchema = z.object({
  userRole: z.string(),
  environment: z.string(),
});

const adminResponse = z.object({
  answer: z.string().describe("答案"),
  debugInfo: z.record(z.any()).describe("调试信息"),
  systemStatus: z.string().describe("系统状态"),
});

const userResponse = z.object({
  answer: z.string().describe("答案"),
});

const contextBasedOutput = createMiddleware({
  name: "ContextBasedOutput",
  wrapModelCall: (request, handler) => {
    // 从运行时上下文读取：用户角色和环境
    const userRole = request.runtime.context.userRole;
    const environment = request.runtime.context.environment;

    let responseFormat;
    if (userRole === "admin" && environment === "production") {
      responseFormat = adminResponse;
    } else {
      responseFormat = userResponse;
    }

    return handler({ ...request, responseFormat });
  },
});

工具上下文

工具的特殊之处在于它们既能读取也能写入上下文。在最基本的情况下，当工具执行时，它接收 LLM 的请求参数并向模型返回一个工具消息。工具完成其工作并产生一个结果。工具还可以为模型获取重要信息，使其能够执行并完成任务。

读取

大多数现实世界的工具不仅仅需要 LLM 的参数。它们需要用于数据库查询的用户 ID、用于外部服务的 API 密钥，或当前会话状态以做出决策。工具从状态、存储和运行时上下文中读取以访问这些信息。

状态
存储
运行时上下文

从 State 读取以检查当前会话信息：

import * as z from "zod";
import { createAgent, tool, type ToolRuntime } from "langchain";

const checkAuthentication = tool(
  async (_, runtime: ToolRuntime) => {
    // 从 State 读取：检查当前认证状态
    const currentState = runtime.state;
    const isAuthenticated = currentState.authenticated || false;

    if (isAuthenticated) {
      return "User is authenticated";
    } else {
      return "User is not authenticated";
    }
  },
  {
    name: "check_authentication",
    description: "检查用户是否已认证",
    schema: z.object({}),
  }
);

从 Store 读取以访问持久化的用户偏好：

import * as z from "zod";
import { createAgent, tool, type ToolRuntime } from "langchain";

const contextSchema = z.object({
  userId: z.string(),
});

const getPreference = tool(
  async ({ preferenceKey }, runtime: ToolRuntime) => {
    const userId = runtime.context.userId;

    // 从 Store 读取：获取现有偏好
    const store = runtime.store;
    const existingPrefs = await store.get(["preferences"], userId);

    if (existingPrefs) {
      const value = existingPrefs.value?.[preferenceKey];
      return value ? `${preferenceKey}: ${value}` : `No preference set for ${preferenceKey}`;
    } else {
      return "No preferences found";
    }
  },
  {
    name: "get_preference",
    description: "从 Store 获取用户偏好",
    schema: z.object({
      preferenceKey: z.string(),
    }),
  }
);

从运行时上下文读取 API 密钥和用户 ID 等配置：

import * as z from "zod";
import { tool } from "@langchain/core/tools";
import { createAgent } from "langchain";

const contextSchema = z.object({
  userId: z.string(),
  apiKey: z.string(),
  dbConnection: z.string(),
});

const fetchUserData = tool(
  async ({ query }, runtime: ToolRuntime<any, typeof contextSchema>) => {
    // 从运行时上下文读取：获取 API 密钥和数据库连接
    const { userId, apiKey, dbConnection } = runtime.context;

    // 使用配置获取数据
    const results = await performDatabaseQuery(dbConnection, query, apiKey);

    return `Found ${results.length} results for user ${userId}`;
  },
  {
    name: "fetch_user_data",
    description: "使用运行时上下文配置获取数据",
    schema: z.object({
      query: z.string(),
    }),
  }
);

const agent = createAgent({
  model: "gpt-5.5",
  tools: [fetchUserData],
  contextSchema,
});

写入

工具结果可用于帮助智能体完成给定的任务。工具既可以将结果直接返回给模型，也可以更新智能体的记忆，以使重要上下文可用于后续步骤。

状态
存储

使用 Command 将数据写入 State 以跟踪会话特定信息：

import * as z from "zod";
import { tool } from "@langchain/core/tools";
import { createAgent } from "langchain";
import { Command } from "@langchain/langgraph";

const authenticateUser = tool(
  async ({ password }) => {
    // 执行认证
    if (password === "correct") {
      // 写入 State：使用 Command 标记为已认证
      return new Command({
        update: { authenticated: true },
      });
    } else {
      return new Command({ update: { authenticated: false } });
    }
  },
  {
    name: "authenticate_user",
    description: "认证用户并更新 State",
    schema: z.object({
      password: z.string(),
    }),
  }
);

将数据写入 Store 以在会话间持久化：

import * as z from "zod";
import { createAgent, tool, type ToolRuntime } from "langchain";

const savePreference = tool(
  async ({ preferenceKey, preferenceValue }, runtime: ToolRuntime<any, typeof contextSchema>) => {
    const userId = runtime.context.userId;

    // 读取现有偏好
    const store = runtime.store;
    const existingPrefs = await store.get(["preferences"], userId);

    // 与新偏好合并
    const prefs = existingPrefs?.value || {};
    prefs[preferenceKey] = preferenceValue;

    // 写入 Store：保存更新的偏好
    await store.put(["preferences"], userId, prefs);

    return `Saved preference: ${preferenceKey} = ${preferenceValue}`;
  },
  {
    name: "save_preference",
    description: "将用户偏好保存到 Store",
    schema: z.object({
      preferenceKey: z.string(),
      preferenceValue: z.string(),
    }),
  }
);

有关在工具中访问状态、存储和运行时上下文的完整示例，请参阅工具。

生命周期上下文

控制在核心智能体步骤之间发生的事情——拦截数据流以实现横切关注点，如摘要、护栏和日志记录。正如你在模型上下文和[工具上下文](#工具上下文中所见，中间件是使上下文工程实用的机制。中间件允许你钩入智能体生命周期的任何步骤，并可以：

更新上下文 - 修改状态和存储以持久化更改、更新对话历史或保存见解
跳转生命周期 - 根据上下文移动到智能体循环中的不同步骤（例如，如果满足条件则跳过工具执行，使用修改后的上下文重复模型调用）

示例：摘要

最常见的生命周期模式之一是在对话历史过长时自动进行压缩。与模型上下文中显示的瞬时消息修剪不同，摘要会持久化更新状态 - 用为所有未来轮次保存的摘要永久替换旧消息。 LangChain 为此提供了内置中间件：

import { createAgent, summarizationMiddleware } from "langchain";

const agent = createAgent({
  model: "gpt-5.5",
  tools: [...],
  middleware: [
    summarizationMiddleware({
      model: "gpt-5.4-mini",
      trigger: { tokens: 4000 },
      keep: { messages: 20 },
    }),
  ],
});

当对话超过令牌限制时，SummarizationMiddleware 会自动：

使用单独的 LLM 调用对较旧的消息进行摘要
在 State 中用摘要消息替换它们（永久地）
保留最近的消息以维持上下文

摘要后的对话历史是永久更新的 - 未来的轮次将看到摘要而不是原始消息。

有关内置中间件、可用钩子以及如何创建自定义中间件的完整列表，请参阅中间件文档。

最佳实践

从简单开始 - 从静态提示和工具开始，仅在需要时添加动态内容
增量测试 - 一次添加一个上下文工程特性
监控性能 - 跟踪模型调用、令牌使用情况和延迟
使用内置中间件 - 利用 SummarizationMiddleware、LLMToolSelectorMiddleware 等。
记录你的上下文策略 - 清楚地说明传递了哪些上下文以及原因
理解瞬时与持久：模型上下文的更改是瞬时的（每次调用），而生命周期上下文的更改会持久化到状态

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

概述

为什么智能体会失败？

智能体循环

可控环节

瞬时上下文

持久上下文

数据源

工作原理

模型上下文

系统提示

消息

工具

模型

响应格式

系统提示

消息

工具

定义工具

选择工具

模型

响应格式

定义格式

选择格式

工具上下文

读取

写入

生命周期上下文

示例：摘要

最佳实践

相关资源

​概述

​为什么智能体会失败？

​智能体循环

​可控环节

瞬时上下文

持久上下文

​数据源

​工作原理

​模型上下文

系统提示

消息

工具

模型

响应格式

​系统提示

​消息

​工具

​定义工具

​选择工具

​模型

​响应格式

​定义格式

​选择格式

​工具上下文

​读取

​写入

​生命周期上下文

​示例：摘要

​最佳实践

​相关资源

概述

为什么智能体会失败？

智能体循环

可控环节

数据源

工作原理

模型上下文

系统提示

消息

工具

定义工具

选择工具

模型

响应格式

定义格式

选择格式

工具上下文

读取

写入

生命周期上下文

示例：摘要

最佳实践

相关资源