摘要
1) 一句话总结
Deep Agents SDK 通过文件系统卸载和对话总结等上下文压缩技术，有效管理大语言模型的内存限制，防止 AI 代理在执行长任务时出现上下文衰退。
2) 核心要点
- 框架定位：Deep Agents SDK 是 LangChain 开源的代理框架，支持代理进行规划、生成子代理以及与文件系统交互以执行长任务。
- 文件系统抽象：代理可执行列出、读取、写入、搜索等操作，用于将庞大的上下文卸载到磁盘，并在需要时重新检索。
- 卸载大型工具结果：当工具响应超过 20,000 个 token 时，系统会将其卸载到文件系统，并在上下文中替换为文件路径和前 10 行预览。
- 卸载大型工具输入：当会话上下文超过模型可用窗口的 85% 时，系统会将旧的文件写入/编辑参数截断，替换为指向磁盘文件的指针。
- 双重总结机制：当卸载无法腾出足够空间时，LLM 会生成结构化总结（包含意图、工件和后续步骤）以替换工作内存中的历史记录，同时将完整的原始消息作为规范记录保存到文件系统。
- 压力测试策略：通过在较低的上下文阈值（如 10-20%）人为触发压缩，可以生成更多压缩事件，从而放大信号以评估和优化不同的配置（如总结提示词）。
- 针对性评估（Targeted Evals）：SDK 维护了一套小型集成测试（如“大海捞针”场景），专门用于验证代理在压缩后是否能保持目标轨迹，以及能否通过文件系统成功恢复被总结掉的关键信息。
3) 风险/不足
- 目标偏移（Goal drift）：代理在执行总结后可能会失去对用户意图的追踪，表现为在下一轮中停下来要求澄清，或者错误地宣布任务已完成。
- 上下文衰退（Context rot）：随着代理处理任务长度的增加，如果不进行有效的上下文管理，模型会出现上下文衰退现象。
- 过度压缩导致性能下降：如果在过低的上下文窗口比例（如 10-20%）下频繁触发总结，会导致代理的整体任务执行性能不佳。
正文
作者：Chester Curme 和 Mason Daugherty
随着 AI 代理（AI agents）可处理的任务长度不断增加，有效的上下文管理变得至关重要，这有助于防止上下文衰退（context rot），并应对大语言模型（LLM）有限的内存限制。
Deep Agents SDK 是 LangChain 开源的、开箱即用的代理框架（agent harness）。它提供了一条便捷的途径来构建具备规划、生成子代理（subagents）以及与文件系统交互能力的代理，从而执行复杂且长时间运行的任务。由于这类任务通常会超出模型的上下文窗口（context windows），该 SDK 实现了一系列促进上下文压缩（context compression）的功能。
上下文压缩是指在保留完成任务所需相关细节的同时，减少代理工作内存中信息量的技术。这可能涉及总结先前的交互、过滤掉过时的信息，或者策略性地决定保留什么和丢弃什么。
Deep Agents 实现了一个文件系统抽象，允许代理执行列出、读取和写入文件等操作，以及搜索、模式匹配和文件执行。代理使用该文件系统根据需要搜索和检索已卸载（offloaded）的内容。
Deep Agents 实现了三种主要的压缩技术，它们以不同的频率触发：
-
卸载大型工具结果：每当出现大型工具响应时，我们都会将其卸载到文件系统中。
-
卸载大型工具输入：当上下文大小超过阈值时，我们会将工具调用中旧的写入/编辑参数卸载到文件系统中。
-
总结：当上下文大小超过阈值，且没有更多符合卸载条件的上下文时，我们会执行总结步骤来压缩消息历史记录。
为了管理上下文限制，Deep Agents SDK 会在达到模型上下文窗口大小的特定比例阈值时触发这些压缩步骤。（在底层，我们使用 LangChain 的模型配置文件来获取特定模型的 token 阈值。）
卸载大型工具结果
工具调用（例如，读取大文件或 API 调用的结果）的响应可能会超出模型的上下文窗口。当 Deep Agents 检测到工具响应超过 20,000 个 token 时，它会将该响应卸载到文件系统，并用文件路径引用和前 10 行的预览来替换它。然后，代理可以根据需要重新读取或搜索该内容。
卸载大型工具输入
文件写入和编辑操作会在代理的对话历史记录中留下包含完整文件内容的工具调用。由于这些内容已经持久化到文件系统中，它们通常是多余的。当会话上下文超过模型可用窗口的 85% 时，Deep Agents 将截断较旧的工具调用，将其替换为指向磁盘上文件的指针，从而减小活动上下文的大小。
总结
当卸载不再能腾出足够的空间时，Deep Agents 会退而求其次使用总结功能。该过程包含两个部分：
-
上下文内总结：LLM 会生成对话的结构化总结——包括会话意图、创建的工件（artifacts）和后续步骤——该总结将替换代理工作内存中的完整对话历史记录。（请参阅 Deep Agents 总结提示词。）
-
文件系统保存：完整、原始的对话消息将作为规范记录（canonical record）写入文件系统。
这种双重方法确保代理（通过总结）保持对其目标和进度的认知，同时（通过文件系统搜索）保留在需要时恢复特定细节的能力。请参阅此追踪记录（trace）中的示例，其中模型使用 read_file 工具来获取先前卸载的消息。
实际应用中的表现
虽然上述技术提供了上下文管理的机制，但我们如何知道它们是否真的有效？在真实世界任务中的运行（如 terminal-bench 等基准测试所捕获的那样）可能会偶尔触发上下文压缩，这使得很难孤立地分析它们的影响。
我们发现，通过在基准数据集上更激进地调用框架的各个功能来增强其信号是很有用的。例如，虽然在可用上下文窗口的 10 - 20% 时触发总结可能会导致整体性能不佳，但它会产生明显更多的总结事件。这使得比较不同的配置（例如，您实现的不同变体）成为可能。例如，通过强制代理频繁进行总结，我们可以发现对 deepagents 总结提示词进行简单修改（我们在其中添加了用于会话意图和后续步骤的专用字段）是如何帮助提高性能的。
图：Claude Sonnet 4.5 在 terminal-bench-2 上的示例运行中随时间变化的 Token 使用情况（灰线显示所有运行；彩色线突出显示两个特定示例）。绿线显示在第 20 轮左右，当总结事件压缩对话历史记录时，Token 数量急剧下降。橙线显示在第 40 轮左右，当一个大型文件写入工具调用从上下文中被驱逐时，Token 数量出现了较小的减少。通过在上下文窗口的 25% 处触发压缩（而不是 Deep Agents 默认的 85%），我们生成了更多的事件以供研究。
针对性评估
Deep Agents SDK 维护了一套针对性评估（targeted evals），旨在隔离和验证各个上下文管理机制。这些是刻意设计的小型测试，旨在使特定的故障模式变得明显且易于调试。
这些评估的目的不是衡量广泛的任务解决能力，而是确保代理的框架不会阻碍某些任务的执行。例如：
-
总结是否保留了代理的目标？ 某些评估会故意在任务中途触发总结，然后检查代理是否继续执行。这确保了总结不仅保留了代理的状态，还保留了其行动轨迹。
-
代理能否恢复被总结掉的信息？ 在这里，我们在对话早期嵌入一个“大海捞针（needle-in-the-haystack）”式的事实，强制触发总结事件，然后要求代理在稍后回忆起该事实以完成任务。总结后，该事实不再存在于活动上下文中，必须通过文件系统搜索来恢复。
这些针对性评估充当了上下文管理的集成测试：它们不能取代完整的基准测试运行，但它们显著减少了迭代时间，并使故障可以归因于特定的压缩机制，而不是代理的整体行为。
指导建议
在评估您自己的上下文压缩策略时，我们强调以下几点：
-
从真实世界的基准测试开始，然后对各个功能进行压力测试。 首先在具有代表性的任务上运行您的框架以建立基准性能。然后，人为地更激进地触发压缩（例如，在上下文的 10-20% 而不是 85% 时触发），以便在每次运行中生成更多的压缩事件。这放大了各个功能的信号，使得比较不同的方法（例如，总结提示词的不同变体）变得更加容易。
-
测试可恢复性。 只有当关键信息仍然可访问时，上下文压缩才有用。包含针对性测试，以验证代理在压缩后既能继续朝着其原始目标前进，又能在需要时恢复特定细节（例如，“大海捞针”场景，其中关键事实被总结掉，但稍后必须被检索出来）。
-
监控目标偏移（goal drift）。 最隐蔽的故障模式是代理在总结后失去了对用户意图的追踪。这可能表现为代理在总结后的下一轮中停下来要求澄清，或者错误地宣布任务已完成。对预期任务更微妙的偏离可能更难归因于总结；在样本数据集上强制进行频繁的总结可能有助于暴露这些故障。
Deep Agents 框架的所有功能都是开源的。尝试最新版本，并告诉我们哪些压缩策略最适合您的用例！
相关文档
- Agent Builder 记忆系统构建方法；关联理由：上下游；说明：该文展示了 Deep Agents 在 Agent Builder 中的落地，并解释了摘要与工具卸载等上下文工程能力如何支撑记忆系统。
- Agent Builder 中的记忆使用方法；关联理由：解说；说明：该文从使用视角补充了 Deep Agents 文件系统记忆与上下文压缩机制在实际任务中的操作方式。