上下文工程总览 (Context overview)
深入解析上下文工程（Context Engineering）的核心维度：在正确的时间、以正确的结构为智能体提供最精准的信息与工具。
上下文工程（Context engineering）是一门系统化构建动态机制的工程实践：它确保系统在正确的时间、以正确的格式为 AI 应用注入最精准的信息和工具，从而支撑智能体高效、可靠地完成任务。上下文可以通过两个核心维度进行解构：
- 按可变性 (Mutability) 划分：
- 静态上下文 (Static context)：在执行过程中保持不可变的客观数据（例如用户元数据、数据库连接池、系统预设工具列表）。
- 动态上下文 (Dynamic context)：伴随应用程序运行而持续演进的可变数据（例如对话历史流水、中间计算结果、工具调用观测事实）。
- 按生命周期 (Lifetime) 划分：
- 运行时上下文 (Runtime context)：仅作用于单次运行（Run）或调用的局部数据。
- 跨会话上下文 (Cross-conversation context)：在多轮对话、独立会话或多线程之间持久保留的数据。
区分运行时上下文与 LLM 上下文窗口
这里的“运行时上下文（Runtime context）”指代代码执行所需的本地环境、依赖项与注入参数。它不同于：
- 注入到大模型 Prompt 里的直接输入内容；
- 大模型受到物理限制的最大 Token 上下文窗口（Context window）。
运行时上下文是将外部环境数据串联进智能体的核心桥梁。与其将连接或会话滥用全局变量维护，不如将它们（如数据库客户端、租户 ID、用户配置）挂载到上下文中并在工具和中间件中取用，从而保持系统的无状态、高可测试性与模块复用性。
LangGraph 结合可变性与生命周期两大维度，提供了三种治理上下文的标准方式：
| 上下文类型 | 核心描述 | 可变性 | 生命周期 |
|---|---|---|---|
| 配置项 (Config) | 在单次运行启动时传入的不可变参数 | 静态 (Static) | 单次运行 (Single run) |
| 动态运行时上下文 (State) | 在单次运行中随流程演进的可变数据 | 动态 (Dynamic) | 单次运行 (Single run) |
| 跨会话动态存储 (Store) | 跨越多个独立会话全局共享的持久化数据 | 动态 (Dynamic) | 跨会话持久 (Cross-conversation) |
配置项 (Config)
Config 专门用于承载静态不可变数据（例如外部 API 密钥、租户标识、用户元数据），适合在运行期间绝不会中途变更的参数。
通过保留关键字 configurable 传入自定义配置：
await graph.invoke(
{ messages: [{ role: "user", content: "hi!" }] },
{ configurable: { user_id: "user_123" } }
);动态运行时上下文 (State)
动态运行时上下文表示在单次运行过程中持续演进的可变数据，通过 LangGraph 的 State 状态对象进行统一管理。这包括对话历史流水、中间推理步骤以及工具调用或 LLM 生成的临时数据。在单次运行期间，状态对象充当短期记忆 (Short-term memory)。
在智能体中使用 (In an agent)
通过中间件（Middleware）将自定义状态动态融入智能体的系统提示词中：
import { createAgent, createMiddleware } from "langchain";
import * as z from "zod";
const CustomState = z.object({
userName: z.string(),
});
const personalizedPrompt = createMiddleware({
name: "PersonalizedPrompt",
stateSchema: CustomState,
wrapModelCall: (request, handler) => {
const userName = request.state.userName || "User";
const systemPrompt = `You are a helpful assistant. User's name is ${userName}`;
return handler({ ...request, systemPrompt });
},
});
const agent = createAgent({
model: "claude-sonnet-4-6",
tools: [/* 业务工具 */],
middleware: [personalizedPrompt] as const,
});
await agent.invoke({
messages: [{ role: "user", content: "hi!" }],
userName: "John Smith",
});在工作流图中使用 (In a workflow)
在基于状态机的工作流中，各个节点接收全局状态并返回增量状态变更：
import { z } from "zod/v4";
import { StateGraph, StateSchema, MessagesValue, START } from "@langchain/langgraph";
const CustomState = new StateSchema({
messages: MessagesValue,
extraField: z.number(),
});
const builder = new StateGraph(CustomState)
.addNode("node", async (state) => {
return {
extraField: state.extraField + 1,
};
})
.addEdge(START, "node");
const graph = builder.compile();跨会话动态存储 (Store)
跨会话动态上下文表示能够跨越不同对话线程或用户会话长期保留的持久化可变数据，由 LangGraph 的 BaseStore 引擎管理。这包括用户个人画像、历史偏好设置以及领域沉淀事实，承担长期记忆 (Long-term memory)的核心职责。