AgentScope 2.0上下文压缩实战：AgentState结构与长会话优化

1. 会话与上下文压缩到底在解决什么问题做过 Agent 应用的人大概都经历过这个场景一个多轮对话跑了几十轮之后响应越来越慢费用越来越高最后直接抛出一个上下文超限的报错。这不是模型不行而是上下文窗口被撑爆了。AgentScope 2.0 把「会话管理」和「上下文压缩」单独拎出来作为一个核心模块来讲原因就在这里——它直接决定了你的 Agent 能不能长时间稳定运行。先说清楚这两个概念的关系。会话Session是 Agent 与用户之间一次完整交互的生命周期容器它记录了这轮对话里所有的消息、工具调用结果、中间状态。而上下文Context是每次真正发给大模型的那些内容它是会话的一个「切片」或者说「投影」。会话可以很长但上下文必须控制在一定长度内否则模型要么报错要么因为注意力被稀释而变傻。AgentScope 2.0 里的AgentState就是承载这一切的核心数据结构。它不只是简单的消息列表还包含了当前 Agent 的配置、记忆、工具状态等。理解AgentState的结构是理解整个上下文压缩机制的前提。很多人一上来就想着怎么压缩结果连状态里有什么都没搞清楚压着压着就把关键信息压没了。这个模块适合谁看如果你正在用 AgentScope 搭建多轮对话机器人、RAG 问答系统、或者多 Agent 协作流程并且遇到了「聊久了就崩」「成本失控」「响应变慢」这类问题那这部分内容就是为你准备的。哪怕你现在还没遇到提前理解这套机制也能帮你在架构设计阶段就避开坑。2. AgentState 的结构拆解与设计逻辑2.1 AgentState 里到底装了什么要理解压缩先得知道被压缩的对象长什么样。AgentState 在 AgentScope 2.0 中大致包含这几类信息消息历史Memory/Messages用户输入、模型回复、工具调用请求与返回这是占用 token 的大头。系统提示System Prompt角色设定、行为约束通常固定不变。工具定义Tools Schema每个工具的 JSON Schema 描述工具多了这部分也很占地方。运行时状态Runtime State当前轮次、临时变量、中间结果等。我实测下来一个中等复杂度的 Agent如果挂了 10 个工具光工具 Schema 就能吃掉两三千 token。消息历史更是随轮次线性增长。所以压缩不能只盯着消息历史看工具定义和系统提示同样有优化空间。2.2 为什么用状态对象而不是裸消息列表早期很多框架直接用一个List[Message]来管理对话简单是简单但问题很明显你没法区分哪些消息是「必须保留的」哪些是「可以丢弃的」。AgentScope 2.0 用AgentState这种结构化对象好处是每一类信息都有明确的归属和生命周期。打个比方裸消息列表就像把所有东西都堆在一个抽屉里找东西全靠翻而AgentState像是有分隔的收纳盒压缩的时候你可以精准地只动某一格不影响其他部分。这个设计上的取舍直接决定了后面压缩策略能做到多细。提示如果你是从旧版本迁移过来的注意检查你的自定义 Agent 是否直接操作了消息列表。2.0 里推荐通过 AgentState 的接口来读写绕过它直接改底层列表压缩逻辑可能会失效。2.3 状态的生命周期管理AgentState 不是一成不变的它在每一轮对话中都会经历「读取 → 追加 → 压缩 → 持久化」这样一个循环。理解这个循环很关键因为压缩发生的时机不同效果差别很大。常见的有两种时机每轮结束就压和接近阈值才压。前者能保证上下文始终精简但压缩本身有开销可能要用模型来总结频繁压缩反而费钱后者省事但容易在某一轮突然超限。AgentScope 2.0 默认走的是阈值触发这个后面会细讲。3. 上下文压缩的核心策略与选型考量3.1 压缩的本质是信息取舍很多人把上下文压缩理解成「删消息」这是最大的误区。压缩的本质是在有限 token 预算下最大化保留对后续推理有用的信息。删消息只是最粗暴的一种手段而且往往删掉的是最该留的。AgentScope 2.0 提供的压缩思路大致可以归为几类我按「信息损失程度」从低到高排一下策略做法信息损失适用场景滑动窗口只保留最近 N 轮中短程任务、闲聊摘要压缩用模型总结早期对话低长程任务、需要记忆关键信息抽取提取实体、结论、决策低结构化任务工具结果截断长返回只留摘要中工具返回超长的场景直接丢弃删掉旧消息高兜底方案选哪种取决于你的任务对「历史记忆」的依赖程度。一个查天气的 Agent滑动窗口就够了一个帮用户做多轮需求澄清的 Agent就必须上摘要压缩否则用户前面说的约束条件全丢了。3.2 为什么摘要压缩是主力方案摘要压缩之所以成为主流是因为它在信息保留和 token 节省之间取得了比较好的平衡。做法是当消息历史超过阈值时把最老的一批消息交给模型让它生成一段简洁的摘要然后用这段摘要替换掉原始消息。这里有个关键细节摘要不是随便总结而是要有针对性地保留后续可能用到的信息。比如用户提到的偏好、已经确认的决策、未完成的待办这些必须进摘要。而寒暄、重复确认、失败的尝试可以大胆丢掉。AgentScope 2.0 在实现上允许你自定义摘要的 prompt这就是给你留的调优口子。默认的摘要 prompt 是通用的但你的业务场景往往有特殊性自己改一版效果会好很多。3.3 阈值怎么定才合理阈值定得太低压缩频繁费钱且可能丢信息定得太高容易触发模型上限报错。我的经验是阈值设在模型上下文窗口的 60% 到 70% 之间。举个例子假设你用的模型上下文窗口是 128K token那压缩触发点设在 80K 左右比较稳妥。留出的 30% 到 40% 空间是给当前轮的工具返回、模型输出、以及摘要本身预留的。因为压缩动作发生时你还需要额外调用一次模型来生成摘要这次调用本身也要占上下文。注意不同模型的 token 计算方式不一样中文和英文的 token 比例也不同。别用字符数去估算一定要用对应模型的 tokenizer 实际算。我踩过这个坑按字符数估的结果和实际差了将近一倍。4. 实操在 AgentScope 2.0 中配置上下文压缩4.1 基础配置流程下面这套流程是我在实际项目里跑通的你可以直接参考。假设你已经装好了 AgentScope 2.0并且有一个能跑的基础 Agent。第一步明确你的模型上下文窗口和压缩阈值。假设用的是一个 128K 窗口的模型我把阈值设为 80000 token。# 压缩配置示例基于常见实践的参数结构 compression_config { enable: True, trigger_threshold: 80000, # 触发压缩的 token 数 keep_recent_rounds: 5, # 无论如何保留最近 5 轮 summary_model: your-model, # 用于生成摘要的模型 max_summary_tokens: 1000, # 摘要长度上限 }第二步把配置挂到 Agent 上。AgentScope 2.0 里通常是在构建 Agent 时传入或者在运行时动态调整。第三步验证压缩是否生效。最直接的办法是打印每轮的实际 token 数观察它在接近阈值时是否回落。4.2 自定义摘要 Prompt 的写法默认摘要 prompt 往往太笼统我一般会改成结构化的强制模型按固定格式输出。这样后续解析和复用都方便。summary_prompt 请将以下对话历史压缩成结构化摘要严格按此格式输出 【用户偏好】用户明确表达过的喜好、约束、要求 【已确认决策】双方已经达成一致的结论 【未完成事项】还没解决、需要后续跟进的问题 【关键事实】对话中出现的重要数据、实体、结果 对话历史 {history} 要求只保留对后续对话有用的信息寒暄和重复内容一律丢弃。 这么写的好处是摘要结果本身就是结构化的你甚至可以在压缩后直接把它当成一个「记忆块」注入到系统提示里比塞回消息列表更省 token。4.3 工具结果的压缩处理工具返回往往是 token 杀手。一个搜索工具返回十条结果每条几百字一轮就上万 token。我的做法是工具返回后立刻做一次轻量压缩而不是等整体压缩时才处理。具体来说可以在工具调用的后处理钩子里对返回内容做截断或摘要。比如只保留前三条结果的关键字段其余丢弃。这一步在 AgentScope 2.0 里可以通过自定义工具包装器实现。def compress_tool_result(raw_result, max_len500): 对工具返回做轻量压缩 if len(raw_result) max_len: return raw_result # 保留开头和结尾中间省略 head raw_result[:max_len // 2] tail raw_result[-max_len // 2:] return f{head}\n...[中间内容已省略]...\n{tail}这个简单的头尾保留法实测能砍掉 60% 以上的工具返回 token而且关键信息开头的结论、结尾的总结基本不丢。4.4 压缩后的状态持久化压缩不是终点压缩后的 AgentState 需要被正确持久化否则下次加载又变回原样。AgentScope 2.0 支持把状态序列化到存储层。这里要注意摘要和原始消息要分开存。原始消息留着做审计和回溯摘要用于实际推理。这样既省了推理成本又没丢数据。5. 常见问题与排查技巧实录5.1 压缩后 Agent「失忆」了怎么办这是最常见的问题。表现是压缩之后Agent 忘记了之前用户说过的关键信息。原因通常是摘要 prompt 没覆盖到那类信息或者keep_recent_rounds设得太小。排查思路先把压缩前后的 AgentState 都打印出来对比一下哪些信息丢了。然后针对性调整摘要 prompt把丢失的信息类型加进格式模板里。如果是个别关键消息可以考虑给它打标记压缩时强制保留。5.2 压缩本身报上下文超限这个有点讽刺为了压缩而调用的摘要模型自己超限了。原因是你要压缩的历史本身就太长超过了摘要模型的窗口。解决办法是分段压缩把超长历史切成几段分别摘要再把几段摘要合并成最终摘要。虽然多调了几次模型但能保证不报错。5.3 压缩频率过高导致成本上升如果发现压缩调用太频繁先检查阈值是不是设低了。另一个常见原因是工具返回波动大某一轮突然返回超长内容直接把 token 顶到阈值。这种情况应该从工具结果压缩入手而不是调高整体阈值。5.4 问题速查表现象可能原因排查方向压缩后失忆摘要 prompt 覆盖不全检查摘要格式模板摘要调用超限历史太长改分段压缩压缩太频繁阈值过低或工具返回波动调阈值 工具结果预处理压缩不生效绕过 AgentState 直接改列表检查读写接口成本不降反升摘要模型选得太大换小模型做摘要实操心得摘要模型不一定要和主模型一样。用一个便宜的小模型专门做摘要成本能降一大截效果通常也够用。我一般用主模型 1/10 价位的模型来做这件事。6. 多 Agent 场景下的上下文管理6.1 每个 Agent 独立管理自己的上下文在多 Agent 协作里一个常见的错误是让所有 Agent 共享一份上下文。这会导致上下文爆炸式增长而且互相干扰。正确做法是每个 Agent 维护自己的 AgentState只在需要传递信息时把关键结论以消息形式传给对方。AgentScope 2.0 的多 Agent 调用配置里消息传递是显式的。这意味着你可以精确控制「什么信息进入哪个 Agent 的上下文」这本身就是一种压缩——不该给的信息根本不给。6.2 共享记忆的压缩策略有些场景确实需要共享记忆比如多个 Agent 协作完成一个长任务。这时候可以维护一个独立的「共享记忆区」它有自己的压缩策略通常比单个 Agent 的压缩更激进因为共享记忆只保留全局性的结论和决策。我的做法是共享记忆只存三类东西——任务目标、已完成的里程碑、待解决的阻塞项。其他细节各 Agent 自己管。这样共享记忆的 token 占用能控制在很小的范围内。6.3 跨 Agent 消息的裁剪Agent 之间传递的消息往往带着大量对方不需要的上下文。比如 Agent A 把整个工具调用链传给 Agent B但 B 只需要最终结论。这时候应该在传递前做一次裁剪只发结论。这个裁剪逻辑可以封装成一个统一的消息发送函数所有跨 Agent 通信都走它。这样既统一了规范又避免了遗漏。7. 我踩过的几个坑和最后的建议第一个坑是过早优化。项目刚开始就跑去做复杂的摘要压缩结果调试成本很高而且早期对话轮次少根本用不上。建议先跑通基础流程等真的遇到上下文问题了再上压缩。第二个坑是摘要 prompt 写得太随意。一开始我用的默认 prompt结果摘要出来的东西又长又没用压缩等于没压。后来改成结构化模板效果立竿见影。摘要 prompt 值得你花时间反复调。第三个坑是忽略工具定义的 token 占用。工具多的时候光 Schema 就占好几千 token这部分其实也可以精简——比如把不常用的工具在特定轮次动态挂载而不是一直挂着。最后分享一个小技巧在开发阶段给 AgentState 加一个 token 计数钩子每轮打印实际 token 数。这个简单的监控能帮你提前发现上下文增长异常比等到报错再去查要省事得多。上下文管理这件事本质上是个持续观察和调优的过程没有一劳永逸的配置只有适合你当前业务场景的平衡点。