Agent 上下文压缩技术：让智能体在长任务中保留“有效注意力”

本文介绍 AI Agent 为什么需要上下文压缩、常见的压缩方法，以及开源工具 Headroom 的基本原理、适用场景与局限。

1. 从一个常见现象开始

使用编码智能体完成大型项目时，可能会出现这样的过程：

1. Agent 读取项目说明和代码；
2. 搜索几十个文件，得到大量匹配结果；
3. 执行测试，终端返回数千行日志；
4. 修改失败后重新分析，又产生新的计划和工具输出；
5. 会话越来越长，Agent 开始遗忘约束、重复读取文件，甚至偏离原任务。

这并不一定是模型的推理能力突然下降。一个重要原因是：真正有用的信息，被大量重复内容和低价值细节淹没了。

Agent 每执行一步，通常都会产生新的上下文：

• 用户需求、系统规则和历史对话；
• 搜索结果、网页内容和 RAG 检索片段；
• 文件、代码、JSON 数据和数据库查询结果；
• 终端日志、报错堆栈和测试报告；
• Agent 自己生成的计划、中间结论与工具调用记录。

因此，长上下文窗口并不能自动解决所有问题。窗口再大，如果其中大部分是噪声，模型仍然需要在大量信息中寻找少数关键线索。

1.1 Agent 的上下文为什么增长得特别快

传统聊天应用主要是“用户提问—模型回答”，而 Agent 会在两次模型调用之间主动执行工具。工具输出又会成为下一轮模型输入，形成不断增长的循环：

用户目标 → 模型规划 → 调用工具 → 返回大量结果
   ↑                                  ↓
   └───── 模型继续判断并调用新工具 ─────┘

例如，为了修复一个程序错误，Agent 第一次搜索得到 200 条匹配结果，第二次测试产生 3,000 行日志，第三次又读取 10 个完整文件。每一步单独看都合理，多轮累积后却可能形成数万 token。用户真正的任务约束可能只有几百字，一次普通测试的成功日志就可能远远超过它。

1.2 上下文窗口、上下文管理与长期记忆

三个概念经常被混在一起，但它们解决的问题不同：

概念	解决的问题	类比
上下文窗口	模型单次最多能接收多少信息	书桌有多大
上下文管理	当前任务应该把哪些信息放到模型面前	书桌上摆哪些资料
长期记忆	跨任务保存什么，并在未来何时取回	书架或档案室

上下文窗口变大，只相当于换了一张更大的书桌。如果把旧文件、重复日志和无关资料全部堆在桌面上，工作并不会自动变得高效。上下文压缩属于上下文管理的重要手段，关注的是“当前这一轮真正需要给模型看什么”。

2. 什么是 Agent 上下文压缩

Agent 上下文压缩，是指在信息进入大语言模型之前，对上下文进行筛选、裁剪、重写或结构化处理，在尽量保留任务关键信息的同时减少 token 数量。

它的目标不是单纯追求“文本越短越好”，而是在三个指标之间取得平衡：

$$\text{压缩效果}=f(\text{token 减少量},\text{任务质量},\text{处理开销})$$

假设测试程序产生了 10,000 行日志，其中 9,900 行是重复的正常请求，真正有价值的内容只有：

ERROR: database connection timeout
Retry 1 failed
Retry 2 failed
FATAL: connection pool exhausted

直接把全部日志发给模型既浪费 token，也可能削弱模型对错误行的关注。更合理的做法是保留异常、状态变化以及少量必要的上下文，并记录原始内容的位置，以便需要时重新读取。

从直觉上看，压缩的前提是输入存在冗余。自然语言中有重复表达，日志中有成千上万条相同的成功记录，代码搜索结果中可能重复出现同一定义。压缩器希望删除这些低信息密度内容，同时保留能够改变模型判断的信号。

但是，“重要”不是文本的固定属性。同一条数据库记录，对“统计订单平均金额”可能无关紧要，对“定位唯一一笔欺诈交易”却可能是决定性证据。因此，压缩不能只看文本本身，还要结合当前任务、数据结构以及后续是否能够取回原文。

3. 为什么不能只依赖更大的上下文窗口

