面向 AI agents 的有效 context engineering

在 applied AI 中，prompt engineering 成为关注焦点已有几年，如今一个新术语开始受到重视：context engineering。使用语言模型构建应用，越来越不只是为 prompt 找到合适的词句，而是要回答一个更广泛的问题：“什么样的 context 配置最有可能让模型产生我们期望的行为？”

Context 指的是从 large-language model (LLM) 采样时包含的一组 token。当前的工程问题，是在 LLM 固有约束下优化这些 token 的效用，以便稳定实现期望结果。有效驾驭 LLM 往往需要从 context 的角度思考——换句话说：考虑 LLM 在任一时刻可用的整体状态，以及该状态可能产生的行为。

在本文中，我们将探讨正在形成的 context engineering 方法，并提供一个更精炼的心智模型，用于构建可引导、有效的 agent。

在 Anthropic，我们将 context engineering 视为 prompt engineering 的自然演进。Prompt engineering 指的是编写和组织 LLM 指令以获得最佳结果的方法（概览和实用的 prompt engineering 策略可参见我们的文档）。Context engineering 指的是在 LLM inference 期间策划和维护最优 token（信息）集合的一组策略，其中包括 prompt 之外可能进入 context 的所有其他信息。

在使用 LLM 做工程的早期，prompting 是 AI engineering 工作中最大的组成部分，因为除日常聊天交互外，大多数用例都需要针对 one-shot 分类或文本生成任务优化 prompt。顾名思义，prompt engineering 的主要关注点是如何编写有效的 prompt，尤其是 system prompt。然而，随着我们转向构建更强大的 agent，使其能够在多轮 inference 和更长时间跨度内运行，我们需要管理整个 context 状态的策略（system instructions、tools、Model Context Protocol (MCP)、外部数据、message history 等）。

在循环中运行的 agent 会生成越来越多可能与下一轮 inference 相关的数据，而这些信息必须被循环式地精炼。Context engineering 是一门艺术，也是一门科学：它要从不断演化的潜在信息宇宙中，策划哪些内容进入有限的 context window。

尽管 LLM 速度很快，也越来越能够管理更大规模的数据，但我们观察到，LLM 和人类一样，在某个点之后会失去焦点或产生混淆。关于 needle-in-a-haystack 风格 benchmark 的研究揭示了 context rot 这一概念：随着 context window 中 token 数量增加，模型从该 context 中准确回忆信息的能力会下降。

虽然一些模型的退化比另一些更平缓，但这一特征在所有模型中都会出现。因此，context 必须被视为一种有限资源，并且具有边际收益递减的特性。就像人类的工作记忆容量有限一样，LLM 在解析大量 context 时也会使用一个“attention budget”。每引入一个新 token，都会在某种程度上消耗这一预算，从而增加了谨慎策划 LLM 可用 token 的必要性。

这种 attention 稀缺性源于 LLM 的架构约束。LLM 基于 Transformer 架构，使每个 token 都能在整个 context 中 attend to 每个其他 token。这会为 n 个 token 产生 n² 个成对关系。

随着 context length 增加，模型捕捉这些成对关系的能力会被摊薄，在 context size 与 attention focus 之间形成天然张力。此外，模型的 attention pattern 来自训练数据分布，而在训练数据中，较短序列通常比较长序列更常见。这意味着模型对 context-wide dependencies 的经验更少，也拥有更少针对这类依赖的专门参数。

position encoding interpolation 等技术允许模型通过适配原本训练时较小的 context 来处理更长序列，不过这会使 token 位置理解有所退化。这些因素共同形成的是性能梯度，而不是硬性的断崖：模型在更长 context 下仍然非常有能力，但与其在较短 context 上的表现相比，在信息检索和长程推理方面可能精度下降。

这些现实意味着，周密的 context engineering 对构建强大的 agent 至关重要。

鉴于 LLM 受有限 attention budget 约束，好的 context engineering 意味着找到尽可能小的高信号 token 集合，以最大化某个期望结果发生的可能性。落实这一实践远比说起来困难，但在下一节中，我们会说明这一指导原则在 context 不同组成部分中的实际含义。

