Agent 上下文压缩技术让智能体在长任务中保留“有效注意力”本文介绍 AI Agent 为什么需要上下文压缩、常见的压缩方法以及开源工具 Headroom 的基本原理、适用场景与局限。1. 从一个常见现象开始使用编码智能体完成大型项目时可能会出现这样的过程Agent 读取项目说明和代码搜索几十个文件得到大量匹配结果执行测试终端返回数千行日志修改失败后重新分析又产生新的计划和工具输出会话越来越长Agent 开始遗忘约束、重复读取文件甚至偏离原任务。这并不一定是模型的推理能力突然下降。一个重要原因是真正有用的信息被大量重复内容和低价值细节淹没了。Agent 每执行一步通常都会产生新的上下文用户需求、系统规则和历史对话搜索结果、网页内容和 RAG 检索片段文件、代码、JSON 数据和数据库查询结果终端日志、报错堆栈和测试报告Agent 自己生成的计划、中间结论与工具调用记录。因此长上下文窗口并不能自动解决所有问题。窗口再大如果其中大部分是噪声模型仍然需要在大量信息中寻找少数关键线索。1.1 Agent 的上下文为什么增长得特别快传统聊天应用主要是“用户提问—模型回答”而 Agent 会在两次模型调用之间主动执行工具。工具输出又会成为下一轮模型输入形成不断增长的循环用户目标 → 模型规划 → 调用工具 → 返回大量结果 ↑ ↓ └───── 模型继续判断并调用新工具 ─────┘例如为了修复一个程序错误Agent 第一次搜索得到 200 条匹配结果第二次测试产生 3,000 行日志第三次又读取 10 个完整文件。每一步单独看都合理多轮累积后却可能形成数万 token。用户真正的任务约束可能只有几百字一次普通测试的成功日志就可能远远超过它。1.2 上下文窗口、上下文管理与长期记忆三个概念经常被混在一起但它们解决的问题不同概念解决的问题类比上下文窗口模型单次最多能接收多少信息书桌有多大上下文管理当前任务应该把哪些信息放到模型面前书桌上摆哪些资料长期记忆跨任务保存什么并在未来何时取回书架或档案室上下文窗口变大只相当于换了一张更大的书桌。如果把旧文件、重复日志和无关资料全部堆在桌面上工作并不会自动变得高效。上下文压缩属于上下文管理的重要手段关注的是“当前这一轮真正需要给模型看什么”。2. 什么是 Agent 上下文压缩Agent 上下文压缩是指在信息进入大语言模型之前对上下文进行筛选、裁剪、重写或结构化处理在尽量保留任务关键信息的同时减少 token 数量。它的目标不是单纯追求“文本越短越好”而是在三个指标之间取得平衡压缩效果 f ( token 减少量 , 任务质量 , 处理开销 ) \text{压缩效果}f(\text{token 减少量},\ \text{任务质量},\ \text{处理开销})压缩效果f(token减少量,任务质量,处理开销)假设测试程序产生了 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 压缩可以发生在不同层次从粒度上看上下文压缩大致可以分成三层消息级压缩删除过期对话、失败分支或低价值工具消息片段级压缩从文档、代码搜索结果或 RAG 片段中选择相关部分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再把压缩后的消息发送给原有模型客户端。下面是根据官方文档简化后的结构示例fromheadroomimportcompress messages[{role:user,content:分析下面的测试结果},{role:user,content:very_long_test_log}]resultcompress(messages,model目标模型名称)compressed_messagesresult.messagesprint(节省 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% tokenREADME 展示的一个日志案例从 10,144 token 压缩到 1,260 token并仍能定位其中的FATAL错误。官方文档还列出了一组场景案例场景压缩前 token压缩后 token项目方报告的节省比例代码搜索结果17,7651,40892%SRE 故障排查65,6945,11892%代码库探索78,50241,25447%GitHub Issue 分类54,17414,76173%这些场景之间的差异本身很有启发结构重复、噪声较多的日志和搜索结果通常更容易压缩代码库探索需要保留更多结构与实现因此压缩空间可能更小。这些数字能够说明工具的设计目标但不应理解为所有任务都能获得相同收益。实际结果取决于原始上下文的冗余程度数据类型和所选压缩器压缩预算与阈值任务是否依赖容易被删除的细节压缩本身带来的计算与存储开销。截至本文整理时Headroom 更适合作为一个快速演进的开源工程项目来观察和试验。其仓库基准不能替代针对具体任务的独立评测也不能直接等同于经过同行评审论文验证的普遍结论。从使用场景看Headroom 更适合工具输出、日志、搜索结果和 RAG 片段较多的长链路任务。对于依赖精确数值、完整条款或逐字引用的任务应采用更保守的策略因为可逆取回机制并不能保证 Agent 一定会发现缺失信息并正确取回原文。10. 总结Agent 的能力不仅取决于模型也取决于模型在每一步能够看到什么。长上下文窗口扩大了信息容量却没有自动解决冗余、位置偏差、成本和注意力分散问题。上下文压缩的核心是提高进入模型的信息密度。Headroom 将结构感知压缩、缓存对齐和可逆取回组合在一起为日志、JSON、代码和 RAG 等 Agent 常见内容提供了较完整的工程方案。它展示了一种值得关注的方向未来的 Agent 不应被动接收不断膨胀的历史而应主动管理自己的上下文预算。与此同时压缩是一种有损决策。判断一个压缩系统是否有效必须同时观察 token、质量、延迟、成本和恢复能力不能只依据压缩率或项目展示案例得出结论。参考资料开源项目与官方文档Headroom GitHubhttps://github.com/headroomlabs-ai/headroomHeadroom 官方文档https://headroom-docs.vercel.app/docsHeadroom 项目主页https://headroomlabs.ai/Microsoft LLMLingua GitHubhttps://github.com/microsoft/LLMLinguaLLMLingua 系列项目主页https://www.llmlingua.com/论文Jiang et al.LLMLingua: Compressing Prompts for Accelerated Inference of Large Language Models. EMNLP 2023https://aclanthology.org/2023.emnlp-main.825/Jiang et al.LongLLMLingua: Accelerating and Enhancing LLMs in Long Context Scenarios via Prompt Compression. ACL 2024https://aclanthology.org/2024.acl-long.91/Pan et al.LLMLingua-2: Data Distillation for Efficient and Faithful Task-Agnostic Prompt Compression. ACL Findings 2024https://aclanthology.org/2024.findings-acl.57/视频YouTubeHeadroom — A Context Optimization Layer for LLM Applicationshttps://www.youtube.com/watch?vUOWSHg18cL0YouTubeHeadroom — Cut Your AI Agent’s Tokens by 90%开源工具演示https://www.youtube.com/watch?v03vi4ApFIZE哔哩哔哩LLMLingua——压缩 Prompt构造 LLMs 的语言https://www.bilibili.com/video/BV19K41187Ny/哔哩哔哩解构上下文压缩的总结与裁剪机制https://www.bilibili.com/video/BV1dH4xz7E1u/资料核对日期2026 年 7 月 19 日。Headroom 仍在快速更新具体命令、兼容范围和项目数据应以其最新官方文档为准。