3.1 成本与延迟仍然存在

模型每轮都要处理输入上下文。上下文越长，通常意味着更高的输入成本和更长的处理时间。Agent 又会反复调用模型，因此少量冗余可能在多轮执行中不断累积。

3.2 关键信息可能“埋在中间”

长文本中的信息并不会被模型同等利用。LongLLMLingua 等研究关注了长上下文中的位置偏差和“Lost in the Middle”问题：关键信息的密度与位置都可能影响下游任务表现。压缩有时不仅能降低成本，还能通过提高有效信息密度帮助模型定位关键证据。

3.3 Agent 的上下文比普通问答更复杂

普通问答主要处理自然语言，而 Agent 上下文中包含 JSON、代码、日志和工具调用结构。若使用普通摘要模型粗暴重写，可能删除字段、破坏语法，或者把工具调用与工具结果拆开，导致后续执行失败。

3.4 上下文过长还可能影响行为一致性

Agent 的早期上下文中通常包含权限边界、代码规范和验收标准。随着大量工具结果进入会话，这些规则在整个上下文中的占比持续下降。模型可能开始重复已经完成的步骤，忽略“不修改接口”等限制，或者依据新的局部信息推翻已经验证过的结论。

因此，上下文压缩不仅是成本优化，也与 Agent 的可靠性有关。不过，这不代表“压得越短越可靠”：如果压缩器恰好删掉关键约束或证据，同样会造成错误。

4. 常见的上下文压缩方法

方法	基本思路	优点	主要风险
截断	只保留最新或最前面的内容	简单、速度快	可能直接删除关键证据
滑动窗口	保留最近若干轮交互	适合连续对话	较早但仍有效的约束会丢失
摘要	将历史内容改写为短摘要	可读性较好	摘要可能遗漏或改写事实
检索式压缩	根据当前问题保留相关片段	针对性强	检索错误会造成信息缺失
Token 级压缩	判断每个词或 token 的重要性	压缩率较高	输出可能不符合自然语言习惯
结构感知压缩	按 JSON、代码、日志等结构分别处理	更适合 Agent 工具输出	需要针对不同数据类型设计规则
可逆压缩	压缩内容，但保留原文索引并允许按需取回	在节省 token 的同时保留恢复路径	增加存储和工具调用机制

微软开源的 LLMLingua 是提示压缩领域的代表性工作。它使用较小的模型判断内容的重要程度，尽量删除非必要 token。后续的 LongLLMLingua 面向长上下文和 RAG 场景，LLMLingua-2 则将压缩建模为 token 分类任务。

Agent 场景在此基础上又提出了新的要求：不仅要压缩自然语言，还要理解日志、JSON 和代码结构，并允许 Agent 在发现信息不足时找回原文。Headroom 正是面向这一问题设计的工程工具。

4.1 压缩可以发生在不同层次

从粒度上看，上下文压缩大致可以分成三层：

1. 消息级压缩：删除过期对话、失败分支或低价值工具消息；
2. 片段级压缩：从文档、代码搜索结果或 RAG 片段中选择相关部分；
3. Token 级压缩：在单段文本内部继续删除低价值词语或句子。

实际系统通常组合多种方法。例如，先从 100 个检索片段中选出 10 个，再对每个片段做文本压缩，最后把较早的对话整理成任务状态。只使用一种算法很难覆盖 Agent 的全部上下文。

4.2 压缩、摘要和 RAG 有什么区别

技术	核心动作	主要目标
摘要	将一段已有文本重新表述得更短	保留整体含义
RAG	根据问题从外部文档集合中检索片段	将外部知识加入上下文
上下文压缩	对准备进入模型的内容进行选择、删除、改写或结构化	在预算内提高有效信息密度

三者可以组合使用。RAG 负责“找到可能相关的材料”，压缩器负责“减少召回结果中的重复与噪声”，摘要则可以把较早的执行过程整理为较短状态。因此，上下文压缩不是 RAG 的替代品，而是对模型输入管线的进一步治理。

5. Headroom 是什么