System prompt 应当极其清晰，并使用简单、直接的语言，在适合 agent 的抽象高度呈现想法。合适的抽象高度位于两种常见失败模式之间的 Goldilocks zone。一个极端是，工程师在 prompt 中硬编码复杂、脆弱的逻辑，以诱导精确的 agentic 行为。这种方法会带来脆弱性，并随着时间推移增加维护复杂度。另一个极端是，工程师有时提供模糊的高层指导，无法给 LLM 提供关于期望输出的具体信号，或错误地假设双方拥有共享 context。最佳高度需要取得平衡：足够具体，能有效引导行为；又足够灵活，能为模型提供强有力的 heuristics 来指导行为。

我们建议将 prompt 组织为不同 section（例如 、、## Tool guidance、## Output description 等），并使用 XML tagging 或 Markdown headers 等技术来划分这些 section，尽管随着模型能力增强，prompt 的具体格式可能正变得不那么重要。

无论你决定如何组织 system prompt，都应努力提供最小信息集合，同时完整描述你期望的行为。（请注意，最小并不一定意味着短；你仍然需要预先给 agent 足够信息，确保它遵循期望行为。）最佳做法是先用可用的最佳模型测试一个最小 prompt，观察它在你的任务上的表现，然后根据初始测试中发现的失败模式，添加清晰指令和示例来提升表现。

Tools 允许 agent 与环境交互，并在工作过程中拉取新的额外 context。由于 tools 定义了 agent 与其信息/行动空间之间的契约，因此 tools 必须促进效率：既要返回 token 高效的信息，也要鼓励高效的 agent 行为。

在 Writing tools for AI agents – with AI agents 中，我们讨论了如何构建 LLM 易于理解、且功能重叠最少的 tools。类似于设计良好的代码库中的函数，tools 应当自包含、对错误具备鲁棒性，并且在预期用途上极其清晰。Input parameters 同样应当描述明确、无歧义，并发挥模型的内在优势。

我们看到的最常见失败模式之一，是 tool set 臃肿，覆盖过多功能，或导致在选择使用哪个 tool 时出现含糊的决策点。如果一名人类工程师都无法明确说出某种情况下应使用哪个 tool，就不能期待 AI agent 做得更好。正如稍后会讨论的，为 agent 策划一个最小可行 tool set，也能在长交互中带来更可靠的 context 维护和修剪。

提供示例，也称为 few-shot prompting，是一项众所周知的最佳实践，我们仍然强烈建议采用。然而，团队常常会把一长串 edge cases 塞进 prompt，试图阐明 LLM 在特定任务中应遵循的每一条可能规则。我们不建议这样做。相反，我们建议策划一组多样化、典型的示例，能够有效呈现 agent 的预期行为。对 LLM 来说，示例就是“胜过千言万语的图片”。

我们对 context 不同组成部分（system prompts、tools、examples、message history 等）的总体建议是：保持审慎，让你的 context 信息充分但紧凑。现在让我们深入讨论如何在 runtime 动态检索 context。

在 Building effective AI agents 中，我们强调了基于 LLM 的 workflows 与 agents 之间的差异。自那篇文章发布以来，我们逐渐倾向于用一个简单定义来描述 agent：LLM 在循环中自主使用 tools。

在与客户合作的过程中，我们看到整个领域正在向这一简单范式收敛。随着底层模型能力增强，agent 的自主程度也可以扩展：更聪明的模型允许 agent 独立处理细微复杂的问题空间，并从错误中恢复。

现在，我们看到工程师对 agent context 设计的思考方式正在发生转变。如今，许多 AI-native 应用会采用某种基于 embedding 的 pre-inference time retrieval，以浮现重要 context 供 agent 推理。随着领域转向更 agentic 的方法，我们越来越多地看到团队用“just in time”context 策略来增强这些 retrieval systems。

采用“just in time”方法构建的 agent，不会预先处理所有相关数据，而是维护轻量级标识符（file paths、stored queries、web links 等），并在 runtime 使用 tools 通过这些引用动态将数据加载到 context 中。Anthropic 的 agentic coding 解决方案 Claude Code 就使用这种方法，在大型数据库上执行复杂数据分析。模型可以编写有针对性的 queries，存储结果，并利用 Bash 命令如 head 和 tail 分析大量数据，而不必将完整数据对象加载到 context 中。这种方法类似于人类认知：我们通常不会记住整套信息语料，而是引入外部组织和索引系统，如 file systems、inboxes 和 bookmarks，以便按需检索相关信息。

