Effective Context Engineering for AI Agents

文章标题和作者/机构: Effective context engineering for AI agents, Engineering at Anthropic

A1 主要贡献

本文探讨了“上下文工程”（Context Engineering）这一新兴领域，并将其定位为“提示工程”（Prompt Engineering）的自然演进。随着人工智能从执行单次任务向能够执行多轮、长周期任务的智能体（Agent）发展，仅仅优化提示词已不足以满足需求。核心问题在于，大型语言模型（LLM）的上下文窗口是有限的，并且存在“上下文退化”（context rot）现象——即随着上下文中令牌（token）数量的增加，模型准确回忆信息的能力会下降。

研究目标：本文旨在为构建可控、高效的AI智能体提供一个精炼的心智模型和一系列实践策略。其核心目标是解决如何在一个有限的“注意力预算”内，策划和管理最优的上下文信息，以最大化智能体达成预期行为的可能性。

核心创新与贡献点：
1. 提出并定义“上下文工程”：将构建LLM应用的核心从“编写正确的提示”转向“配置最优的上下文”。上下文工程是一个迭代过程，涉及在每次推理时动态地策划和维护进入模型上下文窗口的信息，包括系统指令、工具、外部数据、消息历史等。

2. 阐明上下文管理的重要性：基于LLM的架构限制（如Transformer架构中n²的注意力关系）和训练数据分布，本文解释了“上下文退化”和“注意力稀缺”的根本原因，强调了将上下文视为一种有限资源并进行精细管理的必要性。
3. 提供有效上下文的构成要素和设计原则：
* 系统提示（System Prompts）：应在过于具体、僵化的逻辑和过于模糊、宽泛的指导之间找到一个“黄金区域”，做到既能有效引导行为，又足够灵活。
* 工具（Tools）：工具集应功能明确、无歧义，并能高效地返回信息。臃肿或功能重叠的工具集是常见的失败模式。
* 示例（Examples）：提倡使用少量但多样化、典型的示例（few-shot prompting），而非罗列大量边缘案例。

1. 提出动态上下文检索策略：

   • “即时”（Just-in-time）上下文策略：智能体不预先加载所有数据，而是在运行时使用工具，通过文件路径、URL等轻量级标识符动态加载所需信息，模拟人类按需检索信息的认知模式。
   • 智能体搜索（Agentic Search）：让智能体自主导航和检索数据，实现信息的“渐进式披露”，从而仅在工作记忆中保留必要信息。

2. 为长周期任务设计专门的上下文工程技术：

   • 压缩（Compaction）：在上下文窗口接近极限时，让模型总结对话内容，用这个摘要开启一个新的上下文窗口，以保持连贯性。
   • 结构化笔记（Structured Note-taking）：智能体将关键信息记录到上下文窗口之外的持久化存储中，并在需要时重新调入，作为一种“智能体记忆”。
   • 子智能体架构（Sub-agent Architectures）：由一个主智能体协调多个专门的子智能体。每个子智能体在独立的上下文中处理具体任务，然后将精炼后的结果返回给主智能体，实现关注点分离。

A3 背景知识/关键Observation/设计原则

为何上下文工程对构建强大智能体至关重要

LLM的上下文退化问题。我们观察到，尽管大型语言模型（LLM）速度快且能处理大量数据，但它们和人类一样，在某个点上会失去焦点或感到困惑。针对“大海捞针”式基准测试的研究揭示了“上下文退化”（context rot）的概念：随着上下文窗口中令牌（token）数量的增加，模型从该上下文中准确回忆信息的能力会随之下降。

上下文作为有限资源。虽然某些模型的性能下降比其他模型更平缓，但这种特性在所有模型中都会出现。因此，上下文必须被视为一种边际回报递减的有限资源。如同人类的工作记忆容量有限一样，LLM在解析大量上下文时也有一个“注意力预算”。每一个新引入的令牌都会消耗一部分这个预算，这使得我们愈发需要仔细策划提供给LLM的令牌。

LLM的架构限制。这种注意力稀缺性源于LLM的架构限制。LLM基于Transformer架构，该架构使得每个令牌都能关注到整个上下文中的其他所有令牌。这导致对于n个令牌，存在n²个成对关系。随着上下文长度的增加，模型捕捉这些成对关系的能力被拉伸，从而在上下文大小和注意力焦点之间产生了一种天然的紧张关系。此外，模型的注意力模式是在训练数据分布中形成的，其中短序列通常比长序列更常见。这意味着模型对于处理上下文范围内的依赖关系经验较少，专门化的参数也较少。

