先说明一件事最近一直在折腾 Agent 应用最让我头疼的不是模型能力不够而是对话只要超过三轮Agent 就开始失忆。用户上一轮刚报过的手机号这一轮它就能问出请问您的手机号是多少。这个问题的本质就是 Agent 缺少多轮对话记忆。直到我认真过了一遍 AgentScope 2.0 的多轮对话与记忆机制才彻底想明白记忆这件事不是加个数据库那么简单它有一整套设计哲学而 AgentScope 2.0 主推的 in-token 实证记忆机制恰恰是绝大多数场景下性价比最高、最容易落地、也最容易被误解的方案。这篇学习笔记会把 in-token 记忆机制的原理、AgentScope 2.0 里的实操写法、我做的多轮实测数据以及几个真实踩坑记录全部整理出来。不管你是正在选型 Agent 框架的开发者还是被Agent 失忆折磨的应用工程师或者是想系统学习 Agent 开发的新手这篇笔记应该都能给你一些可复用的参考。1. 多轮对话才是 Agent 从玩具走向工具的分水岭1.1 无状态的模型 API 和有状态的产品体验之间隔着一道天然的鸿沟很多人刚开始做 Agent 时会有一个错觉大模型这么聪明多轮对话应该天然就会吧实际上模型 API 本身是无状态的。你每次调用接口看到的只有这一次传进去的 prompt模型根本不知道上一轮聊了什么。它就像一个每次见面都把你当陌生人的朋友你们上次聊得再投机下次碰面它依然会问你贵姓。这就造成了产品层面的尴尬。用户在实际使用 Agent 时默认它是记得自己的。用户会说刚才那个方案再改一下会说我还是用第一次说的那个邮箱吧这些都是典型的指代性表达依赖 Agent 能记住前几轮乃至更早的信息。没有记忆这些表达全部失效用户的体感就是这 AI 是个傻子。所以多轮对话记忆不是锦上添花而是 Agent 能不能真正进入生产环境的核心分水岭。一个只能做单轮问答的 Agent本质上就是个套壳聊天机器人只有具备了跨轮次的信息保持能力Agent 才能承担真正的任务型工作流。1.2 业界主流的 Agent 记忆方案本质上只有三条路线在 AgentScope 2.0 的学习过程中我把常见的记忆方案梳理了一下其实业界所有做法都可以归到三条路线上in-token、standalone、参数微调。理解这三者的区别是看懂后面所有内容的前提。in-token 记忆就是把历史对话记录原原本本地作为上下文 token拼接到每次模型请求里。聊天窗口里你看到的所有历史模型每次都能完整读到。这是最朴素、最直接的方案也是 GPT 类产品最早期就在用的方案。standalone 记忆是把历史信息抽取出来存到外部存储里最常见的是向量数据库也有用普通数据库或者 Redis 的。每次对话时通过检索把相关片段找出来再拼到上下文里。这就是常说的 RAG 记忆或者外部记忆。参数微调则是把特定知识/用户偏好直接训练进模型权重。这条路成本最高一般用于行业知识注入很少人会用微调来做单用户对话记忆因为每个用户的记忆都不一样不可能为每个用户微调一个模型。为了更直观我把三条路线放在一起做了个对比维度in-token上下文记忆standalone外部检索记忆参数微调记忆实现成本极低天然支持中高需要维护存储与检索链路极高需要训练资源信息完整性无损全部历史可见有损依赖检索召回率取决于训练数据覆盖长对话表现受上下文窗口限制支持无限历史但相关度波动稳定但泛化差可解释性强可在请求体里直接查看中需要追踪检索链路弱黑盒适合场景单会话内多轮任务、短中期记忆跨会话长期记忆、海量知识固定知识库、领域专家看完这张表你就会发现in-token 在单会话多轮对话这个场景下几乎是压倒性的优势选择。1.3 AgentScope 2.0 为什么把 in-token 作为实证推荐方案我在读 AgentScope 2.0 的中文文档时注意到官方对记忆机制的态度非常务实新手上手 Agent 开发优先用 in-token 记忆因为简单、可观测、信息无损。实证这个词我觉得有两层含义。第一层是它在实际评测中被证明有效。在上下文窗口没被撑爆的前提下in-token 的记忆准确率是最高的——因为它根本没有检索这个环节不存在召回失败、排序错误之类的中间故障。相比之下向量检索出来的片段经常跟当前问题对不上号这种记错了比不记得更致命。第二层是它的代价是可量化、可预测的。token 消耗随着对话轮数线性增长什么时候会到上限成本是多少工程师可以精确计算出来进而选择合适的压缩策略。AgentScope 2.0 把这种有实证依据的设计哲学贯彻到底先给你一条最简单可靠的路径让你把业务跑通再把复杂的记忆增强能力作为可选项提供。这也符合我个人的经验——大多数 Agent 项目死在过度设计上而不是死在方案不够高级上。2. in-token 记忆机制的原理拆解把对话塞回上下文这件事远没有听起来那么简单2.1 底层逻辑从 API 视角看所谓记忆就是不断变长的 messages 数组要理解 in-token最好的方式是从 API 请求体的角度去看。以 OpenAI 兼容接口为例一次带历史的对话请求其实长这样{ model: gpt-4o, messages: [ {role: system, content: 你是一个乐于助人的助理。}, {role: user, content: 我叫老张今天我心情不太好。}, {role: assistant, content: 老张你好不管发生什么我一直都在。有什么想聊聊的吗}, {role: user, content: 你还记得我叫什么吗} ] }注意看这里没有任何数据库没有任何向量检索。模型能回答出你叫老张完全是因为第三轮请求里把第一轮的 user 消息、第二轮的 assistant 回复都原封不动地放进来了。这就是 in-token 记忆的全部秘密所谓让 Agent 记住你就是每次都把你之前说过的所有话重新讲给模型听一遍。2.2 AgentScope 2.0 中的 Msg 消息模型为什么正确的盒子比裸字符串更可靠如果你只是自己调用 API用字典形式的 messages 完全没问题。但一旦进入 Agent 开发你会发现裸字典很快就不够用了。原因有三个第一Agent 要调用工具工具返回的结果必须和 assistant 的 tool_call 请求一一对应纯字典结构很容易搞乱第二多智能体场景下消息可能来自不同的 agent你需要区分每条消息的归属第三人机协同场景中消息可能是用户发的、Agent 发的、也可能是系统触发的这种跨来源的消息如果不做结构化后续做权限控制和审计就是灾难。AgentScope 2.0 用 Msg 消息模型来解决这个问题。在我使用的 2.0 版本里消息不再是 dict而是统一的 Msg 对象核心字段包括roleSYSTEM / USER / ASSISTANT / TOOLname谁说的content内容本体id / parent_id / timestamp血缘与时间戳这个设计最妙的地方在于血缘关系。每一条 Msg 都有 parent_id可以回溯到它是由哪条消息触发的。这意味着你可以完整回放整个对话链——哪个 agent 看到了哪条消息、基于什么上下文做出了什么判断、调用工具后拿到了什么结果。做多轮对话排查时这个能力帮了我大忙。举个例子同样是让 Agent 记住用户偏好如果只用裸字符串拼接你完全不知道某一条消息到底有没有被模型真正看到而用 Msg 血缘信息配合 AgentScope Studio你可以直观地看到每一轮模型实际收到的上下文集。这在第 4 部分的实测中会体现出来。2.3 信息无损是 in-token 最锋利的武器也是它最容易被低估的优点很多人一听到 in-token 就说这不就是把消息拼起来嘛太笨了。这种说法其实低估了信息无损的价值。RAG / 向量检索本质上是一个有损压缩过程。你要把用户的长对话切块、向量化、存起来下次检索的时候再捞出来。这个过程里有三个环节都可能丢信息切块可能切断因果联系向量化可能损失语义细节召回的 top-k 可能漏掉关键片段。我见过太多团队在 Agent 上引入向量记忆后出现提了 A 问题它答得挺好但聊到第三轮就答非所问的诡异现象——不是模型不行是检索环节把关键信息丢了。in-token 完全没有这个问题。所有历史消息原样保留模型可以直接从完整上下文中捕捉人称指代、语气偏好、前后矛盾它能依靠的上下文就是最真实的对话过程。特别是写代码、改文档这类强引用的场景用户经常会说把上面那个函数的返回类型改一下这种情况下如果你只检索了语义相似的片段没有拿到完整的函数定义模型根本无从下手。in-token 虽然笨但它保证模型手里永远握着全部底牌。2.4 窗口极限之下的三种退化模式硬截断、滑动窗口、摘要压缩当然in-token 也有它的天花板——上下文窗口。一旦历史 token 总量超出模型窗口你必须做出取舍。AgentScope 2.0 的文档和社区实践中最常见的三种取舍方式我总结如下。硬截断直接砍掉最早的消息。实现最简单但代价是一砍全忘用户最早说过的重要信息比如手机号、需求背景会直接消失。只适合对早期信息不敏感的场景。滑动窗口始终保留最近 N 条消息。实现也不复杂能保证模型最近的事记得清楚但窗口之外的信息还是会丢。适合客服这类以近期上下文为主的场景。摘要压缩把早期消息交给模型总结成一段摘要比如用户是老张偏好简洁回答前面确定了方案 A然后把摘要放在 system 消息里近期消息保持原样。这是目前工程上平衡得最好的方案——早期记忆以要点形式存在近期记忆以原文形式存在。需要说明的是这三种方式不是非此即彼的关系。AgentScope 2.0 里它们可以组合使用滑动窗口兜底窗口外的消息做摘要摘要在每次进入窗口边界时重新生成。这一套组合做下来几十轮对话的记忆基本都能维持在一个可用的水平。3. AgentScope 2.0 实操从零跑通一个带记忆的多轮对话 Agent3.1 环境准备安装与模型配置实操部分我来还原一遍我自己的完整配置过程。环境是 Python 3.10 AgentScope 2.0 版本。安装只需要一条命令pip install agentscope装完之后第一步是配置模型。AgentScope 2.0 支持多种模型服务我用的是 OpenAI 兼容接口。模型配置不是写死在代码里的而是通过一个 model configs 列表传入这样做的好处是切换模型或者切换 key 时不需要改动业务代码import agentscope model_configs [ { model_type: openai, config_name: my_gpt4o, model_name: gpt-4o, api_key: your-api-key-here, base_url: https://api.openai.com/v1, } ] agentscope.init(model_configsmodel_configs)注意config_name是用来在代码里引用的逻辑名字model_name才是真正请求模型服务时的名称。有的同学会在这里直接把config_name填成gpt-4o后面创建 Agent 时又填了别的名字导致一堆低级报错。命名要规范这算是第一个经验点。3.2 核心代码ReActAgent Msg三行代码拿到多轮记忆AgentScope 2.0 的 ReActAgent 默认就是 in-token 记忆模式不需要额外引入记忆模块。这意味着什么呢意味着你只要把历史对话作为消息持续传给同一个 Agent 对象它天然就能记住之前的所有内容。下面是我实测通过的代码from agentscope.agent import ReActAgent from agentscope.message import Msg agent ReActAgent( nameassistant, model_config_namemy_gpt4o, ) # 第一轮告诉它基础信息 reply_1 agent(Msg(nameuser, content我叫老张回复请尽量简洁。)) print(reply_1.content) # 第三轮验证记忆是否生效 reply_2 agent(Msg(nameuser, content你还记得我的名字和要求吗)) print(reply_2.content)执行后reply_2 的内容大概是记得你叫老张回复要尽量简洁。——没有任何显式的记忆存储代码记忆就这样生效了。原因就在 2.1 节说的ReActAgent 内部维护着一个消息列表每一轮对话产生的 Msg 都会自动追加进去下一轮请求时带着全部历史一起发送。这就是 in-token 的典型实现。3.3 让 Agent 在记忆之上使用工具把工具调用结果也纳入上下文多轮对话一个更真实的场景是既要有记忆又要调用工具。AgentScope 2.0 里注册工具的写法是装饰器风格非常直观agent ReActAgent( nameassistant, model_config_namemy_gpt4o, ) agent.method def get_today_weather(city: str) - str: 查询指定城市的天气情况。 Args: city: 城市名称。 # 这里替换为真实天气 API 调用 return f{city}今天晴24℃ # 第一轮记住用户所在城市 agent(Msg(nameuser, content我在上海以后问天气默认上海。)) # 第四轮跨多轮使用工具 reply agent(Msg(nameuser, content今天上海天气怎么样)) print(reply.content)这里发生的事比看起来复杂Agent 生成的 assistant 消息中会包含一个 tool_call 请求框架自动执行 get_today_weather 工具把工具返回值作为 TOOL 角色的消息追加进上下文最后模型再基于前面的所有记忆和工具结果生成最终回答。整个工具调用链路里的中间消息也会被记录在案成为后续记忆的一部分。这比单轮对话更能体现 in-token 的价值——没有历史上下文模型就无法知道上海这个隐含对象是从哪来的。3.4 为什么要用 Msg 对象而不是直接传字符串一次 debug 给我的教训我在刚开始写 AgentScope 2.0 时图省事直接往 agent 里传字符串reply agent(你好)结果第一轮没报错第二轮开始出现角色错乱有时模型把自己说过的话误当成用户说的对话逻辑完全崩掉。后来看 AgentScope Studio 里的消息流才发现裸字符串会被当作默认角色处理在多轮对话中产生歧义。改用 Msg 之后消息的角色、名称、血缘一目了然再没出过这种问题。这也是我理解 AgentScope 2.0 一直强调 msg-model 的原因消息是整个 Agent 交互的最小单元消息结构不健壮上层的一切都不可靠。Msg 对象强行让你把谁说、说了什么、在哪个上下文下说的这三个要素写清楚这本身就是一种防呆设计。4. 实证记录10 轮、30 轮、60 轮对话下的记忆表现in-token 的边界到底在哪4.1 我设计的记忆测试方法前面讲了不少理论这一节放我的实测数据。我设计了一套记忆测试模拟真实用户与 Agent 的连续交互主要考察三类能力信息回捞第 1 轮告诉 Agent 一个专属信息比如我的工号是 A-2024-0715然后分别在第 10、30、60 轮询问它是否还记得考察基础记忆保持。指代消解在第 N 轮时使用我刚才说的那个方案第一次提到的那个订单号这类指代表达考察 Agent 是否能在长历史中定位正确信息。长上下文引用在前面多轮分散埋入多条约束颜色偏好、时间限制、禁用语等最后给一个新任务看 Agent 能不能把所有约束全部满足。测试用的模型是 gpt-4o窗口 128K token每轮消息控制在 800 token 以内。我用同一段脚本跑完全程。4.2 测试结果前 30 轮非常稳60 轮后开始出现中间遗忘结果整理成表格如下对话轮数信息回捞准确率指代消解成功率约束满足率单轮累计输入 token 约平均响应时间10 轮100%100%100%8K1.2s30 轮100%93%94%24K1.8s60 轮87%73%78%48K2.6s需要说明的是这个数字只代表我当前测试环境的抽样结果不是严谨的学术评测但趋势非常典型在 30 轮以内in-token 记忆的准确率几乎完美到了 60 轮、累计上下文接近 50K token 时模型开始出现一种很微妙的现象——不是彻底遗忘而是对中间位置的信息回忆出现偏差比如把工号 A-2024-0715 记成 A-2024-0712。这就是业界常说的大海捞针问题当上下文很长时模型的注意力会被开头和结尾的内容吸引中间部分容易被稀释。尤其是指代消解60 轮之后模型经常找错参照对象。所以我的结论是in-token 绝不是无限可用的窗口是你的上限但远在窗口上限之前模型的注意力已经在衰退。4.3 成本模型用一条公式估算多轮对话的真实 token 消耗除了准确率成本也是工程上必须提前算清楚的事。in-token 的成本模型比想象中更容易失控因为它是指数叠加的。我简化说明一下假设每轮用户输入和工具调用合计约 500 token模型输出约 300 token。那么第 n 轮请求时需要携带的历史 token 大约是 (n-1) × 800。累计到第 50 轮时总消耗是所有轮次输入的和约等于 800 × (12...49) / 2 × 2量级在 100 万 token 上下。也就是说一个 50 轮的长对话可能吃掉上百万 token按常见模型价格算一次深度交互的成本可能是单轮的几十倍。这个成本曲线决定了 in-token 在实际生产中必须搭配策略使用。我自己的经验是明确设置单会话最大轮数接近轮数上限时主动开启新的会话并生成摘要或者按照 4.1 的方案30 轮之后自动进入摘要 近期原文的混合模式。一句话总结in-token 负责高质量短记忆摘要负责长记忆的骨架两者结合才能在成本和效果之间找到平衡点。5. 踩坑清单多轮对话 in-token最容易翻车的四个细节5.1 消息角色错乱模型把自己说过的话当成用户说的这是我在多轮对话里踩过最典型的坑。现象是对话超过几轮之后模型开始自问自答甚至把自己之前的回答当成用户的新指令执行。排查 AgentScope Studio 里的轨迹后发现问题出在消息角色上——部分历史消息的 role 被写成了 USER而这些消息的内容其实是模型自己的输出。原因通常是手动构造消息时对 role 字段处理不严谨或者在从旧代码迁移时把 dict 直接转 Msg 而没核对字节。解决办法很简单统一用Msg构造消息让框架负责角色映射如果需要手工拼接历史务必核对每一条的 role 和 name。这个坑虽然低级但在团队协作时特别容易发生一定要作为 code review 的重点项。5.2 工具调用历史是记忆刺客tool_call 与 tool 消息配对错位带工具的 Agent 比纯对话更容易出记忆问题。OpenAI 兼容接口要求 assistant 消息里的 tool_call 必须有对应的 tool 角色消息而且是一一配对的关系。一旦中间某条工具消息缺失、重复或者顺序颠倒模型轻则报错重则把工具返回的内容当成用户的指令产生严重的安全隐患。我遇到的一次故障是Agent 调用天气工具后工具消息没有正确追加到历史中下一轮模型在没有任何工具结果的情况下编造了一个上海 25℃的回答。这在 in-token 模式下尤其危险因为编造的内容会进入历史后续每一轮都会被当作事实继续引用错误会被逐渐放大。排查方式也简单在 AgentScope Studio 里检查每一条 assistant 消息之后是否有对应的 tool 消息回写。5.3 超出上下文窗口的报错与静默截断大家最容易想到的问题是Context length exceeded之类的硬报错。但其实更危险的是静默截断——好几种模型服务在超过窗口上限时不会报错而是直接把最早的几条消息悄悄丢弃模型浑然不觉地继续回答用户还以为 Agent 还记得其实它已经忘了大半。对付静默截断最好的办法是在 Agent 外显式维护一个 token 计数器。在发送消息之前预估当前消息列表的 token 总量超过阈值就启动压缩策略。AgentScope 2.0 的 Msg 模型自带结构化信息做 token 统计很方便不要依赖模型服务端帮你善后。5.4 权限与隐私边界in-token 模式下所有历史都是明文上下文最后聊一个容易被忽略的点。in-token 记忆意味着所有对话历史会明文出现在每次模型的请求上下文中这对隐私敏感信息是个大挑战。用户的手机号、地址、身份信息都可能在上下文中被模型看到。AgentScope 2.0 提供了权限管理相关的设计我看过社区里关于权限系统通过 SSE 接口实现的讨论当 Agent 准备执行某个敏感操作比如读取用户私密信息或调用外部写接口时系统会通过 SSE 推送一条权限请求到服务端等待人工审批后再继续运行。这个机制和记忆的关系在于你可以对进入上下文的信息提前做脱敏把敏感原始信息替换为脱敏占位符只在真正需要时通过权限审批换取原始数据。我目前的做法是上下文里一律用脱敏信息Agent 需要真实数据时走权限通道这样既保住了记忆能力又不会让明文敏感信息长期驻留在上下文中。6. in-token 之外什么场景该换 standalone 记忆什么场景该混搭6.1 决策矩阵别再一刀切地选记忆方案in-token 很好但它不是银弹。我的建议是先按场景对号入座再决定技术方案。下面这张表是我实践中总结出来的决策参考业务场景推荐记忆方案理由单会话内多轮任务改需求、深度咨询in-token信息无损、指代消解表现最好跨会话长期用户画像记住用户偏好standalone 摘要会话间隔长无法依赖上下文连续海量知识问答企业知识库standaloneRAG不可能把知识库全塞进上下文客服/销售助手短会话、高频in-token 滑动窗口单会话短窗口足够需要控制成本代码助手多文件工程上下文in-token 关键片段检索完整代码段靠上下文远程仓库靠检索你会发现真正的生产级 Agent 很少只用一种记忆方案绝大多数是 in-token 打底vector 检索补充必要时再做摘要压缩。关键是先想清楚你的首要约束是什么——是效果、成本、还是冷启动速度。6.2 混合记忆的工程建议短期 in-token长期 query-then-inject如果让我给一个通用的混合记忆架构大概是这样短期记忆最近 N 轮直接用 in-token消息原文进上下文。长期记忆跨会话用户的关键信息在每次会话结束后抽取出来存入向量库或结构化存储新会话开始时先用当前用户输入作为 query 检索相关历史片段注入 system 消息。摘要层超长会话当前会话超过窗口阈值时把早期消息压缩为摘要替换原文进入上下文。这套架构的代码思路在 AgentScope 2.0 里并不复杂短期记忆是框架默认行为长期记忆的注入发生在初始化 Agent 时在 system 消息里带上检索出来的历史摘要即可。至于检索的时机不要每轮都查那样又贵又容易干扰模型。我自己的经验是仅当新用户消息包含指代或明确提到早期任务时才触发一次检索补全。6.3 AgentScope 2.0 生态里与记忆相关的两个进阶触点最后补充两个和记忆能力强相关的进阶功能是我在学习 AgentScope 2.0 时觉得特别值得关注的方向。第一个是 AgentScope Studio。它不仅仅是调试工具更是理解 Agent 记忆状态的最直观入口。你可以在 Studio 的轨迹视图中看到每一轮 Agent 实际收到的消息列表就像给模型戴了一个行车记录仪。排查为什么模型不记得 X这类问题时不需要猜直接在 Studio 里看上下文里到底有没有 X能节省大量试错时间。第二个是多智能体场景下的记忆传递。单 Agent 的 in-token 很好理解但一旦引入 Pipeline、AgentHub、MsgHub 这类多智能体编排消息会在多个 Agent 之间传递记忆就不只是一个 Agent 的历史而是消息如何在 Agent 网络里流动。有一类常见故障就是A Agent 明明知道某条信息但协作任务走到 B Agent 时信息丢了。AgentScope 2.0 的 Msg 血缘机制在这里体现出价值——每条消息的 parent_id 可以把整个多智能体交互链完整串联起来定位记忆在哪一步断裂变得非常直接。我在自己的实际使用中还有一个体会多智能体场景下不要试图让每个 Agent 都拥有完整记忆。更合理的做法是让主导 Agent维护全局上下文子 Agent 只接收完成自己子任务所需的最小上下文。记忆越分散一致性越难保证出问题的概率也越高。再分享一个小技巧给每个 Agent 的 system 消息里加上一句话——你在与其他 Agent 协作时必须引用你实际看到的消息原文不允许凭印象转述。这个简单的约束能让多智能体协作时的信息失真率明显下降本质上就是在帮 in-token 记忆链路做防损。