跳到主要内容

原文：07-effective-context-engineering-for-ai-agents.md 来源：https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents

AI Agent 的高效上下文工程

发布于 2025 年 9 月 29 日

上下文是 AI Agent 的关键资源——也是有限资源。本文探讨高效策划和管理上下文的策略。

提示词工程（Prompt Engineering）作为应用 AI 的焦点几年后，一个新术语正崛起：上下文工程（Context Engineering）。基于语言模型构建应用，越来越不是为提示词找对的措辞，而是回答更宽泛的问题——"什么样的上下文配置最可能产生我们想要的模型行为？"

上下文（Context） 指从大语言模型（LLM）采样时包含的所有 token。工程（Engineering） 问题是：在 LLM 固有约束下优化这些 token 的效用，以一致地实现所需结果。有效驾驭 LLM 通常需要"在上下文中思考"——也就是考虑 LLM 在任何给定时刻的整体可用状态，以及该状态可能产生什么行为。

上下文工程 vs. 提示词工程​

我们把上下文工程视为提示词工程的自然延伸。

  • 提示词工程：为最优结果撰写和组织 LLM 指令的方法
  • 上下文工程：在 LLM 推理过程中策划和维护最优 token 集（信息）的策略集合，包括落入提示词之外的所有其他信息

LLM 工程早期，提示词是 AI 工程工作的最大组成——大多数日常聊天交互之外的用例都是单次分类或文本生成任务，需要为此优化的提示词。重点是写有效提示词，特别是系统提示。

但当我们朝向构建跨多轮推理、更长时间维度运行的更强大 Agent 时，需要管理整个上下文状态的策略：系统指令、工具、Model Context Protocol（MCP）、外部数据、消息历史等。

Agent 在循环中运行时会生成越来越多对下一轮推理可能相关的数据——这些信息必须被周期性地精炼。上下文工程是从这个不断演化的可能信息宇宙中策划进入有限上下文窗口内容的艺术与科学。

与"写提示词"这种离散任务不同，上下文工程是迭代的——每次决定传给模型什么时，都会发生策划阶段。

为什么上下文工程对构建有能力的 Agent 至关重要​

尽管 LLM 速度快、能管理越来越大的数据量，我们观察到 LLM 和人一样会到某个点失去焦点或感到困惑。在"大海捞针"式基准测试上的研究揭示了**上下文腐烂（Context Rot）**概念：随上下文窗口中 token 数增加，模型从该上下文中准确召回信息的能力会下降。

虽然有些模型退化更平缓，但这一特性出现在所有模型上。因此，上下文必须被视为有边际收益递减的有限资源。像人有有限的工作记忆容量，LLM 也有解析大量上下文时的"注意力预算"。每个新引入的 token 在某种程度上消耗这个预算，加深仔细策划 LLM 可用 token 的需要。

这种注意力稀缺源于 LLM 的架构约束。LLM 基于 transformer 架构——每个 token 都关注其他每个 token。这导致 n² 对的成对关系（n 个 token）。

随着上下文长度增加，模型捕捉这些成对关系的能力被拉得很薄，在上下文大小与注意力焦点之间产生天然张力。此外，模型从训练数据分布发展出注意力模式——较短序列通常更常见。这意味着模型对跨上下文依赖的经验更少、专门参数更少。

技术如位置编码插值能让模型处理更长序列（适配到原训练的较小上下文），但代价是 token 位置理解的某些退化。这些因素创造的是性能梯度而非硬悬崖：模型在更长上下文上仍然高度可用，但相比短上下文时的表现，信息检索和长程推理可能精度降低。

因此，深思熟虑的上下文工程对构建有能力的 Agent 至关重要。

有效上下文的解剖​

LLM 受有限注意力预算约束，好的上下文工程意味着找到最大化所需结果可能性的最小高信号 token 集。

系统提示​

应极其清晰，使用简单直接的语言，把想法呈现在适合 Agent 的"高度"。"正确的高度"是两种常见失败模式之间的金发姑娘区域：

  • 一端：工程师在提示中硬编码复杂、脆弱的逻辑来引出确切的 Agent 行为——这种方法随时间增加维护复杂性
  • 另一端：工程师有时给出模糊的高层指导，未给 LLM 关于所需输出的具体信号，或错误地假设共享上下文
  • 最优高度的平衡：足够具体以有效引导行为，又足够灵活以提供强启发