位置编码插值技术的影响。像位置编码插值这样的技术通过将长序列适应于最初训练的较小上下文，使得模型能够处理更长的序列，但这会在一定程度上降低对令牌位置的理解能力。这些因素共同导致了性能的平滑下降而非断崖式下跌：模型在较长上下文中仍然非常强大，但与在较短上下文中的表现相比，其信息检索和长程推理的精度可能会降低。

上下文工程的必要性。这些现实情况意味着，深思熟虑的上下文工程对于构建强大的智能体至关重要。

有效上下文的构成

寻找最小化高信噪比令牌集合的核心原则。鉴于LLM受限于有限的注意力预算，良好的上下文工程意味着找到最小的、可能的高信噪比令牌集合，以最大化达成某种期望结果的可能性。实现这一实践远比听起来要困难，但在下文中，我们概述了这一指导原则在上下文不同组成部分中的实际应用。

系统提示应清晰直接。系统提示应该极其清晰，并使用简单、直接的语言，以适合智能体的高度来呈现思想。所谓“正确的高度”，是指介于两种常见失败模式之间的“黄金区域”。一个极端是，工程师在提示中硬编码复杂、脆弱的逻辑，以求精确的智能体行为。这种方法会造成系统脆弱并增加长期的维护复杂性。另一个极端是，工程师有时提供模糊、高层次的指导，这未能给LLM提供关于期望输出的具体信号，或者错误地假设了共享的上下文。最佳的高度则是在两者之间取得平衡：既足够具体以有效引导行为，又足够灵活，为模型提供强大的启发式方法来指导其行为。

组织和优化提示结构。我们建议将提示组织成不同的部分（如<background_information>, <instructions>, ## Tool guidance, ## Output description等），并使用XML标签或Markdown标题等技术来划分这些部分，尽管随着模型能力的增强，提示的具体格式可能变得不那么重要。

从最小化提示开始迭代。无论您决定如何构建系统提示，都应该力求使用能完整概述您预期行为的最小信息集。（请注意，最小并不一定意味着简短；您仍需预先给予智能体足够的信息以确保其遵循期望的行为。）最好的做法是，首先用现有最好的模型测试一个最小化的提示，看看它在您的任务上的表现，然后根据初步测试中发现的失败模式，添加清晰的指令和示例来提升性能。

工具的设计原则。工具允许智能体与其环境进行交互，并在工作时引入新的、额外的上下文。由于工具定义了智能体与其信息/行动空间之间的契合同，因此工具的设计必须能提升效率，这既包括返回令牌高效的信息，也包括鼓励高效的智能体行为。

确保工具的清晰度和独立性。在《为AI智能体编写工具——借助AI智能体》一文中，我们讨论了构建易于LLM理解且功能重叠最小的工具。与设计良好的代码库中的函数类似，工具应该是自包含的、对错误具有鲁棒性，并且其预期用途必须极其明确。输入参数同样应具有描述性、无歧义，并能发挥模型的内在优势。

避免工具集臃肿和歧义。我们看到的最常见的失败模式之一是臃肿的工具集，它覆盖了过多的功能或导致在选择使用哪个工具时出现决策模糊点。如果人类工程师都无法确定在特定情况下应该使用哪个工具，那么就不能期望AI智能体能做得更好。正如我们稍后将讨论的，为智能体策划一个最小可行的工具集，也有助于在长时间的交互中实现更可靠的上下文维护和修剪。

提供精选示例（Few-shot Prompting）。提供示例，即所谓的少样本提示（few-shot prompting），是一个众所周知的最佳实践，我们继续强烈推荐。然而，团队常常会在提示中塞入一长串的边缘案例，试图阐明LLM在特定任务中应遵循的每一个可能规则。我们不推荐这种做法。相反，我们建议努力策划一组多样化、典型的示例，以有效展示智能体的预期行为。对于LLM来说，示例就是“一图胜千言”中的“图”。

上下文工程的总体指导。我们对上下文不同组成部分（系统提示、工具、示例、消息历史等）的总体指导是：要深思熟虑，并保持上下文信息丰富而紧凑。现在，让我们深入探讨在运行时动态检索上下文的方法。

A2 方法细节

上下文检索与智能体搜索

对智能体的定义。在《构建高效的AI智能体》一文中，我们强调了基于LLM的工作流与智能体之间的区别。自那篇文章发布以来，我们逐渐倾向于一个简单的智能体定义：LLM以循环方式自主使用工具。

