By Chester Curme and Mason Daugherty作者：Chester Curme 和 Mason Daugherty
As the addressable task length of AI agents continues to grow, effective context management becomes critical to prevent context rot and to manage LLMs’ finite memory constraints.随着 AI 智能体可处理任务长度的不断增加，有效的上下文管理对于防止上下文退化以及应对大语言模型（LLM）有限的内存约束变得至关重要。
The Deep Agents SDK is LangChain’s open source, batteries-included agent harness. It provides an easy path to build agents with the ability to plan, spawn subagents, and work with a filesystem to execute complex, long-running tasks. Because these sorts of tasks can generally exceed models’ context windows, the SDK implements various features that facilitate context compression.Deep Agents SDK 是 LangChain 推出的开源、功能完备的智能体开发框架。它为构建智能体提供了一条便捷路径，使其具备规划、生成子智能体以及通过文件系统执行复杂、长周期任务的能力。由于此类任务通常会超出模型的上下文窗口，该 SDK 实现了一系列有助于上下文压缩的功能。
Context compression refers to techniques that reduce the volume of information in an agent's working memory while preserving the details relevant to completing the task. This might involve summarizing previous interactions, filtering out stale information, or strategically deciding what to retain and what to discard.上下文压缩是指在减少智能体工作内存中信息量的同时，保留完成任务所需细节的技术。这可能涉及总结之前的交互、过滤掉陈旧信息，或策略性地决定保留哪些内容、舍弃哪些内容。
Deep Agents implements a filesystem abstraction that allows agents to perform operations such as listing, reading, and writing files, as well as search, pattern matching, and file execution. Agents use the filesystem to search and retrieve offloaded content as needed.Deep Agents 实现了一种文件系统抽象，允许智能体执行列出、读取、写入文件，以及搜索、模式匹配和文件执行等操作。智能体利用文件系统根据需要搜索并检索已卸载的内容。
Deep Agents implements three main compression techniques, triggered at different frequencies:Deep Agents 实现了三种主要的压缩技术，它们会在不同的频率下触发：
- Offloading large tool results: We offload large tool responses to the filesystem whenever they occur.卸载大型工具结果：每当出现大型工具响应时，我们都会将其卸载到文件系统中。
- Offloading large tool inputs: When the context size crosses a threshold, we offload old write/edit arguments from tool calls to the filesystem.卸载大型工具输入：当上下文大小超过阈值时，我们会将工具调用中旧的写入/编辑参数卸载到文件系统中。
- Summarization: When the context size crosses the threshold, and there is no more context eligible for offloading, we perform a summarization step to compress the message history.摘要总结：当上下文大小超过阈值，且没有更多可供卸载的上下文时，我们会执行摘要总结步骤来压缩消息历史记录。
To manage context limits, the Deep Agents SDK triggers these compression steps at threshold fractions of the model's context window size. (Under the hood, we use LangChain's model profiles to access the token threshold for a given model.)为了管理上下文限制，Deep Agents SDK 会在模型上下文窗口大小的阈值比例处触发这些压缩步骤。（在底层，我们使用 LangChain 的模型配置文件来获取给定模型的 Token 阈值。）
Offloading large tool results卸载大型工具结果
Responses from tool invocations (e.g., the result of reading a large file or an API call) can exceed a model's context window. When Deep Agents detects a tool response exceeding 20,000 tokens, it offloads the response to the filesystem and substitutes it with a file path reference and a preview of the first 10 lines. Agents can then re-read or search the content as needed.工具调用的响应（例如读取大文件或 API 调用的结果）可能会超出模型的上下文窗口。当 Deep Agents 检测到工具响应超过 20,000 个 Token 时，它会将响应卸载到文件系统，并用文件路径引用和前 10 行预览来替换它。智能体随后可以根据需要重新读取或搜索这些内容。
Offloading large tool inputs卸载大型工具输入
File write and edit operations leave behind tool calls containing the complete file content in the agent's conversation history. Since this content is already persisted to the filesystem, it's often redundant. As the session context crosses 85% of the model’s available window, Deep Agents will truncate older tool calls, replacing them with a pointer to the file on disk and reducing the size of the active context.文件写入和编辑操作会在智能体的对话历史中留下包含完整文件内容的工具调用。由于这些内容已经持久化到文件系统中，它们往往是冗余的。当会话上下文超过模型可用窗口的 85% 时，Deep Agents 将截断较旧的工具调用，用指向磁盘上文件的指针替换它们，从而减小活动上下文的大小。
Summarization摘要总结
When offloading no longer yields sufficient space, Deep Agents falls back to summarization. This process has two components:当卸载操作无法再腾出足够的空间时，Deep Agents 会退而求其次使用摘要总结。此过程包含两个部分：
- In-context summary: An LLM generates a structured summary of the conversation—including session intent, artifacts created, and next steps—which replaces the full conversation history in the agent's working memory. (See the Deep Agents summarization prompt.)上下文内摘要：大语言模型生成对话的结构化摘要（包括会话意图、已创建的工件和后续步骤），该摘要将替换智能体工作内存中的完整对话历史。（请参阅 Deep Agents 摘要提示词。）
- Filesystem preservation: The complete, original conversation messages are written to the filesystem as a canonical record.文件系统保存：完整、原始的对话消息作为规范记录被写入文件系统。
This dual approach ensures the agent maintains awareness of its goals and progress (via the summary) while preserving the ability to recover specific details when needed (via filesystem search). See an example in this trace, where the model uses the read_file tool to fetch previously offloaded messages.这种双重方法确保智能体既能保持对目标和进展的感知（通过摘要），又能保留在需要时恢复特定细节的能力（通过文件系统搜索）。请参阅此跟踪记录中的示例，模型使用 read_file 工具获取了之前卸载的消息。
What this looks like in practice实际应用效果
While the techniques above provide the machinery for context management, how do we know they're actually working? Runs on real-world tasks, as captured in benchmarks such as terminal-bench, may trigger context compression sporadically, making it difficult to isolate their impact.虽然上述技术提供了上下文管理的机制，但我们如何知道它们是否真的有效呢？在 terminal-bench 等基准测试中运行真实任务时，上下文压缩可能会零星触发，这使得很难单独评估其影响。
We’ve found it useful to increase the signal of individual features of the harness by engaging them more aggressively on benchmark datasets. For example, while triggering summarization at 10 - 20% of the available context window may lead to suboptimal overall performance, it produces significantly more summarization events. This allows for different configurations (e.g., variations of your implementation) to be compared. For example, by forcing the agent to summarize frequently, we could identify how simple changes to the deepagents summarization prompt, in which we added dedicated fields for the session intent and next steps, help improve performance.我们发现，通过在基准数据集上更激进地应用这些功能，可以有效增强单个功能特性的信号。例如，虽然在可用上下文窗口的 10% - 20% 处触发摘要总结可能会导致整体性能欠佳，但它会产生更多的摘要事件。这使得不同的配置（例如您实现的变体）可以进行比较。例如，通过强制智能体频繁总结，我们可以确定对 Deep Agents 摘要提示词所做的简单修改（例如添加会话意图和后续步骤的专用字段）如何帮助提升性能。
Figure: Token usage over time in sample runs of Claude Sonnet 4.5 on terminal-bench-2 (gray lines show all runs; colored lines highlight two specific examples). The green line shows a dramatic token drop around turn 20 when a summarization event compresses the conversation history. The orange line shows a smaller reduction around turn 40 when a large file write tool call is evicted from context. By triggering compression at 25% of the context window (rather than the Deep Agents default of 85%), we generate more events to study.图：Claude Sonnet 4.5 在 terminal-bench-2 上运行样本的 Token 使用情况随时间的变化（灰色线条显示所有运行情况；彩色线条突出显示了两个特定示例）。绿线显示在第 20 轮左右出现剧烈的 Token 下降，此时摘要事件压缩了对话历史。橙线显示在第 40 轮左右出现较小的缩减，此时一个大型文件写入工具调用被从上下文中移除。通过在上下文窗口的 25% 处（而不是 Deep Agents 默认的 85%）触发压缩，我们生成了更多可供研究的事件。
Targeted evals针对性评估
The Deep Agents SDK maintains a set of targeted evaluations designed to isolate and validate individual context-management mechanisms. These are deliberately small tests that make specific failure modes obvious and debuggable.Deep Agents SDK 维护了一套针对性评估方案，旨在隔离和验证单个上下文管理机制。这些是刻意设计的小型测试，使得特定的故障模式变得明显且易于调试。
The goal of these evals is not to measure broad task-solving ability, but to ensure that the agent’s harness does not get in the way of certain tasks. For example:这些评估的目标不是衡量广泛的任务解决能力，而是确保智能体的框架不会阻碍特定任务的执行。例如：
- Did summarization preserve the agent’s objective? Some evals deliberately trigger summarization mid-task and then check whether the agent continues. This ensures that summarization preserves not only agent state but also its trajectory.摘要总结是否保留了智能体的目标？一些评估会刻意在任务中途触发摘要总结，然后检查智能体是否继续执行。这确保了摘要总结不仅保留了智能体的状态，还保留了其执行轨迹。
- Can the agent recover information that was summarized away? Here we embed a “needle-in-the-haystack” fact early in the conversation, force a summarization event, and then require the agent to recall that fact later to complete the task. The fact is not present in the active context after summarization and must be recovered via filesystem search.智能体能否恢复被摘要掉的信息？在这里，我们在对话早期嵌入一个“大海捞针”式的事实，强制触发摘要总结事件，然后要求智能体稍后回忆该事实以完成任务。该事实在摘要总结后的活动上下文中不存在，必须通过文件系统搜索来恢复。
These targeted evals act as integration tests for context management: they don’t replace full benchmark runs, but they significantly reduce iteration time and make failures attributable to specific compression mechanisms rather than overall agent behavior.这些针对性评估充当了上下文管理的集成测试：它们不能取代完整的基准测试运行，但能显著减少迭代时间，并使故障归因于特定的压缩机制，而不是整体的智能体行为。
Guidance指导建议
When evaluating your own context compression strategies, we’d emphasize:在评估您自己的上下文压缩策略时，我们建议重点关注：
- Start with real-world benchmarks, then stress-test individual features. Run your harness on representative tasks first to establish baseline performance. Then, artificially trigger compression more aggressively (e.g., at 10-20% of context instead of 85%) to generate more compression events per run. This amplifies the signal from individual features, making it easier to compare different approaches (e.g. variations in your summarization prompt).从真实世界的基准测试开始，然后对单个功能进行压力测试。首先在代表性任务上运行您的框架以建立基准性能。然后，更激进地人工触发压缩（例如在上下文的 10-20% 而不是 85% 处），以在每次运行中生成更多的压缩事件。这会放大单个功能的信号，从而更容易比较不同的方法（例如摘要提示词的变体）。
- Test recoverability. Context compression is only useful if critical information remains accessible. Include targeted tests that verify agents can both continue toward their original goal after compression and recover specific details when needed (e.g., needle-in-the-haystack scenarios where a key fact is summarized away but must be retrieved later).测试可恢复性。上下文压缩只有在关键信息仍然可访问时才有用。包含针对性测试，验证智能体在压缩后既能继续朝着原始目标前进，又能在需要时恢复特定细节（例如“大海捞针”场景，即关键事实被摘要掉但稍后必须被检索出来）。
- Monitor for goal drift. The most insidious failure mode is an agent that loses track of the user's intent after summarization. This may manifest as the agent completing in the turn after summarization to ask for clarification, or to mistakenly declare the task complete. More subtle deviations from the intended task may be harder to attribute to summarization; forcing frequent summarization on sample datasets may help surface these failures.监控目标漂移。最隐蔽的故障模式是智能体在摘要总结后丢失了对用户意图的追踪。这可能表现为智能体在摘要总结后的那一轮询问澄清，或者错误地宣布任务完成。更微妙的偏离预期任务的行为可能更难归因于摘要总结；在样本数据集上强制频繁进行摘要总结可能有助于发现这些故障。
All features of the Deep Agents harness are open source. Try out the latest version and let us know what compression strategies work best for your use cases!Deep Agents 框架的所有功能都是开源的。请尝试最新版本，并让我们知道哪些压缩策略最适合您的用例！
.png)