我们建议把提示组织成不同部分（如 <background_information>、<instructions>、## Tool guidance、## Output description），并用 XML 标签或 Markdown 标题分隔。但随着模型变强，提示的精确格式可能变得不那么重要。

最小信息集即可完整勾勒期望行为——最小不一定意味着短，仍然要给 Agent 足够前置信息确保它遵守期望行为。最佳做法是先用最强可用模型测试一个最小提示，看任务上的表现，再根据初始测试发现的失败模式添加清晰指令和示例。

工具​

工具让 Agent 与环境交互、在工作时拉入新的额外上下文。因为工具定义 Agent 与其信息/动作空间之间的契约，工具必须促进效率——既返回 token 高效的信息，也鼓励高效的 Agent 行为。

工具应自包含、对错误健壮、对预期用法极其清晰。输入参数同样应描述性强、无歧义、契合模型的固有强项。

最常见失败模式之一是臃肿的工具集——覆盖太多功能或导致选哪个工具的歧义。如果一个人类工程师无法明确说该用哪个工具，AI Agent 也别指望能做得更好。为 Agent 策划最小可行工具集也带来更可靠的长交互维护和上下文修剪。

示例​

提供示例（few-shot prompting）是经典最佳实践，我们继续强烈推荐。但团队常把边缘情况的清单塞进提示，试图说清 LLM 应该遵循的每条可能规则——我们不推荐这样。

应该策划一组多样、典型的示例，有效描绘 Agent 的预期行为。对 LLM 来说，示例就是胜过千言万语的"图片"。

我们对上下文各组件（系统提示、工具、示例、消息历史等）的整体指导：深思熟虑，让上下文信息丰富又紧凑。

上下文检索与 Agent 式搜索​

Agent 的简单定义：LLM 在循环中自主使用工具。

随着底层模型变强，Agent 自治水平可以扩展：更聪明的模型让 Agent 独立导航有微妙差别的问题空间，并从错误中恢复。

我们看到工程师如何为 Agent 设计上下文的方式正在转变。今天许多 AI 原生应用采用某种基于嵌入的预推理时检索为 Agent 浮现重要上下文。随着领域转向更 Agent 式的方法，越来越多团队用 "刚好及时（just in time）" 上下文策略增强这些检索系统。

不预先处理所有相关数据，"刚好及时"方法构建的 Agent 维护轻量标识符（文件路径、存储查询、Web 链接），并用这些引用通过工具在运行时动态加载数据进上下文。Anthropic 的 Agent 编码方案 Claude Code 用这种方法对大数据库做复杂数据分析——模型可以写有针对性的查询、存储结果、利用 Bash 命令如 head 和 tail 分析大数据，而无需把完整数据对象加载进上下文。

这反映了人类认知：我们一般不记忆整个语料库，而是引入外部组织和索引系统（文件系统、收件箱、书签）按需检索相关信息。

除了存储效率，这些引用的元数据提供了高效精炼行为的机制。对 Agent 来说，tests 文件夹中名为 test_utils.py 的文件，与 src/core_logic/ 中同名文件，暗示不同用途。文件夹层级、命名约定、时间戳都提供重要信号，帮助人和 Agent 理解何时及如何使用信息。

让 Agent 自主导航和检索数据还启用渐进披露——通过探索逐步发现相关上下文。每次交互产生为下一决定提供信息的上下文：文件大小暗示复杂度，命名约定暗示用途，时间戳可作为相关性的代理。

当然有权衡：运行时探索比检索预计算数据慢。需要审慎工程确保 LLM 有正确的工具和启发法有效导航其信息环境。没有适当指导，Agent 可能误用工具、追死胡同、或未能识别关键信息浪费上下文。

某些场景中，最有效的 Agent 可能采用混合策略——前期检索一些数据求速度，再自主探索。Claude Code 就是采用混合模型的 Agent：CLAUDE.md 文件简单地预先放入上下文，而 glob 和 grep 等原语让它导航环境并刚好及时检索文件，有效绕过过时索引和复杂语法树的问题。