智能体自主性随模型能力扩展。通过与客户的合作，我们看到该领域正趋向于这个简单的范式。随着底层模型能力的增强，智能体的自主性水平可以随之扩展：更智能的模型允许智能体独立地在复杂的问题空间中导航并从错误中恢复。

从预检索到即时上下文的转变。我们现在观察到工程师在设计智能体上下文方面的思维方式正在发生变化。如今，许多AI原生应用都采用某种基于嵌入的推理前检索方式，为智能体提供重要的上下文以供其推理。随着领域向更具智能体性的方法过渡，我们越来越多地看到团队用“即时”（just in time）上下文策略来增强这些检索系统。

“即时”上下文策略的工作方式。“即时”方法构建的智能体不会预先处理所有相关数据，而是维护一些轻量级的标识符（如文件路径、存储的查询、网页链接等），并使用这些引用在运行时通过工具动态地将数据加载到上下文中。Anthropic的智能体编码解决方案Claude Code就使用这种方法对大型数据库执行复杂的数据分析。该模型可以编写有针对性的查询、存储结果，并利用像head和tail这样的Bash命令来分析大量数据，而无需将完整的数据对象加载到上下文中。这种方法反映了人类的认知：我们通常不会记忆整个信息库，而是引入外部组织和索引系统，如文件系统、收件箱和书签，以便按需检索相关信息。

元数据在智能体行为中的作用。除了存储效率，这些引用的元数据——无论是明确提供的还是直观的——都提供了一种有效优化行为的机制。对于在一个文件系统中操作的智能体来说，tests文件夹中一个名为test_utils.py的文件的存在，其意图就不同于src/core_logic/目录下同名的文件。文件夹层次结构、命名约定和时间戳都为人类和智能体提供了重要信号，帮助他们理解如何以及何时利用信息。

渐进式信息披露。让智能体自主导航和检索数据还实现了“渐进式披露”——换句话说，允许智能体通过探索逐步发现相关上下文。每一次交互都会产生新的上下文，为下一次决策提供信息：文件大小暗示了复杂性；命名约定暗示了用途；时间戳可以作为相关性的代理。智能体可以逐层构建理解，只在工作记忆中保留必要的内容，并利用笔记策略进行额外的持久化。这种自我管理的上下文窗口使智能体能够专注于相关子集，而不是淹没在详尽但可能无关的信息中。

即时探索的权衡。当然，这也存在权衡：运行时探索比检索预先计算的数据要慢。不仅如此，还需要有主见和深思熟虑的工程设计，以确保LLM拥有正确的工具和启发式方法来有效地导航其信息环境。没有适当的指导，智能体可能会因滥用工具、追逐死胡同或未能识别关键信息而浪费上下文。

混合策略的应用。在某些情况下，最有效的智能体可能会采用一种混合策略，即预先检索一些数据以提高速度，并自行决定进行进一步的自主探索。决定“正确”自主性水平的边界取决于任务。Claude Code就是一个采用这种混合模型的智能体：CLAUDE.md文件会预先简单地放入上下文中，而像glob和grep这样的原语使其能够导航环境并即时检索文件，从而有效绕过了索引陈旧和复杂语法树的问题。

混合策略的适用场景与未来趋势。混合策略可能更适用于内容不那么动态的场景，例如法律或金融工作。随着模型能力的提升，智能体设计将趋向于让智能模型表现得更智能，并逐渐减少人工策划。鉴于该领域的快速发展，“做最简单有效的事”可能仍然是我们给基于Claude构建智能体的团队的最佳建议。

针对长周期任务的上下文工程

长周期任务的挑战。长周期任务要求智能体在一系列动作中保持连贯性、上下文和目标导向行为，而这些动作序列的令牌总数超过了LLM的上下文窗口。对于持续数十分钟到数小时的连续工作，如大型代码库迁移或全面的研究项目，智能体需要专门的技术来规避上下文窗口大小的限制。

上下文窗口大小的局限性。等待更大的上下文窗口似乎是一个显而易见的策略。但很可能在可预见的未来，各种大小的上下文窗口都将受到上下文污染和信息相关性问题的影响——至少在追求最强智能体性能的情况下是如此。为了使智能体能够在扩展的时间范围内有效工作，我们开发了几种直接解决这些上下文污染限制的技术：压缩、结构化笔记和多智能体架构。

压缩（Compaction）