除了存储效率之外，这些引用的 metadata 还提供了一种高效精炼行为的机制，无论这种机制是显式提供的还是直观形成的。对于在 file system 中运行的 agent 来说，tests 文件夹中名为 test_utils.py 的文件，与 src/core_logic/ 中同名文件所暗示的用途不同。Folder hierarchies、naming conventions 和 timestamps 都提供了重要信号，帮助人类和 agent 理解如何以及何时使用信息。

让 agent 自主导航和检索数据，也支持 progressive disclosure——换句话说，允许 agent 通过探索逐步发现相关 context。每次交互都会产生 context，用来为下一次决策提供信息：file sizes 暗示复杂度；naming conventions 暗示用途；timestamps 可以作为相关性的 proxy。Agent 可以逐层构建理解，只在工作记忆中保留必要内容，并利用 note-taking 策略实现额外持久化。这种自管理的 context window 让 agent 聚焦于相关子集，而不是淹没在穷尽但可能无关的信息中。

当然，这里存在权衡：runtime exploration 比检索预计算数据更慢。不仅如此，还需要有观点且周密的工程设计，确保 LLM 拥有合适的 tools 和 heuristics，能够有效导航其信息环境。如果缺少适当指导，agent 可能会误用 tools、追逐死胡同，或未能识别关键信息，从而浪费 context。

在某些场景中，最有效的 agent 可能会采用混合策略：为了速度预先检索一部分数据，并在自行判断时进行进一步自主探索。关于“正确”自主程度的决策边界取决于任务。Claude Code 就是采用这种混合模型的 agent：CLAUDE.md files 会被朴素地预先放入 context，而 glob 和 grep 等 primitives 允许它导航环境并 just-in-time 检索文件，从而有效绕过陈旧 indexing 和复杂 syntax trees 的问题。

这种混合策略可能更适合内容动态性较低的 context，例如法律或金融工作。随着模型能力提升，agentic design 会朝着让智能模型以智能方式行动的方向发展，并逐步减少人类策划。鉴于该领域进展很快，“do the simplest thing that works”很可能仍然是我们给使用 Claude 构建 agent 的团队的最佳建议。

Long-horizon tasks 要求 agent 在一系列动作中保持连贯性、context 和目标导向行为，而这些动作的 token 数会超过 LLM 的 context window。对于持续工作数十分钟到数小时的任务，例如大型代码库迁移或全面研究项目，agent 需要专门技术来绕过 context window 大小限制。

等待更大的 context window 似乎是一个显而易见的策略。但在可预见的未来，各种大小的 context window 都可能受到 context pollution 和信息相关性问题的影响——至少在需要最强 agent 表现的场景中是如此。为了让 agent 能够在更长时间跨度内有效工作，我们开发了一些直接应对这些 context pollution 约束的技术：compaction、structured note-taking 和 multi-agent architectures。

Compaction

Compaction 是一种实践：当 conversation 接近 context window 限制时，总结其内容，并用该 summary 重新启动一个新的 context window。Compaction 通常是 context engineering 中用于提升长期连贯性的第一个杠杆。其核心是以高保真方式提炼 context window 的内容，使 agent 能以最小性能退化继续工作。

例如，在 Claude Code 中，我们通过将 message history 传给模型，让模型总结并压缩最关键的细节来实现这一点。模型会保留架构决策、未解决 bug 和实现细节，同时丢弃冗余的 tool outputs 或 messages。随后，agent 可以基于这个压缩后的 context 加上最近访问的五个文件继续工作。用户可以获得连续性，而不必担心 context window 限制。

Compaction 的艺术在于选择保留什么与丢弃什么，因为过于激进的 compaction 可能会导致细微但关键的 context 丢失，而这些 context 的重要性可能只有稍后才会显现。对于实现 compaction systems 的工程师，我们建议在复杂 agent traces 上仔细调优你的 prompt。可以先最大化 recall，确保 compaction prompt 捕捉 trace 中每一条相关信息，然后迭代提升 precision，去除多余内容。

