Headroom SharedContext API参考：put、get、entry、stats全方法详解

Headroom SharedContext API参考put、get、entry、stats全方法详解【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom在多智能体Multi-Agent协作中Agent 之间交接上下文时往往会原样重放全部内容token 成本成倍增长。Headroom 的SharedContext就是为此设计的压缩式共享上下文组件put()时自动压缩、get()时返回压缩版、需要细节再取原文、stats()汇总 token 节省量。本文将 SharedContext 的全部方法逐一讲透帮助新手用 3 行代码就能搭起多 Agent 上下文压缩管道通常可减少80% 左右的交接 token为什么多智能体交接需要上下文压缩想象一个典型的流程研究员 Agent 产出一大份调研结果交给编码 Agent 时整份文本被重新塞进提示词。这份上下文里 90% 的信息对下游是冗余的而你却要为它全额付费。Headroom 的解决方案把传递中的上下文当作一次压缩请求处理——写入时压缩存档、读取时默认拿压缩版、按需取回原文。压缩管道与 Headroom 代理服务器Proxy完全同源无需部署任何额外服务。官方文档对该组件的定位见 docs/content/docs/shared-context.mdx实现源码在 headroom/shared_context.py。快速上手3行代码建立压缩共享上下文安装后pip install headroomPython 端只需 3 行from headroom import SharedContext ctx SharedContext() ctx.put(research, big_research_output, agentresearcher) # 存入并自动压缩 summary ctx.get(research) # 拿到压缩版约小 80% full ctx.get(research, fullTrue) # 需要细节时取回原文TypeScript 端有对等实现 sdk/typescript/src/shared-context.ts多 Agent 完整示例见 sdk/typescript/examples/shared-context-multi-agent.ts。put() 方法写入即自动压缩put(key, content, *, agentNone)是唯一会触发压缩的方法源码位于 headroom/shared_context.py#L91-L142。参数说明key上下文命名如research_findings同 key 再次 put 视为覆盖更新content待存储并压缩的字符串内容agent可选标记来源 Agent便于追踪交接链路返回值是一个ContextEntry对象写入瞬间即可读到压缩效果entry ctx.put(findings, big_json_output, agentresearcher) entry.original_tokens # 20,000 entry.compressed_tokens # 4,000 entry.savings_percent # 80.0 entry.transforms # [router:json:0.20] 记录了实际应用的转换器get() 方法默认压缩版按需取回全文get(key, *, fullFalse)是读取入口L144-L168三种典型情形compressed ctx.get(findings) # 压缩版约 4K tokens original ctx.get(findings, fullTrue) # 原文约 20K tokens missing ctx.get(nonexistent) # 返回 None未命中或已过期关键机制超过ttl的条目在读取时会被顺带清理并返回None所以读到 None不代表没存过可能是过期了。get_entry() 方法完整条目元数据一览get_entry(key)返回完整的ContextEntryheadroom/shared_context.py#L170-L179除了内容本体还能拿到全部元数据字段含义key/agent条目名称与来源 Agentoriginal/compressed原文与压缩版内容original_tokens/compressed_tokens压缩前后 token 数savings_percent节省百分比属性自动计算timestamp写入时间戳TTL 判断依据transforms本次压缩应用的转换器列表做交接审计、调试压缩效果时用get_entry()比get()信息量大得多。keys() 与 clear()列出键与安全清理keys()L181-L185列出所有未过期的 key返回列表。过期条目不会出现在结果中。clear()清空全部条目适合会话结束时释放内存L204-L207。print(ctx.keys()) # [research, findings] ctx.clear() # 全部移除stats() 方法聚合 token 节省统计stats()L187-L202返回SharedContextStats是衡量这套多 Agent 管道到底省了多少钱的核心接口stats ctx.stats() stats.entries # 3活跃条目数 stats.total_original_tokens # 60,000 stats.total_compressed_tokens# 12,000 stats.total_tokens_saved # 48,000 stats.savings_percent # 80.0注意它只统计未过期条目且空上下文时savings_percent安全返回0.0而不会除零。社区整体的 Headroom token 节省规模可参考下图的仪表盘效果构造参数model、ttl 与 max_entries 详解SharedContext(model..., ttl..., max_entries...)L79-L89提供三个构造参数默认值已可直接使用参数默认值作用modelclaude-sonnet-4-5-20250929仅用于 token 计数路由不影响模型调用ttl36001 小时条目存活时间秒过期即失效max_entries100容量上限写满时自动淘汰最旧条目 一个值得注意的细节当容量已满时覆盖已有 key 的 put 不会触发淘汰——只有真正新增条目才会挤掉最旧的一条。这一行为有专门的回归测试保障见 tests/test_shared_context.py 中的test_updating_existing_key_at_capacity_does_not_evict。多 Agent 框架集成CrewAI / LangGraph / OpenAI Agents SDKSharedContext 与框架无关本质就是put get任何上下文发生移动的节点都能接入CrewAI——任务完成后把产出存入下游任务读压缩版ctx.put(findings, researcher_task.output.raw) coder_context ctx.get(findings)LangGraph——节点间通过压缩摘要传递状态细节按需取回def researcher_node(state): ctx.put(research, do_research()) return {research_summary: ctx.get(research)} def coder_node(state): full ctx.get(research, fullTrue) # 需要时再拿全量 return {code: write_code(full)}三种框架的完整写法可对照 wiki/shared-context.md。工作原理压缩管道幕后机制put()内部调用的是headroom.compress()——与 Headroom 代理服务器同一条压缩管道headroom/compress.py。内容会被路由器分发到最合适的压缩器内容类型压缩器典型压缩率JSON 数组SmartCrusher70%–95%代码CodeCompressorAST 感知依结构而定自然语言文本KompressModernBERT或直通依信息密度而定原文始终保留在内存中保证get(fullTrue)永远能无损取回——压缩只影响传递成本不影响信息完整性✅相关资源资源路径核心实现headroom/shared_context.py官方文档docs/content/docs/shared-context.mdxWiki 详解wiki/shared-context.mdTypeScript SDKsdk/typescript/src/shared-context.ts单元测试tests/test_shared_context.py从put写入压缩、get分级读取、get_entry元数据审计到stats量化节省效果SharedContext 用 6 个轻量方法覆盖了多 Agent 上下文共享的完整生命周期。如果你的多智能体系统正被交接 token 税困扰这就是最省事的解法。【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考