企业官网建设流程全解析

先说明一件事：最近一直在折腾 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 在"单会话多轮对话"这个场景下，几乎是压倒性的优势选择。

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 对象，核心字段包括：

• role：SYSTEM / USER / ASSISTANT / TOOL
• name：谁说的
• 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 实操：从零跑通一个带记忆的多轮对话 Agent

3.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_configs=model_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( name="assistant", model_config_name="my_gpt4o", ) # 第一轮：告诉它基础信息 reply_1 = agent(Msg(name="user", content="我叫老张，回复请尽量简洁。")) print(reply_1.content) # 第三轮：验证记忆是否生效 reply_2 = agent(Msg(name="user", content="你还记得我的名字和要求吗？")) print(reply_2.content)

执行后，reply_2 的内容大概是："记得，你叫老张，回复要尽量简洁。"——没有任何显式的记忆存储代码，记忆就这样生效了。原因就在 2.1 节说的：ReActAgent 内部维护着一个消息列表，每一轮对话产生的 Msg 都会自动追加进去，下一轮请求时带着全部历史一起发送。这就是 in-token 的典型实现。

3.3 让 Agent 在记忆之上使用工具：把工具调用结果也纳入上下文

多轮对话一个更真实的场景是既要有记忆，又要调用工具。AgentScope 2.0 里注册工具的写法是装饰器风格，非常直观：

agent = ReActAgent( name="assistant", model_config_name="my_gpt4o", ) @agent.method def get_today_weather(city: str) -> str: """ 查询指定城市的天气情况。 Args: city: 城市名称。 """ # 这里替换为真实天气 API 调用 return f"{city}今天晴，24℃" # 第一轮：记住用户所在城市 agent(Msg(name="user", content="我在上海，以后问天气默认上海。")) # 第四轮：跨多轮使用工具 reply = agent(Msg(name="user", 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 轮后开始出现"中间遗忘"

结果整理成表格如下：

需要说明的是，这个数字只代表我当前测试环境的抽样结果，不是严谨的学术评测，但趋势非常典型：在 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 × (1+2+...+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 很好，但它不是银弹。我的建议是先按场景对号入座，再决定技术方案。下面这张表是我实践中总结出来的决策参考：

你会发现，真正的生产级 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 记忆链路做防损。