一个容易处理的多余内容例子是清除 tool calls 和 results——当某个 tool call 已经深埋在 message history 中之后，agent 为什么还需要再次看到原始结果？最安全、最轻量的 compaction 形式之一是 tool result clearing，最近已作为 Claude Developer Platform 上的一项功能发布。

Structured note-taking

Structured note-taking，或 agentic memory，是一种技术：agent 定期将 notes 写入 context window 之外的持久化 memory。这些 notes 会在之后被重新拉回 context window。

这种策略以最小开销提供持久记忆。就像 Claude Code 创建 to-do list，或你的 custom agent 维护一个 NOTES.md file，这个简单模式允许 agent 在复杂任务中跟踪进度，维护关键 context 和 dependencies，否则这些信息可能会在几十次 tool calls 之后丢失。

Claude playing Pokémon 展示了 memory 如何改变 agent 在非编码领域的能力。该 agent 会在数千个 game steps 中保持精确统计——跟踪诸如“在过去 1,234 steps 中，我一直在 Route 1 训练我的 Pokémon，Pikachu 已经朝着 10 级目标提升了 8 级”这样的目标。在没有任何关于 memory structure 的 prompting 的情况下，它会建立已探索区域的 maps，记住自己解锁了哪些关键 achievements，并维护关于 combat strategies 的策略 notes，帮助它学习哪些 attacks 对不同对手最有效。

在 context resets 后，agent 会读取自己的 notes，并继续进行多小时的训练序列或 dungeon explorations。这种跨 summarization steps 的连贯性支持 long-horizon strategies，而如果仅依靠 LLM 的 context window 保留全部信息，这是不可能实现的。

作为 Sonnet 4.5 发布的一部分，我们在 Claude Developer Platform 上发布了一个处于 public beta 的 memory tool，让开发者更容易通过基于文件的系统在 context window 之外存储和查阅信息。这允许 agent 随时间构建 knowledge bases，跨 sessions 维护 project state，并在不把所有内容都保留在 context 中的情况下引用之前的工作。

Sub-agent architectures

Sub-agent architectures 提供了另一种绕过 context 限制的方式。与其让一个 agent 试图在整个项目中维护状态，不如让专门的 sub-agents 使用干净的 context windows 处理聚焦任务。Main agent 负责基于高层计划进行协调，而 subagents 执行深入技术工作，或使用 tools 查找相关信息。每个 subagent 可能会进行广泛探索，使用数万甚至更多 token，但最终只返回其工作的浓缩、提炼后的 summary（通常为 1,000-2,000 tokens）。

这种方法实现了清晰的关注点分离——详细的搜索 context 被隔离在 sub-agents 内部，而 lead agent 专注于综合和分析结果。这一模式在 How we built our multi-agent research system 中有所讨论，并在复杂研究任务上相较 single-agent systems 显示出显著改进。

这些方法之间的选择取决于任务特征。例如：

即使模型持续改进，在长时间交互中维持连贯性的挑战，仍将是构建更有效 agent 的核心问题。

Context engineering 代表了我们使用 LLM 构建系统方式的一次根本转变。随着模型能力增强，挑战不再只是精心编写完美 prompt，而是要在每一步周密策划哪些信息进入模型有限的 attention budget。无论你是在为 long-horizon tasks 实现 compaction，设计 token-efficient tools，还是让 agent 能够 just-in-time 探索环境，指导原则都相同：找到最小的高信号 token 集合，以最大化你期望结果发生的可能性。

随着模型改进，我们概述的这些技术也会继续演化。我们已经看到，更聪明的模型需要更少的规定式工程设计，允许 agent 以更高自主性运行。但即便能力继续扩展，将 context 视为宝贵而有限的资源，仍将是构建可靠、有效 agent 的核心。

今天即可在 Claude Developer Platform 开始使用 context engineering，并通过我们的 memory and context management cookbook 获取实用提示和最佳实践。

作者为 Anthropic 的 Applied AI team：Prithvi Rajasekaran、Ethan Dixon、Carly Ryan 和 Jeremy Hadfield，并有团队成员 Rafi Ayub、Hannah Moran、Cal Rueb 和 Connor Jennings 参与贡献。特别感谢 Molly Vorwerck、Stuart Ritchie 和 Maggie Vo 的支持。