考虑到领域进展的快节奏，"做能 work 的最简方案" 仍是我们对在 Claude 之上构建 Agent 的团队的最佳建议。

长任务的上下文工程​

长任务要求 Agent 在 token 数超过 LLM 上下文窗口的动作序列中保持一致性、上下文和目标导向行为。对于跨数十分钟到多小时连续工作的任务（如大代码库迁移、综合研究项目），Agent 需要专门技术绕过上下文窗口大小限制。

等待更大上下文窗口看似显然的策略——但可预见的未来里，所有大小的上下文窗口都会受上下文污染和信息相关性问题影响。我们开发了几种直接处理这些约束的技术：压缩、结构化笔记、多 Agent 架构。

压缩（Compaction）​

把临近上下文窗口上限的对话总结，并用摘要重新初始化新上下文窗口。压缩通常是上下文工程中驱动更好长程一致性的第一杠杆。核心是高保真精炼上下文窗口内容，让 Agent 以最小性能退化继续。

在 Claude Code 中，我们把消息历史传给模型总结并压缩最关键细节——保留架构决策、未解决 bug、实现细节，丢弃冗余工具输出或消息。Agent 接着用压缩上下文加上最近访问的五个文件继续。

压缩的艺术在于选择保留什么 vs. 丢弃什么——过激压缩可能丢失微妙但关键的上下文（其重要性后期才显现）。建议在复杂 Agent 轨迹上仔细调整提示：先最大化召回率确保压缩提示捕获每条相关信息，再迭代提升精确度去除多余内容。

低垂果实：清除工具调用和结果——一次工具被调用后，Agent 何必再看到原始结果？这是压缩中最安全、最轻微的形式之一。

结构化笔记​

或称 Agent 式记忆（agentic memory），Agent 定期把笔记写入上下文窗口外的持久内存。这些笔记稍后被拉回上下文。

这种策略以最小开销提供持久记忆。像 Claude Code 创建待办列表、或你的自定义 Agent 维护 NOTES.md 文件——这种简单模式让 Agent 跟踪复杂任务进度，维护跨数十次工具调用否则会丢失的关键上下文和依赖。

Claude 玩 Pokémon 演示了记忆如何在非编码领域转换 Agent 能力：Agent 跨数千游戏步保持精确计数——"过去 1234 步我一直在 Route 1 训练我的 Pokémon，Pikachu 已获得 8 级，目标 10 级"。无需任何关于记忆结构的提示，它发展出已探索区域地图、记住已解锁的关键成就、维持战斗策略笔记帮助学习哪些攻击对不同对手最有效。

上下文重置后，Agent 读取自己的笔记并继续多小时的训练序列或地下城探索。这种跨摘要步骤的一致性，让单凭 LLM 上下文窗口不可能的长程策略成为可能。

Sub-Agent 架构​

不是一个 Agent 跨整个项目维持状态，专门的 sub-agent 用干净上下文窗口处理聚焦任务。主 Agent 用高层计划协调，sub-agent 执行深度技术工作或用工具找相关信息。每个 sub-agent 可能广泛探索（用数万 token 或更多），但只返回压缩、精炼的工作摘要（通常 1000-2000 token）。

这达成清晰的关注点分离——详细搜索上下文隔离在 sub-agent 内，主 Agent 聚焦综合和分析结果。这模式在复杂研究任务上相比单 Agent 系统显示巨大提升。

选择策略​

方法适用
压缩需要大量来回的对话流任务
笔记有清晰里程碑的迭代式开发
多 Agent并行探索有红利的复杂研究和分析

结论​

上下文工程代表我们用 LLM 构建方式的根本转变。模型变强后，挑战不只是打磨完美提示——而是审慎策划在每一步进入模型有限注意力预算的信息。

无论是为长任务实现压缩、设计 token 高效工具、还是让 Agent 刚好及时探索其环境，指导原则相同：找到最大化所需结果可能性的最小高信号 token 集。

随模型继续提升，更聪明的模型需要更少描述性工程，让 Agent 以更多自治运作。但即使能力扩展，把上下文视为珍贵、有限资源仍将是构建可靠、有效 Agent 的核心。