Headroom 是一个采用 Apache-2.0 许可证的开源上下文优化工具。它位于 Agent 应用与大语言模型服务之间，在内容发送给模型前压缩工具输出、日志、文件、RAG 片段和对话历史。

它提供多种接入方式：

• 作为 Python 或 TypeScript 库，在应用中调用压缩函数；
• 作为代理服务，在请求进入模型服务前统一处理；
• 通过 MCP 暴露压缩、原文取回和统计工具；
• 包装部分编码智能体，在尽量少改动原有工作流的情况下接入。

Headroom 的核心流程可以概括为：

Agent 产生上下文
        ↓
稳定可缓存的消息前缀（CacheAligner）
        ↓
识别内容类型（ContentRouter）
        ↓
选择 JSON、代码或自然语言压缩器
        ↓
保存原文并生成可取回引用（CCR）
        ↓
将压缩后的上下文发送给大语言模型

从系统位置看，Headroom 不替代大语言模型，也不负责决定 Agent 的业务流程。它更像一个位于“信息入口”的中间层：Agent 原本准备发送给模型的内容先经过 Headroom，压缩后的消息再交给原模型处理。

这一位置使它能够统一处理多种来源的数据，但也意味着 Headroom 的判断会直接影响模型能够看到的证据。如果压缩策略配置不当，即使主模型能力很强，也无法利用已经被隐藏的细节。

6. Headroom 如何压缩不同内容

6.1 ContentRouter：先判断内容，再选择压缩方式

日志、JSON、代码和自然语言不能采用同一种删除规则。ContentRouter 会先识别内容类型，再把内容交给相应的压缩器。这种设计比统一截断更符合 Agent 的实际数据特征。

6.2 SmartCrusher：压缩 JSON 和结构化数据

对于大型 JSON 数组，逐条发送所有记录通常没有必要。结构感知压缩可以优先保留：

• 与用户问题相关的记录；
• 错误项和异常值；
• 能表示整体分布的样本；
• 必要的字段名和结构信息。

例如，一个接口返回 5,000 条订单，用户只询问“支付失败且金额异常的订单”。理想的压缩结果应保留失败记录、异常金额和必要字段，而不是机械保留前 100 条数据。

假设原始数组中包含数千条近似的成功记录，但只有一条异常：

[
  {"id": 1001, "status": "success", "amount": 58.0},
  {"id": 1002, "status": "success", "amount": 61.0},
  {"id": 1003, "status": "failed", "amount": 9999.0}
]

结构感知压缩可以用统计信息和代表性样本描述正常部分，同时保留第三条异常记录。与直接截断相比，它更有机会保留位于数组中部或尾部的重要异常。

6.3 CodeCompressor：理解代码结构

代码压缩不能随意删除字符。Headroom 的代码压缩器采用抽象语法树等结构信息，重点保留导入、类型、函数签名和关键代码结构。这样，Agent 可以先了解文件的整体接口；当某个函数成为分析重点时，再读取完整实现。

例如，阅读一个 1,000 行的服务类时，第一轮可能只需知道类名、公开方法、参数和依赖关系，不需要同时看到每个方法的完整实现。结构感知压缩可以把方法体折叠成概要，同时保留支持导航和调用关系分析的“骨架”。如果任务转为定位某个方法内部的并发错误，则必须再取回完整实现，不能继续依赖骨架作结论。

6.4 文本压缩模型：提高自然语言的信息密度

对于文档、网页和一般文本，Headroom 可使用专门的文本压缩模型删除冗余表达，保留更重要的内容。其思路与 LLMLingua 系列相似，但 Headroom 更强调与 Agent 工具链的整体集成。

自然语言压缩通常比日志去重更困难，因为一句看似普通的限定语可能改变结论。例如，“仅在管理员确认后执行”中的“仅”和“确认后”都不能删除。对于制度、合同和科研材料，应采用更保守的压缩策略，并通过任务指标验证事实是否完整保留。

6.5 CacheAligner：减少无意义的缓存失效

许多模型服务会缓存重复的提示前缀。如果每轮请求都在前部加入动态时间戳、随机标识或顺序变化的元数据，即使主体内容相同，也可能无法命中缓存。CacheAligner 尝试稳定消息前缀，从而提高提示缓存的复用机会。

