AI Agent 的有效上下文工程
原文链接: www.anthropic.com/engineering…
发布日期: 2025年9月29日
上下文是 AI Agent 的关键但有限的资源。在这篇文章中，我们将探讨有效策划和管理为 Agent 提供动力的上下文的策略。
在应用 AI 领域，提示词工程（prompt engineering）作为关注焦点已经持续了几年，而现在一个新术语开始崭露头角：上下文工程（context engineering）。使用语言模型进行开发已不再仅仅是为你的提示词寻找合适的措辞和短语，而更多地是回答一个更宏观的问题："什么样的上下文配置最有可能生成我们模型期望的行为？"
上下文（Context） 指的是在从大型语言模型（LLM）采样时包含的 token 集合。工程（Engineering） 问题则是在 LLM 固有约束下优化这些 token 的效用，以便持续实现预期结果。有效地驾驭 LLM 通常需要 在上下文中思考 ——换句话说：考虑 LLM 在任何给定时刻可用的整体状态，以及该状态可能产生的潜在行为。
在这篇文章中，我们将探索上下文工程这门新兴艺术，并为构建可控、有效的 Agent 提供一个精炼的思维模型。
上下文工程 vs 提示词工程
在 Anthropic，我们将上下文工程视为提示词工程的自然演进。提示词工程指的是编写和组织 LLM 指令以获得最佳结果的方法（参见我们的文档了解概述和有用的提示词工程策略）。上下文工程 指的是在 LLM 推理过程中策划和维护最优 token 集合（信息）的策略集，包括所有可能出现在其中的其他信息（不仅仅是提示词）。
在使用 LLM 进行工程开发的早期，提示是 AI 工程工作中最大的组成部分，因为除了日常聊天交互之外，大多数用例都需要针对一次性分类或文本生成任务优化的提示词。顾名思义，提示词工程的主要关注点是如何编写有效的提示词，特别是系统提示词。然而，随着我们转向构建能够在多轮推理和更长时间跨度上运行的更强大 Agent，我们需要管理整个上下文状态的策略（系统指令、工具、Model Context Protocol（MCP）、外部数据、消息历史等）。
在循环中运行的 Agent 会生成越来越多的数据，这些数据 可能 与下一轮推理相关，而这些信息必须被循环地精炼。上下文工程是从这个不断演变的可能信息宇宙中策划进入有限上下文窗口内容的艺术与科学。
与编写提示词这一离散任务相比，上下文工程是迭代的，每次我们决定传递什么内容给模型时都会发生策划阶段。
💡 提示词工程 vs 上下文工程对比
| 维度 | 提示词工程 | 上下文工程 |
|---|---|---|
| 关注点 | 如何编写有效的提示词 | 如何策划和维护最优 token 集合 |
| 范围 | 系统提示词、用户提示词 | 系统指令、工具、MCP、外部数据、消息历史等 |
| 时机 | 一次性优化 | 每轮推理都需要策划 |
| 目标 | 一次性分类或文本生成 | 多轮推理、长时间跨度任务 |
| 性质 | 离散任务 | 迭代过程 |
为什么上下文工程对构建强大 Agent 至关重要
尽管 LLM 速度快且能够管理越来越大量的数据，但我们观察到 LLM 与人类一样，在某个点上会失去焦点或感到困惑。关于 needle-in-a-haystack 风格基准测试的研究揭示了上下文腐化（context rot）的概念：随着上下文窗口中 token 数量的增加，模型从该上下文中准确召回信息的能力会下降。
虽然某些模型表现出比其他模型更温和的退化，但这一特性在所有模型中都会出现。因此，上下文必须被视为一种具有边际收益递减的有限资源。就像人类具有有限的工作记忆容量一样，LLM 在解析大量上下文时也有一个"注意力预算"可供使用。引入的每个新 token 都会在一定程度上消耗这个预算，从而增加了仔细策划 LLM 可用 token 的需求。
这种注意力稀缺性源于 LLM 的架构约束。LLM 基于 transformer 架构，该架构使每个 token 都能关注整个上下文中的每个其他 token。这导致 n 个 token 产生 n² 个成对关系。
随着上下文长度的增加，模型捕获这些成对关系的能力会被稀释，在上下文大小和注意力焦点之间产生自然的张力。此外，模型从训练数据分布中发展其注意力模式，而较短的序列通常比较长的序列更常见。这意味着模型对上下文范围的依赖性经验较少，专门用于这些依赖性的参数也较少。
位置编码插值等技术允许模型通过将其适配到最初训练的较小上下文来处理更长的序列，尽管 token 位置理解会有一些退化。这些因素创造的是性能梯度而非硬性悬崖：模型在较长上下文中仍然非常强大，但与在较短上下文中的表现相比，信息检索和长距离推理的精度可能会有所降低。
这些现实意味着深思熟虑的上下文工程对于构建强大的 Agent 至关重要。
💡 上下文长度与模型性能关系
graph LR
A[上下文长度增加] --> B[n² 成对关系增加]
B --> C[注意力被稀释]
C --> D[性能梯度下降]
E[训练数据特性] --> F[短序列更常见]
F --> G[长序列参数较少]
G --> D
D --> H[信息检索精度降低]
D --> I[长距离推理能力下降]
有效上下文的解剖结构
鉴于 LLM 受到有限注意力预算的约束，好的 上下文工程意味着找到能最大化某个预期结果可能性的 最小可能 高信号 token 集合。实践这一原则说起来容易做起来难，但在以下部分，我们概述了这一指导原则在上下文不同组成部分中的实际含义。
系统提示词
系统提示词 应该极其清晰，使用简单、直接的语言，以 正确的高度 向 Agent 呈现想法。正确的高度是两种常见失败模式之间的"金发姑娘区间"。在一个极端，我们看到工程师在他们的提示词中硬编码复杂、脆弱的逻辑来引出精确的 Agent 行为。这种方法会造成脆弱性，并随时间增加维护复杂性。在另一个极端，工程师有时会提供模糊的、高级别的指导，未能给 LLM 提供期望输出的具体信号，或者错误地假设共享上下文。最佳高度达成平衡：足够具体以有效指导行为，但又足够灵活以为模型提供强有力的启发式规则来指导行为。
在光谱的一端，我们看到脆弱的 if-else 硬编码提示词，而在另一端，我们看到过于笼统或错误假设共享上下文的提示词。
💡 系统提示词"高度"光谱
graph TD
subgraph 过于具体
A1[硬编码 if-else 逻辑]
A2[脆弱性高]
A3[维护复杂]
end
subgraph 最佳高度
B1[足够具体指导行为]
B2[足够灵活提供启发式]
B3[平衡的抽象级别]
end
subgraph 过于笼统
C1[模糊的高级指导]
C2[缺乏具体信号]
C3[错误假设共享上下文]
end
A1 --> B1
B1 --> C1
我们建议将提示词组织成不同的部分（如 <background_information>、<instructions>、## Tool guidance、## Output description 等），并使用 XML 标签或 Markdown 标题等技术来划分这些部分，尽管提示词的确切格式可能随着模型变得更强大而变得不那么重要。
无论你决定如何构建系统提示词，你都应该努力获得完整概述预期行为的最小信息集。（请注意，最小不一定意味着简短；你仍然需要预先给 Agent 足够的信息以确保它遵守期望的行为。）最好从使用最佳可用模型测试最小提示词开始，看看它在你的任务上的表现，然后根据初始测试中发现的失败模式添加清晰的指令和示例来提高性能。
工具
工具 允许 Agent 与其环境交互并在工作时引入新的、额外的上下文。因为工具定义了 Agent 与其信息/行动空间之间的契约，所以工具促进效率极其重要，无论是通过返回 token 高效的信息还是通过鼓励高效的 Agent 行为。
在为 AI Agent 编写工具——与 AI Agent 一起一文中，我们讨论了构建被 LLM 良好理解且功能重叠最小的工具。类似于设计良好的代码库中的函数，工具应该是自包含的、对错误健壮的，并且在其预期用途方面极其清晰。输入参数同样应该是描述性的、明确的，并发挥模型的固有优势。
我们看到的最常见失败模式之一是臃肿的工具集，涵盖太多功能或导致使用哪个工具的决策点模糊。如果人类工程师都不能明确说出在给定情况下应该使用哪个工具，那么 AI Agent 也不能被期望做得更好。正如我们稍后将讨论的，为 Agent 策划一个最小可行的工具集也可以在长期交互中带来更可靠的上下文维护和修剪。
💡 工具设计最佳实践
| 原则 | 描述 | 反模式 |
|---|---|---|
| 自包含 | 工具功能独立完整 | 工具间存在复杂依赖 |
| 错误健壮 | 优雅处理各种错误情况 | 错误时静默失败或崩溃 |
| 用途清晰 | 明确的功能边界和描述 | 功能模糊或过于宽泛 |
| 参数明确 | 描述性强、无歧义的输入 | 参数名称含糊不清 |
| 最小重叠 | 工具间功能不重复 | 多个工具可完成同一任务 |
| Token 高效 | 返回精简、必要的信息 | 返回大量冗余数据 |
示例
提供示例，也称为少样本提示（few-shot prompting），是一个众所周知的最佳实践，我们继续强烈建议使用。然而，团队通常会在提示词中塞入一长串边缘案例，试图阐明 LLM 在特定任务中应遵循的每一条可能规则。我们不推荐这样做。相反，我们建议努力策划一组有效描绘 Agent 预期行为的多样化、规范性示例。对于 LLM 来说，示例就是价值千言的"图片"。
我们在上下文不同组成部分（系统提示词、工具、示例、消息历史等）的总体指导是要深思熟虑，保持上下文信息丰富但紧凑。现在让我们深入探讨在运行时动态检索上下文。
上下文检索和 Agent 式搜索
在构建有效的 AI Agent一文中，我们强调了基于 LLM 的工作流和 Agent 之间的区别。自从我们写了那篇文章以来，我们倾向于一个简单的定义来描述 Agent：LLM 在循环中自主使用工具。
与我们的客户合作，我们看到这个领域正在向这种简单范式汇聚。随着底层模型变得更强大，Agent 的自主程度可以扩展：更智能的模型允许 Agent 独立导航复杂的问题空间并从错误中恢复。
我们现在看到工程师思考如何为 Agent 设计上下文的方式正在发生转变。今天，许多 AI 原生应用采用某种形式的基于嵌入的预推理时间检索，以呈现重要的上下文供 Agent 推理。随着该领域过渡到更多 Agent 式方法，我们越来越多地看到团队用"即时"上下文策略来增强这些检索系统。
即时上下文策略
与预先处理所有相关数据不同，采用"即时"方法构建的 Agent 维护轻量级标识符（文件路径、存储的查询、网络链接等），并使用这些引用通过工具在运行时动态加载数据到上下文中。Anthropic 的 Agent 式编程解决方案 Claude Code 使用这种方法对大型数据库执行复杂的数据分析。模型可以编写有针对性的查询、存储结果，并利用 Bash 命令如 head 和 tail 来分析大量数据，而无需将完整数据对象加载到上下文中。这种方法反映了人类认知：我们通常不会记忆整个信息语料库，而是引入外部组织和索引系统（如文件系统、收件箱和书签）来按需检索相关信息。
💡 上下文检索策略对比
| 策略 | 预处理检索 | 即时检索 |
|---|---|---|
| 时机 | 推理前 | 运行时 |
| 数据处理 | 预先加载所有相关数据 | 维护轻量级标识符，按需加载 |
| 优势 | 检索速度快 | 上下文精简、灵活性高 |
| 劣势 | 可能加载无关数据 | 探索耗时 |
| 适用场景 | 静态内容（法律、金融） | 动态环境（代码库、文件系统） |
| 代表产品 | 传统 RAG 系统 | Claude Code |
元数据的价值
除了存储效率之外，这些引用的元数据提供了一种有效精炼行为的机制，无论是显式提供还是直觉性的。对于在文件系统中操作的 Agent 来说，tests 文件夹中名为 test_utils.py 的文件暗示着与位于 src/core_logic/ 中同名文件不同的用途。文件夹层次结构、命名约定和时间戳都提供重要信号，帮助人类和 Agent 理解如何以及何时利用信息。
渐进式披露
让 Agent 自主导航和检索数据还能实现渐进式披露——换句话说，允许 Agent 通过探索逐步发现相关上下文。每次交互都会产生为下一个决策提供信息的上下文：文件大小暗示复杂性；命名约定暗示用途；时间戳可以作为相关性的代理。Agent 可以逐层组装理解，仅在工作记忆中保留必要的内容，并利用笔记策略进行额外的持久化。这种自管理的上下文窗口使 Agent 专注于相关子集，而不是淹没在详尽但可能无关的信息中。
当然，这有一个权衡：运行时探索比检索预计算数据慢。不仅如此，还需要有见解的、深思熟虑的工程来确保 LLM 拥有有效导航其信息景观的正确工具和启发式方法。如果没有适当的指导，Agent 可能会通过误用工具、追逐死胡同或未能识别关键信息来浪费上下文。
混合策略
在某些环境中，最有效的 Agent 可能采用混合策略，预先检索一些数据以提高速度，并根据其判断进一步进行自主探索。"正确"自主程度的决策边界取决于任务。Claude Code 是采用这种混合模型的 Agent：CLAUDE.md 文件被直接放入上下文中，而 glob 和 grep 等原语允许它导航其环境并即时检索文件，有效地绕过陈旧索引和复杂语法树的问题。
混合策略可能更适合内容较少动态变化的环境，如法律或金融工作。随着模型能力的提高，Agent 式设计将趋向于让智能模型智能地行动，人工策划逐渐减少。鉴于该领域的快速发展，"做最简单有效的事情"可能仍将是我们对在 Claude 上构建 Agent 的团队的最佳建议。
💡 上下文检索策略决策流程
graph TD
A[开始：选择上下文策略] --> B{内容是否动态变化？}
B -->|是| C{是否需要快速响应？}
B -->|否| D[预处理检索策略]
C -->|是| E[混合策略]
C -->|否| F[即时检索策略]
E --> G[预加载关键配置文件<br>如 CLAUDE.md]
E --> H[提供导航工具<br>如 glob, grep]
F --> I[维护轻量级标识符]
F --> J[运行时动态加载]
D --> K[基于嵌入的检索]
D --> L[预先加载相关数据]
长周期任务的上下文工程
长周期任务要求 Agent 在 token 计数超过 LLM 上下文窗口的行动序列中保持一致性、上下文和目标导向行为。对于跨越数十分钟到数小时连续工作的任务，如大型代码库迁移或综合研究项目，Agent 需要专门的技术来解决上下文窗口大小限制。
等待更大的上下文窗口可能看起来是一个显而易见的策略。但可能在可预见的未来，所有大小的上下文窗口都将受到上下文污染和信息相关性问题的影响——至少在需要最强 Agent 性能的情况下是如此。为了使 Agent 能够在延长的时间跨度内有效工作，我们开发了几种直接解决这些上下文污染约束的技术：压缩（compaction）、结构化笔记（structured note-taking） 和 多 Agent 架构（multi-agent architectures）。
💡 长周期任务上下文管理技术
graph TD
Root((长周期任务<br>上下文管理))
Root --> A[压缩 Compaction]
Root --> B[结构化笔记]
Root --> C[多 Agent 架构]
A --> A1[总结对话内容]
A --> A2[保留关键决策]
A --> A3[清除冗余工具输出]
B --> B1[持久化笔记到外部存储]
B --> B2[跟踪任务进度]
B --> B3[维护待办清单]
C --> C1[主 Agent 协调]
C --> C2[子 Agent 专注任务]
C --> C3[返回精简摘要]
压缩（Compaction）
压缩是指在对话接近上下文窗口限制时，总结其内容并用摘要重新启动新的上下文窗口的做法。压缩通常是上下文工程中推动更好长期一致性的第一个杠杆。其核心是以高保真方式提炼上下文窗口的内容，使 Agent 能够以最小的性能退化继续工作。
例如，在 Claude Code 中，我们通过将消息历史传递给模型来总结和压缩最关键的细节来实现这一点。模型保留架构决策、未解决的 bug 和实现细节，同时丢弃冗余的工具输出或消息。然后 Agent 可以使用这个压缩后的上下文加上最近访问的五个文件继续工作。用户获得了连续性而无需担心上下文窗口限制。
压缩的艺术在于选择保留什么与丢弃什么，因为过于激进的压缩可能导致丢失微妙但关键的上下文，而这些上下文的重要性可能只有在后来才变得明显。对于实现压缩系统的工程师，我们建议在复杂的 Agent 轨迹上仔细调整你的提示词。首先最大化召回率以确保你的压缩提示词捕获轨迹中的每一条相关信息，然后迭代以通过消除多余内容来提高精确度。
低垂果实类型的多余内容的一个例子是清除工具调用和结果——一旦工具在消息历史深处被调用，Agent 为什么还需要再次看到原始结果？最安全、最轻量级的压缩形式之一是工具结果清除，这是最近作为 Claude 开发者平台的功能推出的。
💡 压缩策略优先级
| 优先级 | 内容类型 | 处理方式 |
|---|---|---|
| 必须保留 | 架构决策 | 完整保留 |
| 必须保留 | 未解决的 bug | 完整保留 |
| 必须保留 | 实现细节 | 完整保留 |
| 可以精简 | 工具调用参数 | 保留关键信息 |
| 可以清除 | 深层历史中的工具结果 | 清除原始输出 |
| 可以清除 | 冗余消息 | 合并或删除 |
结构化笔记（Structured Note-taking）
结构化笔记，或称 Agent 式记忆，是 Agent 定期将笔记写入上下文窗口外部持久化存储的技术。这些笔记在之后的时间被拉回上下文窗口。
这种策略以最小的开销提供持久记忆。就像 Claude Code 创建待办清单，或你的自定义 Agent 维护 NOTES.md 文件一样，这种简单的模式允许 Agent 跟踪复杂任务的进度，维护关键上下文和依赖关系，否则这些在数十次工具调用中会丢失。
Claude 玩宝可梦展示了记忆如何在非编程领域转变 Agent 能力。Agent 在数千个游戏步骤中保持精确计数——跟踪目标如"在过去的 1,234 步中，我一直在 1 号道路训练我的宝可梦，皮卡丘已经向目标 10 级提升了 8 级。"在没有关于记忆结构的任何提示的情况下，它开发了已探索区域的地图，记住解锁了哪些关键成就，并维护战斗策略的策略笔记，帮助它学习哪些攻击对不同对手效果最好。
在上下文重置后，Agent 读取自己的笔记并继续多小时的训练序列或地牢探索。这种跨总结步骤的一致性使得仅靠 LLM 上下文窗口保留所有信息时不可能实现的长周期策略成为可能。
作为 Sonnet 4.5 发布的一部分，我们在 Claude 开发者平台上以公开测试版发布了记忆工具，通过基于文件的系统使存储和查阅上下文窗口外的信息变得更容易。这允许 Agent 随时间建立知识库，跨会话维护项目状态，并引用之前的工作而无需将所有内容保留在上下文中。
子 Agent 架构（Sub-agent Architectures）
子 Agent 架构提供了另一种绕过上下文限制的方法。不是让一个 Agent 试图在整个项目中维护状态，而是让专门的子 Agent 用干净的上下文窗口处理专注的任务。主 Agent 用高级计划进行协调，而子 Agent 执行深度技术工作或使用工具查找相关信息。每个子 Agent 可能进行大量探索，使用数万个甚至更多 token，但只返回其工作的浓缩、提炼摘要（通常 1,000-2,000 个 token）。
这种方法实现了明确的关注点分离——详细的搜索上下文保持隔离在子 Agent 内部，而主 Agent 专注于综合和分析结果。这种模式在我们如何构建多 Agent 研究系统中讨论，在复杂研究任务上显示出比单 Agent 系统有实质性改进。
💡 子 Agent 架构工作流程
graph TD
A[主 Agent] --> B[高级计划协调]
B --> C[子 Agent 1<br>专注任务 A]
B --> D[子 Agent 2<br>专注任务 B]
B --> E[子 Agent 3<br>专注任务 C]
C --> F[大量探索<br>数万 token]
D --> G[大量探索<br>数万 token]
E --> H[大量探索<br>数万 token]
F --> I[精简摘要<br>1-2k token]
G --> J[精简摘要<br>1-2k token]
H --> K[精简摘要<br>1-2k token]
I --> L[主 Agent 综合分析]
J --> L
K --> L
技术选择指南
这些方法之间的选择取决于任务特征。例如：
- 压缩 为需要大量来回交流的任务保持对话流程；
- 笔记 对于具有明确里程碑的迭代开发表现出色；
- 多 Agent 架构 处理复杂的研究和分析，在并行探索带来收益的地方。
即使模型继续改进，在延长交互中保持一致性的挑战仍将是构建更有效 Agent 的核心。
💡 长周期任务技术选择
| 技术 | 最佳场景 | 优势 | 劣势 |
|---|---|---|---|
| 压缩 | 大量来回交流的任务 | 保持对话流程 | 可能丢失微妙上下文 |
| 结构化笔记 | 迭代开发、有明确里程碑 | 跨会话持久化 | 需要设计笔记结构 |
| 多 Agent 架构 | 复杂研究、并行探索 | 关注点分离、深度探索 | 架构复杂性增加 |
结论
上下文工程代表了我们使用 LLM 构建方式的根本转变。随着模型变得更强大，挑战不仅仅是制作完美的提示词——而是深思熟虑地策划每一步进入模型有限注意力预算的信息。无论你是为长周期任务实现压缩、设计 token 高效的工具，还是让 Agent 即时探索其环境，指导原则保持不变：找到能最大化预期结果可能性的最小高信号 token 集合。
我们概述的技术将随着模型的改进继续演变。我们已经看到更智能的模型需要更少的规范性工程，允许 Agent 以更大的自主性运行。但即使能力扩展，将上下文视为珍贵的有限资源仍将是构建可靠、有效 Agent 的核心。
立即在 Claude 开发者平台开始上下文工程，并通过我们的记忆和上下文管理 cookbook 获取有用的技巧和最佳实践。
致谢
由 Anthropic 应用 AI 团队撰写：Prithvi Rajasekaran、Ethan Dixon、Carly Ryan 和 Jeremy Hadfield，团队成员 Rafi Ayub、Hannah Moran、Cal Rueb 和 Connor Jennings 也有贡献。特别感谢 Molly Vorwerck、Stuart Ritchie 和 Maggie Vo 的支持。
📝 总结
核心要点
- 上下文是有限资源：LLM 有"注意力预算"，随着上下文长度增加，信息检索和长距离推理精度下降
- 从提示词工程到上下文工程：不仅要关注如何写提示词，更要关注如何策划整个上下文状态
- 系统提示词要找到"正确的高度"：既不要过于具体（脆弱），也不要过于笼统（模糊）
- 工具设计要精简高效：自包含、无歧义、最小功能重叠
- 即时上下文策略：维护轻量级标识符，按需动态加载数据
- 长周期任务三大技术：压缩、结构化笔记、多 Agent 架构
- 核心原则：找到能最大化预期结果可能性的最小高信号 token 集合
原文作者: Anthropic Applied AI 团队（Prithvi Rajasekaran、Ethan Dixon、Carly Ryan、Jeremy Hadfield）