压缩的定义与作用。压缩是一种实践，即当一个对话接近上下文窗口限制时，对其内容进行总结，并用该总结重新启动一个新的上下文窗口。压缩通常是上下文工程中用于提升长期连贯性的首要手段。其核心在于以高保真度的方式提炼上下文窗口的内容，使智能体能够以最小的性能下降继续工作。

Claude Code中的压缩实现。例如，在Claude Code中，我们通过将消息历史传递给模型，让其总结和压缩最关键的细节来实现这一点。模型会保留架构决策、未解决的错误和实现细节，同时丢弃冗余的工具输出或消息。然后，智能体可以带着这个压缩后的上下文加上最近访问的五个文件继续工作。用户可以获得连续性，而无需担心上下文窗口的限制。

压缩的艺术与调优。压缩的艺术在于选择保留什么和丢弃什么，因为过于激进的压缩可能导致 subtle 但关键的上下文丢失，而这些上下文的重要性可能在后期才会显现。对于实现压缩系统的工程师，我们建议在复杂的智能体追踪记录上仔细调整你的提示。首先，最大化召回率，确保你的压缩提示能从追踪记录中捕捉到每一个相关信息；然后，通过消除多余内容来迭代提高精确度。

工具结果清理作为一种简单的压缩。一个容易实现的多余内容清理示例是清除工具调用和结果——一旦一个工具在消息历史的深处被调用过，智能体为什么还需要再次看到原始结果？工具结果清理是最安全、最轻量级的压缩形式之一，最近已作为一项功能在Claude开发者平台上推出。

结构化笔记

结构化笔记的定义。结构化笔记，或称“智能体记忆”，是一种技术，即智能体定期将笔记写入并持久化到上下文窗口之外的内存中。这些笔记在后续时间点会被重新拉入上下文窗口。

结构化笔记的优势。这种策略以最小的开销提供了持久的记忆。就像Claude Code创建一个待办事项列表，或者你的自定义智能体维护一个NOTES.md文件一样，这个简单的模式允许智能体在复杂任务中跟踪进度，维护那些否则会在数十次工具调用中丢失的关键上下文和依赖关系。

在非编码领域的应用示例。Claude玩《宝可梦》的例子展示了记忆如何在非编码领域改变智能体的能力。该智能体在数千个游戏步骤中保持精确的计数——跟踪目标，例如“在过去的1234步中，我一直在1号道路上训练我的宝可梦，皮卡丘已经升了8级，目标是10级。”在没有任何关于记忆结构的提示下，它自己绘制了已探索区域的地图，记住了已解锁的关键成就，并维护了战斗策略的战略笔记，帮助它学习哪种攻击对不同对手最有效。

跨上下文重置保持连贯性。在上下文重置后，智能体读取自己的笔记，并继续进行数小时的训练序列或地牢探索。这种跨越总结步骤的连贯性使得长周期的策略成为可能，而如果将所有信息都保留在LLM的上下文窗口中，这是不可能实现的。

Claude开发者平台上的记忆工具。作为我们Sonnet 4.5发布的一部分，我们在Claude开发者平台上以公开测试版的形式发布了一个记忆工具，该工具通过一个基于文件的系统，使得在上下文窗口之外存储和查询信息变得更加容易。这使得智能体能够随着时间的推移建立知识库，跨会话维护项目状态，并在不将所有内容保留在上下文中的情况下引用先前的工作。

子智能体架构

子智能体架构的原理。子智能体架构提供了另一种绕过上下文限制的方法。不是让一个智能体试图在整个项目中维护状态，而是让专门的子智能体处理具有干净上下文窗口的专注任务。主智能体通过一个高层计划进行协调，而子智能体则执行深入的技术工作或使用工具查找相关信息。每个子智能体可能会进行广泛的探索，使用数万甚至更多的令牌，但只返回其工作的浓缩、提炼后的摘要（通常为1000-2000个令牌）。

子智能体架构的优势。这种方法实现了明确的关注点分离——详细的搜索上下文被隔离在子智能体内部，而主导智能体则专注于综合和分析结果。这种模式在《我们如何构建多智能体研究系统》一文中有过讨论，并在复杂的研究任务上显示出比单智能体系统显著的性能提升。

不同方法的选择依据。这些方法之间的选择取决于任务的特性。例如：

• 压缩：适用于需要大量来回交流的任务，以保持对话流程的连贯性。
• 笔记：在具有明确里程碑的迭代开发任务中表现出色。
• 多智能体架构：适用于复杂的、并行探索能带来收益的研究和分析任务。