需要注意，缓存优化与上下文压缩是两个不同概念：压缩减少需要发送和处理的 token，缓存优化则尽量避免重复计算相同前缀。

6.6 CCR：压缩后仍能找回原文

Headroom 将可逆机制称为 CCR。压缩器在本地保存原始内容，并向模型提供引用。当压缩结果不足以解决问题时，Agent 可以通过取回工具请求对应原文。

这种机制类似查阅一本书：第一次只给出目录和摘要；确定相关章节后，再打开原文，而不是每次都把整本书放到桌面上。

可逆压缩并不意味着没有信息损失。它只是提供了恢复路径，Agent 是否意识到需要取回、能否选对原文，仍会影响最终结果。

6.7 多智能体之间的上下文压缩

多智能体系统还会产生另一类冗余：不同子 Agent 将完整研究过程全部返回给主 Agent。主 Agent 实际需要的通常是结论、证据和未解决问题，而不是每个子 Agent 的所有中间日志。

Headroom 提供共享上下文与跨 Agent 压缩相关能力，使大型输出可以先存储，再向其他 Agent 传递压缩表示。不过，多智能体场景必须保留结果来源和证据位置，否则压缩后的结论会难以追溯。

7. Headroom 与相关方案的对比

方案	主要特点	更适合的内容	与 Headroom 的差异
简单截断	按长度删除开头或结尾	低风险、强时序对话	实现简单，但不理解内容重要性
对话摘要	用 LLM 重写历史	自然语言会话	可读性好，但可能改写事实并增加模型调用
LLMLingua 系列	学习 token 重要性并进行提示压缩	自然语言、长文档、RAG	更偏压缩算法与论文研究
RAG 重排	对召回片段重新排序和筛选	外部知识库	主要处理检索结果，不覆盖全部工具输出
Headroom	内容路由、结构感知压缩、缓存对齐和可逆取回	JSON、日志、代码、文本和 Agent 历史	更强调工程集成和多数据类型处理

Headroom 的价值并不在于发明了所有底层压缩思想，而在于把不同压缩器、代理接入、缓存优化、原文取回和监控组合成面向 Agent 的工具链。因此，介绍 Headroom 时既要看到其工程完整性，也应把它放在提示压缩和上下文管理的发展脉络中理解。

8. Headroom 的接入方式

8.1 作为应用程序库

Python 应用可以先调用 compress，再把压缩后的消息发送给原有模型客户端。下面是根据官方文档简化后的结构示例：

from headroom import compress

messages = [
    {"role": "user", "content": "分析下面的测试结果"},
    {"role": "user", "content": very_long_test_log}
]

result = compress(messages, model="目标模型名称")
compressed_messages = result.messages

print("节省 token：", result.tokens_saved)
print("压缩比例：", result.compression_ratio)

这段代码只展示调用关系。实际使用时仍需按照最新官方文档配置依赖、模型名称和模型客户端。

8.2 作为透明代理

如果不希望在每个业务模块中逐一加入压缩逻辑，可以让原应用通过 Headroom 代理访问模型服务。代理负责拦截请求、压缩上下文，再转发给模型提供方。这种方式改动较少，但上线前必须验证流式输出、工具调用、错误处理、鉴权和监控链路是否兼容。

8.3 通过 MCP 使用

Headroom 当前文档提供三个面向 MCP 客户端的主要工具：

• headroom_compress：压缩较大的内容；
• headroom_retrieve：根据引用取回原文；
• headroom_stats：查看压缩和节省情况。

这使支持 MCP 的 Agent 可以主动决定何时压缩、何时恢复。但工具是否会被正确调用，仍然取决于 Agent 的规划能力和工具描述质量。

8.4 与 Agent 框架集成

根据当前官方文档，Headroom 提供 LangChain、Agno、Strands、LiteLLM、Vercel AI SDK 等接入方式。项目更新较快，兼容范围和命令可能变化，部署时应以仓库和官方文档的当前版本为准，不宜直接照搬旧教程。

9. 项目数据应该怎样理解

Headroom 仓库当前给出的项目方数据包括：

• JSON 数据场景减少约 60%～95% token；
• 编码智能体场景减少约 15%～20% token；
• README 展示的一个日志案例从 10,144 token 压缩到 1,260 token，并仍能定位其中的 FATAL 错误。

官方文档还列出了一组场景案例：

场景	压缩前 token	压缩后 token	项目方报告的节省比例
代码搜索结果	17,765	1,408	92%
SRE 故障排查	65,694	5,118	92%
代码库探索	78,502	41,254	47%
GitHub Issue 分类	54,174	14,761	73%

这些场景之间的差异本身很有启发：结构重复、噪声较多的日志和搜索结果通常更容易压缩；代码库探索需要保留更多结构与实现，因此压缩空间可能更小。

这些数字能够说明工具的设计目标，但不应理解为所有任务都能获得相同收益。实际结果取决于：

• 原始上下文的冗余程度；
• 数据类型和所选压缩器；
• 压缩预算与阈值；
• 任务是否依赖容易被删除的细节；
• 压缩本身带来的计算与存储开销。

截至本文整理时，Headroom 更适合作为一个快速演进的开源工程项目来观察和试验。其仓库基准不能替代针对具体任务的独立评测，也不能直接等同于经过同行评审论文验证的普遍结论。

从使用场景看，Headroom 更适合工具输出、日志、搜索结果和 RAG 片段较多的长链路任务。对于依赖精确数值、完整条款或逐字引用的任务，应采用更保守的策略，因为可逆取回机制并不能保证 Agent 一定会发现缺失信息并正确取回原文。

10. 总结

Agent 的能力不仅取决于模型，也取决于模型在每一步能够看到什么。长上下文窗口扩大了信息容量，却没有自动解决冗余、位置偏差、成本和注意力分散问题。

上下文压缩的核心，是提高进入模型的信息密度。Headroom 将结构感知压缩、缓存对齐和可逆取回组合在一起，为日志、JSON、代码和 RAG 等 Agent 常见内容提供了较完整的工程方案。它展示了一种值得关注的方向：未来的 Agent 不应被动接收不断膨胀的历史，而应主动管理自己的上下文预算。

与此同时，压缩是一种有损决策。判断一个压缩系统是否有效，必须同时观察 token、质量、延迟、成本和恢复能力，不能只依据压缩率或项目展示案例得出结论。

参考资料

开源项目与官方文档

1. Headroom GitHub：https://github.com/headroomlabs-ai/headroom
2. Headroom 官方文档：https://headroom-docs.vercel.app/docs
3. Headroom 项目主页：https://headroomlabs.ai/
4. Microsoft LLMLingua GitHub：https://github.com/microsoft/LLMLingua
5. LLMLingua 系列项目主页：https://www.llmlingua.com/

论文

1. Jiang et al. LLMLingua: Compressing Prompts for Accelerated Inference of Large Language Models. EMNLP 2023：https://aclanthology.org/2023.emnlp-main.825/
2. Jiang et al. LongLLMLingua: Accelerating and Enhancing LLMs in Long Context Scenarios via Prompt Compression. ACL 2024：https://aclanthology.org/2024.acl-long.91/
3. Pan et al. LLMLingua-2: Data Distillation for Efficient and Faithful Task-Agnostic Prompt Compression. ACL Findings 2024：https://aclanthology.org/2024.findings-acl.57/

视频

1. YouTube：Headroom — A Context Optimization Layer for LLM Applications：https://www.youtube.com/watch?v=UOWSHg18cL0
2. YouTube：Headroom — Cut Your AI Agent’s Tokens by 90%（开源工具演示）：https://www.youtube.com/watch?v=03vi4ApFIZE
3. 哔哩哔哩：LLMLingua——压缩 Prompt，构造 LLMs 的语言：https://www.bilibili.com/video/BV19K41187Ny/
4. 哔哩哔哩：解构上下文压缩的总结与裁剪机制：https://www.bilibili.com/video/BV1dH4xz7E1u/

---

资料核对日期：2026 年 7 月 19 日。Headroom 仍在快速更新，具体命令、兼容范围和项目数据应以其最新官方文档为准。