未来展望。即使模型不断进步，在扩展交互中保持连贯性的挑战仍将是构建更有效智能体的核心。

A4 实验环境

本文并未提供传统学术论文中的标准化实验环境设置，如特定的数据集、硬件配置或软件库版本。它更像是一篇阐述方法论和最佳实践的白皮书。文中提到的应用和示例主要用于说明所提出上下文工程技术的有效性。

• 模型与平台：

  • 主要基于Anthropic的Claude系列模型。
  • 提到了Claude开发者平台（Claude Developer Platform）作为实现这些技术的平台，并提及了Sonnet 4.5模型的发布。
  • 提及了平台上的特定功能，如工具结果清理（tool result clearing）和公开测试版的记忆工具（memory tool）。

• 应用场景与示例：

  • Claude Code：一个用于执行复杂数据分析和大规模代码库迁移的智能体编码解决方案。它被用来说明“即时”上下文加载、混合策略和“压缩”技术。
  • Claude玩《宝可梦》：一个概念验证示例，展示了智能体在非编码、长周期任务中如何利用“结构化笔记”来维持状态、跟踪目标和学习策略。
  • 多智能体研究系统：一个内部项目，用于说明“子智能体架构”在处理复杂研究任务时的优势。

A4 实验结果

本文没有提供定量的实验结果或基准测试数据。其结果以定性描述和案例分析的形式呈现，旨在验证所提出的上下文工程策略的有效性。

• “即时”上下文与智能体搜索：

  • 实验内容：通过Claude Code应用，让智能体处理大型数据库和代码库。
  • 实验结果：Claude Code能够编写针对性查询，并使用head和tail等命令分析数据，而无需将整个数据库加载到上下文中，成功完成了复杂的数据分析任务。这证明了“即时”上下文策略在处理大规模数据时的有效性和效率。
  • 分析结论：通过让智能体自主、动态地加载信息，可以模拟人类的认知过程，有效绕过上下文窗口限制，并利用文件系统等元数据作为行为指导。

• 压缩（Compaction）：

  • 实验内容：在Claude Code执行大型代码库迁移等长周期任务时，当上下文接近极限时应用压缩技术。
  • 实验结果：模型能够成功地总结对话历史，保留关键的架构决策和未解决的bug，同时丢弃冗余信息。智能体能够基于压缩后的上下文继续工作，保持了任务的连续性。
  • 分析结论：压缩是维持智能体在长周期任务中连贯性的有效首要手段。

• 结构化笔记（Structured Note-taking）：

  • 实验内容：让一个Claude智能体玩《宝可梦》游戏，这是一个需要长期记忆和策略规划的任务。
  • 实验结果：智能体自发地创建和维护笔记，记录了游戏进度（如训练步数、等级提升）、探索过的地图区域、关键成就以及有效的战斗策略。即使在上下文重置后，它也能通过读取笔记恢复状态，继续执行长达数小时的任务。
  • 分析结论：结构化笔记（智能体记忆）极大地增强了智能体在非编码领域处理长周期任务的能力，使其能够跨越上下文窗口的限制进行规划和学习。

• 子智能体架构（Sub-agent Architectures）：

  • 实验内容：构建一个多智能体研究系统，由主智能体协调多个负责特定搜索和分析任务的子智能体。
  • 实验结果：该系统在处理复杂研究任务时，表现出比单智能体系统“显著的性能提升”。
  • 分析结论：通过将复杂任务分解给具有独立上下文的子智能体，可以实现关注点分离，有效管理上下文并提升整体性能。

A5 结论

本文的结论是，上下文工程代表了我们使用LLM构建应用的根本性转变。随着模型变得越来越强大，挑战不再仅仅是制作完美的提示，而是要在每一步都深思熟虑地策划哪些信息进入模型有限的注意力预算。

核心指导原则：无论是在为长周期任务实施压缩、设计令牌高效的工具，还是让智能体能够即时探索其环境，指导原则始终如一：找到最小的、能最大化预期结果可能性的高信噪比令牌集合。

未来展望：本文预测，随着模型不断进步，这些技术将持续演进。更智能的模型将需要更少的规定性工程，允许智能体以更大的自主性运作。然而，即便模型能力不断扩展，将上下文视为一种宝贵、有限的资源，对于构建可靠、高效的智能体而言，仍将是至关重要的核心理念。

最后，文章鼓励读者开始在Claude开发者平台实践上下文工程，并利用相关的教程和最佳实践资源。