这两年AI Agent的概念火到什么程度呢圈子里几乎人人都在聊智能体但真正落过地的同行都知道最大的门槛不是模型不够聪明而是工程上接不住。对话状态怎么持久化、上下文怎么管理、工具调用怎么编排、模型出错怎么兜底这些才是从Demo走向生产的拦路虎。我最近用阿里的AgentScope从零搭了一个带记忆的Agent跑完一轮生产场景的改造之后确实把上面这些问题都踩了一遍。这篇文章就把整个过程拆开来讲AgentScope的核心机制是什么、记忆型Agent怎么设计、生产化改造要做哪些事、以及实测中遇到的坑。这篇内容适合两种人。一是刚入门Agent开发、想找一套相对完整的框架上手的同学可以把它当作AgentScope学习指南用二是已经在用LangChain或其他工具、但对生产级三个字缺乏体感的人我的踩坑记录和改造思路应该能帮你少走很多弯路。1. 为什么选AgentScope它解决的不是写Agent而是管Agent在动手之前先说清楚我为什么没选别的框架。现在市面上的Agent框架大致分两类一类是LangChain、LlamaIndex这种偏自由拼装的什么都要自己接灵活但生产化时要操心的细节特别多另一类是Dify这类偏图形化平台的上手快但定制深度受限深入到Agent内部机制时会觉得被框架摁住了。AgentScope的位置比较特殊——它是一个更贴近编程式开发的多Agent框架但同时又帮我把模型接口、消息通信、记忆管理、服务调用这些底层活干掉了。1.1 核心抽象Agent、Message、Pipeline、ServiceAgentScope的几个核心概念理解了它们整个框架的脉络就清楚了。第一个是Agent它是最小的智能体单元。一个Agent内部有模型配置、消息处理逻辑、记忆组件你把模型和指令交给它它就能对输入消息做出响应。框架内置了ReActAgent、DictDialogAgent、UserAgent等常用类型也可以继承基类自己写。第二个是Message这是AgentScope里非常顺手的设计——Agent之间的通信、Agent内部的输入输出统一都是Message对象。它自带name、content、id、timestamp等字段。这意味着你可以在任意节点给消息打标记、做追踪做日志和排查时格外方便。Debug的时候把一段决策链路的消息序列导出来哪一步模型返回了没解析的内容、哪一步工具结果格式不对一眼就能定位。第三个是Pipeline它负责把多个Agent编排成一个流程。串联多个Agent、给流程加控制逻辑都在Pipeline里完成。举个例子我后来做的一个客服质检回复双Agent流程就是用Pipeline把评审Agent和回复Agent串起来前者的评分结果作为后者的输入约束。第四个是Service它是Agent调用的外部能力接口工具函数、数据查询、RAG检索都可以注册成Service。AgentScope 2.0里把RAG也做成了Service化后面专门讲。这组抽象组合起来承上启下的逻辑是基础的消息通信机制统一了往上搭什么Agent、编排什么流程都有一套稳定的地基。跟LangChain对比LangChain的Chain和Tool更像是函数式组合而AgentScope更接近Actor模型那种每个Agent独立收发消息、可被编排的组织方式。如果你要做的场景不止一个Agent而是多个角色协作AgentScope的组织优势会明显很多。1.2 生产级到底体现在哪框架官方的定位是面向多智能体应用的生产级框架我自己用下来的体感是它对以下三件事有天然的考虑首先是分布式友好。Actor模型的设计让每个Agent可以跑在独立的执行上下文里Agent之间通过消息解耦。这在单机Demo里感觉不出来但一旦要拆服务、做水平扩展这种设计会让迁移成本低得多。其次是模型接入的统一性。AgentScope通过model_configs统一管理模型配置OpenAI、DashScope、Ollama本地模型等都可以按同一套方式接入。这意味着你可以先在本地用小模型调通链路再切到线上大模型模型服务商切换不需要改业务代码只改配置。最后是Service与工具调用的标准化。工具函数的注册、传参、结果回传都走Service接口Agent调用工具时框架会自动处理解析和回填结果。这一点在后面做RAG接入时省了我很多事。2. 项目起步从零跑通一个带基础记忆的Agent这个阶段的目标非常朴素——让一个带记忆的Agent能连续对话并且能记住关键信息。先把这个最小闭环跑出来后面的生产化改造才有抓手。2.1 环境准备与模型配置环境要求不复杂Python 3.9以上直接pip安装pip install agentscope本地通常建议把示例项目先跑起来再改自己的需求。模型配置这块是AgentScope里最容易上手也最容易迷惑的地方我建议按下面这种结构组织import agentscope agentscope.init( model_configs[ { model: openai, model_type: openai, config_name: gpt-4o-mini, api_key: ${OPENAI_API_KEY}, } ], projectproduction-ai-agent, )注意几个要点config_name是给这个配置起的引用名后面创建Agent时用这个名字指向模型不直接写模型名。api_key用环境变量占位符${...}注入不硬编码在代码里。生产环境你可能会用KMS或其他密钥管理服务这个占位符机制能让你在裸代码里不出现任何密钥。如果你用本地模型可以配置模型服务地址和模型路径。我用Ollama接Qwen系列模型实测过注册方式差别不大主要注意本地服务地址拼接。2.2 创建第一个带记忆的Agent并验证连续对话AgentScope里每个Agent都内置了记忆组件的概念。最简单的做法是给Agent绑定一个memory对象Agent每次对话都会把消息接入记忆之后再响应该轮输入前会先从记忆里取出相关上下文来组装Prompt。下面是我当时跑通最小闭环的代码如果你照抄只需要替换模型配置from agentscope.agent import ReActAgent from agentscope.memory import TemporaryMemory memory TemporaryMemory() agent ReActAgent( nameassistant, model_config_namegpt-4o-mini, memorymemory, system_prompt( 你是项目助手。请记住用户提供的关键信息 例如项目名称、技术栈、偏好设定。 ), ) # 第一轮对话 response agent(我叫王工负责支付网关项目主要用Java和Python。) print(response) # 第二轮对话看看Agent是否还记得上一轮的信息 response agent(你记得我的项目背景吗) print(response)这里ReActAgent用的是经典的Thought-Action-Observation循环模型先生成思考再决定是否需要调用工具最后根据观察结果组织回答。对记忆型Agent来说ReActAgent的好处是当它需要回忆信息时它可以在循环里启动记忆检索动作而不是单纯依赖上下文里的原始文本。第二轮问你记得我的项目背景吗如果第一轮的消息成功写入了记忆并在组装Prompt时被召回Agent会重建一遍你是王工负责支付网关项目技术栈是Java和Python。通常这类信息在短期记忆里不会丢但如果你反复切换话题、跑了多轮早期信息被顶出上下文窗口也是常见的事。因此记忆组件到底怎么管理就成为了核心问题。3. 记忆不只是缓存理解AgentScope的短期记忆与长期记忆很多人对带记忆的Agent有个误解以为把历史对话一股脑塞回Prompt就算记忆了。实际上生产场景里上下文窗口是有限的塞太多会导致回答质量下降还会拖慢响应、增加费用。记忆的价值在于结构化地保留关键历史并在需要时精准召回。3.1 短期记忆与长期记忆的分工AgentScope把记忆分成两个层次短期记忆TemporaryMemory保存当前会话窗口内发生的消息。它的作用类似工作内存保证Agent在对话过程中记得刚才说过什么不重复提问、不把上下文搞乱。它有容量上限超限后会做裁剪或丢弃早期内容。长期记忆LongTermMemory保存需要跨会话、跨时间保持的信息。它通过向量化存储把对话内容去掉涉及的敏感信息后可选择脱敏转成Embedding后续通过语义检索召回相关记录。我给记忆加了一个落盘文件夹跑了十几个场景后核心体感是短期记忆解决前后一致性长期记忆解决跨时间积累。两者不是替代关系是配合关系。3.2 知识应该怎样流入记忆这是我实验中收获最大的一处。很多人以为长期记忆是把全文存下来再检索实际上有效做法通常是在每轮对话结束后把关键实体、事件、偏好摘录成短句结构化摘要再写入长期记忆在每轮对话开始时用用户的当前输入做Query对长期记忆做语义检索选出Top-K条相关记录拼进Prompt。这个过程类似一个记笔记-查笔记的机制。我自己实现时会把短期记忆的消息通过一个摘要Agent做提炼保证写入长期记忆的不是流水账而是用户偏好Java Python这类高信息密度的语句。这样做下来RAG效果很稳定长期记忆也不会污染Prompt。from agentscope.memory import LongTermMemory from agentscope.store import LocalVectorStore # 向量存储生产环境可替换为Milvus等 store LocalVectorStore() long_term_memory LongTermMemory( storestore, embedding_modelbge-small-zh-v1.5, similarity_top_k3, )注意这里的embedding模型我选择了中文友好的bge系列实测比通用英文Embedding模型对中文专有名词的匹配效果好很多。如果你做的是纯英文或代码类场景可以换CodeBERT或相应模型重点是匹配你的语料语言。3.3 会话隔离与生产级记忆的关键设计直接在生产环境踩过一个坑一开始图省事用一个Agent实例处理所有用户会话结果用户A的信息通过共享记忆跑到了用户B的上下文里差点造成数据串流事故。后来我改成用户会话维度一对一绑定Agent实例和记忆实例隔离问题立刻解决了。生产级记忆必须做到按会话隔离、按用户隔离、按权限隔离。每个会话创建独立的AgentAgent绑定自己的记忆对象会话结束可以持久化记忆新会话再恢复。这种设计的代价是多了一些实例管理开销但换来的是数据不会串、权限边界清晰。如果你用AgentScope做多用户产品建议从一开始就按这个思路设计不要先共享后加锁那会非常痛苦。4. 生产级改造结构化输出、可观测性与容错Demo能跑和能上线中间隔着一整套工程化改造。我在这部分做的事情是让输出可解析、运行可追踪、异常可兜底。4.1 结构化输出让Agent按约定返回格式真实业务里Agent的输出不能是自由文本。用户问天气系统需要拿到城市、温度、时间这些字段用户做订单查询系统需要拿到订单号、状态、金额。自由文本意味着后续流程难以对接。AgentScope的格式化能力在这里就很重要了。我在实践中采用的方式是自定义一个FormatAgent风格的后处理封装在Agent设置里指定格式化器并给出JSON Schemaresponse_schema { type: json_object, properties: { intent: {type: string}, slots: {type: object}, }, required: [intent, slots], }然后在Agent的构造参数里传这个Schema。模型会按Schema输出JSON。你以为这样就够了不够模型有时候会输出多行废话或者格式走样所以我额外加了一道解析校验自动重试的防抖逻辑。解析失败时把异常信息回传给模型让它修正输出最多重试两次还不行就走兜底路由。这个设计直接把我项目里下游解析失败率从8%压到了不到1%。4.2 可观测性从黑盒对话到全链路消息流AgentScope在消息通信上的设计让我在排查问题时特别省力。每个Message都有id、timestamp、name等元信息你可以在Agent的响应处理环节做一层拦截把输入Message和输出Message完整记录到结构化日志里。我的做法是写了一个日志装饰器import json import logging def traced_agent(agent): def wrapped(message): logging.info( [trace] agent%s input%s, agent.name, json.dumps(message, ensure_asciiFalse), ) response agent(message) logging.info( [trace] agent%s output%s, agent.name, json.dumps(response, ensure_asciiFalse), ) return response return wrapped日志记录的是消息流而不只是最终回答文本。这样在问题排查时我可以完整复现用户的意图是怎么流转的哪一步模型调用消耗了多少token工具结果是否被正确注入。另外AgentScope提供了message_id的关联关系输入和输出通过这个id串联连续多轮可以还原出完整的决策链路。这一点在生产排错时价值巨大。4.3 容错设计模型会挂服务会抖Agent要会扛生产环境有个铁律别假设模型调用100%成功。我在上线第一周就撞上了模型服务超时。设计容错的时候我把重点放在三处调用超时给模型调用设置合理的超时时间比如60秒超时后根据业务策略重试或降级回答。响应格式异常模型返回内容不是合法JSON时进入格式化重试流程。工具调用失败Agent要能识别工具返回了错误并把它作为Observation写回推理循环而不是直接崩溃。我还给Agent加了一层兜底回复策略。当模型连续重试还是失败时返回一句安全、通用的提示并标记任务状态为handoff_to_human。这样下游系统至少知道这条会话需要人工介入而不是把错误膨胀到用户面前。5. 接入RAG服务让Agent学会按需查资料AgentScope 2.0把RAG做成了服务化的能力也就是RAG as a Service。作为一个带记忆的生产级Agent只有通用对话能力是不够的它还需要能访问私有知识库、查阅技术文档、检索历史工单。这正是RAG要解决的问题。5.1 从全量塞上下文到检索增强生成第一版RAG实现几乎所有人都会做一件事把知识库内容全部塞进Prompt。结果模型被海量无关文本干扰回答质量惨不忍睹token费用也高。后来才改成了正规的检索-注入-生成链路离线阶段文档加载、切分、向量化、索引在线阶段用户Query向量化检索Top-K片段拼入Prompt再让模型生成。这套流程在AgentScope里被抽象成了Service。你注册一个文档检索ServiceAgent在ReAct循环里判断这个问题需要查知识库于是发起Service调用拿到检索结果再生成回答。5.2 在AgentScope里配置RAG服务我照着官方RAG示例改了一套核心代码长这样from agentscope.service import ServiceTool from agentscope.rag import RAGService, DocumentLoader, SentenceSplitter doc_loader DocumentLoader(pathdocs/) splitter SentenceSplitter(chunk_size256, chunk_overlap32) rag_service RAGService( nameknowledge_rag, loaderdoc_loader, splittersplitter, embedding_modelbge-small-zh-v1.5, storestore, top_k4, )然后把这个Service注册给AgentAgent的system prompt里声明技术问题请通过knowledge_rag查询资料后再回答。实测下来知识类问题的正确率提升很明显关键原因在于召回回来的Top-4片段都是和问题最相关的模型基于这些片段做生成比让它凭空编靠谱得多。5.3 RAG生产中容易忽略的三个细节第一是切分的句子粒度。切得太碎语义不完整切得太长注意力被稀释。我用的chunk_size在200-300字之间、重叠32字这个配置对中文技术文档效果比较均衡你可以根据语料微调但没有绝对最优解。第二是知识库更新机制。生产系统的知识库不是静态的——文档会改、产品会迭代。你需要做增量更新别每次全量重建索引成本高还容易导致线上短暂无索引。AgentScope的存储层支持追加写入可以按文档ID做增量同步。第三是权限边界。不是所有Agent都有权限查所有知识库。内部资料、客户数据、平台配置要分开存储按Agent角色隔离。我一开始把所有文档丢一个库后来发现Agent回答中会把内部运维细节也讲出来只好紧急调整成按库隔离检索前权限过滤双保险。6. 实测踩坑本地模型、并发调度与上下文超限这部分是真实运营暴露出来的问题也是我认为最值得分享的一节。每个坑都会附上排查和解决思路你在自己的项目里大概率也会撞见。6.1 本地模型接入的兼容性迷雾我最初图成本低想用Ollama启动本地模型跑通全流程。接入后发现一个问题AgentScope在解析模型返回时需要拿到规范的content字段而本地模型的响应格式五花八门有的自带reasoning链文本有的把工具调用包装在content里而不是独立的tool_calls里。这导致ReAct流程直接断裂。排查链路是这样的第一步我在日志里打印模型原始响应发现content是一大段思考过程最终回答的混合体第二步检查AgentScope消息解析逻辑它需要的是纯回答或结构化工具调用第三步解决方式是给本地模型配置添加响应格式说明在提示词里明确要求只输出最终结果不要输出思维链。如果你用的是支持工具调用的本地模型例如某些经过tool_aligned训练的模型务必在配置里打开对应开关否则AgentScope传过去的tool_schema不会被正确处理。6.2 并发场景下的记忆串扰前文提到的共享记忆问题这里再展开一下。我在压测时用20路并发直接让多个用户会话共用同一个Agent实例的memory。结果出现了恐怖的幻觉片段——用户A问项目状态Agent回答里混入了用户B的项目信息。定位到根因后修复方案是会话容器每个会话进来创建一个新的Agent实例并绑定独立的记忆实例会话结束后把长期记忆写入持久化存储新会话如果要求恢复记忆则用会话ID检索历史长期记忆重新加载。这个会话即实例模式在AgentScope的Actor模型语境下非常自然。Agent本身不持有跨会话共享的全局状态全局状态都收敛在存储层实例是轻量的创建销毁成本可控。实测后再也没出现串扰问题。6.3 上下文超限与记忆裁剪的平衡第七轮对话之后上下文开始接近模型窗口上限这是所有记忆型Agent都会撞的墙。我第一反应是增大窗口长度但发现效果不好还非常贵。后来老老实实做裁剪策略优先保留最近的N轮完整消息保证当前对话的连续性保留系统提示词中提到的关键实体如项目名、技术栈这部分单独存短期记忆摘要早期细节如果需要通过长期记忆检索补全。这个策略跑下来回答质量不仅没下降反而因为Prompt更聚焦而有所提升。裁剪不是丢信息而是把信息按当前需要重新组织。我总结的经验是先定必须留在窗口里的底线再谈压缩不要盲目裁剪。7. 最后一公里把Agent封装成可部署的服务到这里Agent已经能带记忆、能检索、能容错、能结构化输出但还差最后一步——让它真正跑在服务里被外部系统调用。我用了FastAPI来做这层封装实测起来还是顺手的。7.1 无状态服务 外部会话存储服务实例要支持水平扩展就必须保持无状态。Agent实例可以被创建和销毁真正需要持久化的是会话状态和长期记忆。封装时维护一个session_pool用会话ID索引内存中的Agent实例对话结束后同步记忆到外部存储。from fastapi import FastAPI, HTTPException app FastAPI() app.post(/api/chat) async def chat(session_id: str, user_message: str): if session_id not in sessions: sessions[session_id] create_agent_ws_memory(session_id) agent sessions[session_id] response agent(user_message) return {session_id: session_id, reply: response}这样服务重启后记忆还在。水平扩容时加节点即可不需要在应用层维护跨节点的Agent状态。7.2 模型分级与成本控制生产跑起来后我观察到一个现象不是每轮对话都需要大模型。闲聊、寒暄、简单查询这些低难度请求用轻量模型就够了真正复杂的多步推理、工具编排才需要调用大参数模型。AgentScope的模型配置支持多模型组合我按意图分流处理实测成本下降了约四成。如果你做的量大这个优化值得投入。7.3 从单Agent到多Agent协作的演进一个带记忆的Agent已经能解决不少问题但真实业务往往是多角色的。做客服系统的话你需要接待Agent和质检Agent做数据分析的话你需要解析Agent和执行Agent。AgentScope的msghub可以在多个Agent之间做消息广播Pipeline可以做流程编排。我目前已经在设计一个客服回复风险预警的双Agent流程回复Agent生成内容预警Agent独立检查消息中是否有敏感或风险词。这种拆分的价值在于Agent各司其职、各持一套记忆整个系统的可维护性明显更高。最后分享一个实操体会搭完这个记忆型Agent我最大的收获并不是会用它了而是理解了Agent在生产环境真正难在哪。模型的进步是快但工程上的记忆隔离、输出稳定、成本控制每一件都是体力活也都是决定产品能不能真正跑下去的关键。你如果也想上手建议先把我前面第2节的最小闭环跑通然后立刻按第3、4节的思路去做隔离和结构化最后再逐步加RAG和多Agent协作。这一步一个脚印比直接去啃一个大而全的项目更稳。
AgentScope生产级Agent开发实战：记忆管理、RAG接入与工程化改造
这两年AI Agent的概念火到什么程度呢圈子里几乎人人都在聊智能体但真正落过地的同行都知道最大的门槛不是模型不够聪明而是工程上接不住。对话状态怎么持久化、上下文怎么管理、工具调用怎么编排、模型出错怎么兜底这些才是从Demo走向生产的拦路虎。我最近用阿里的AgentScope从零搭了一个带记忆的Agent跑完一轮生产场景的改造之后确实把上面这些问题都踩了一遍。这篇文章就把整个过程拆开来讲AgentScope的核心机制是什么、记忆型Agent怎么设计、生产化改造要做哪些事、以及实测中遇到的坑。这篇内容适合两种人。一是刚入门Agent开发、想找一套相对完整的框架上手的同学可以把它当作AgentScope学习指南用二是已经在用LangChain或其他工具、但对生产级三个字缺乏体感的人我的踩坑记录和改造思路应该能帮你少走很多弯路。1. 为什么选AgentScope它解决的不是写Agent而是管Agent在动手之前先说清楚我为什么没选别的框架。现在市面上的Agent框架大致分两类一类是LangChain、LlamaIndex这种偏自由拼装的什么都要自己接灵活但生产化时要操心的细节特别多另一类是Dify这类偏图形化平台的上手快但定制深度受限深入到Agent内部机制时会觉得被框架摁住了。AgentScope的位置比较特殊——它是一个更贴近编程式开发的多Agent框架但同时又帮我把模型接口、消息通信、记忆管理、服务调用这些底层活干掉了。1.1 核心抽象Agent、Message、Pipeline、ServiceAgentScope的几个核心概念理解了它们整个框架的脉络就清楚了。第一个是Agent它是最小的智能体单元。一个Agent内部有模型配置、消息处理逻辑、记忆组件你把模型和指令交给它它就能对输入消息做出响应。框架内置了ReActAgent、DictDialogAgent、UserAgent等常用类型也可以继承基类自己写。第二个是Message这是AgentScope里非常顺手的设计——Agent之间的通信、Agent内部的输入输出统一都是Message对象。它自带name、content、id、timestamp等字段。这意味着你可以在任意节点给消息打标记、做追踪做日志和排查时格外方便。Debug的时候把一段决策链路的消息序列导出来哪一步模型返回了没解析的内容、哪一步工具结果格式不对一眼就能定位。第三个是Pipeline它负责把多个Agent编排成一个流程。串联多个Agent、给流程加控制逻辑都在Pipeline里完成。举个例子我后来做的一个客服质检回复双Agent流程就是用Pipeline把评审Agent和回复Agent串起来前者的评分结果作为后者的输入约束。第四个是Service它是Agent调用的外部能力接口工具函数、数据查询、RAG检索都可以注册成Service。AgentScope 2.0里把RAG也做成了Service化后面专门讲。这组抽象组合起来承上启下的逻辑是基础的消息通信机制统一了往上搭什么Agent、编排什么流程都有一套稳定的地基。跟LangChain对比LangChain的Chain和Tool更像是函数式组合而AgentScope更接近Actor模型那种每个Agent独立收发消息、可被编排的组织方式。如果你要做的场景不止一个Agent而是多个角色协作AgentScope的组织优势会明显很多。1.2 生产级到底体现在哪框架官方的定位是面向多智能体应用的生产级框架我自己用下来的体感是它对以下三件事有天然的考虑首先是分布式友好。Actor模型的设计让每个Agent可以跑在独立的执行上下文里Agent之间通过消息解耦。这在单机Demo里感觉不出来但一旦要拆服务、做水平扩展这种设计会让迁移成本低得多。其次是模型接入的统一性。AgentScope通过model_configs统一管理模型配置OpenAI、DashScope、Ollama本地模型等都可以按同一套方式接入。这意味着你可以先在本地用小模型调通链路再切到线上大模型模型服务商切换不需要改业务代码只改配置。最后是Service与工具调用的标准化。工具函数的注册、传参、结果回传都走Service接口Agent调用工具时框架会自动处理解析和回填结果。这一点在后面做RAG接入时省了我很多事。2. 项目起步从零跑通一个带基础记忆的Agent这个阶段的目标非常朴素——让一个带记忆的Agent能连续对话并且能记住关键信息。先把这个最小闭环跑出来后面的生产化改造才有抓手。2.1 环境准备与模型配置环境要求不复杂Python 3.9以上直接pip安装pip install agentscope本地通常建议把示例项目先跑起来再改自己的需求。模型配置这块是AgentScope里最容易上手也最容易迷惑的地方我建议按下面这种结构组织import agentscope agentscope.init( model_configs[ { model: openai, model_type: openai, config_name: gpt-4o-mini, api_key: ${OPENAI_API_KEY}, } ], projectproduction-ai-agent, )注意几个要点config_name是给这个配置起的引用名后面创建Agent时用这个名字指向模型不直接写模型名。api_key用环境变量占位符${...}注入不硬编码在代码里。生产环境你可能会用KMS或其他密钥管理服务这个占位符机制能让你在裸代码里不出现任何密钥。如果你用本地模型可以配置模型服务地址和模型路径。我用Ollama接Qwen系列模型实测过注册方式差别不大主要注意本地服务地址拼接。2.2 创建第一个带记忆的Agent并验证连续对话AgentScope里每个Agent都内置了记忆组件的概念。最简单的做法是给Agent绑定一个memory对象Agent每次对话都会把消息接入记忆之后再响应该轮输入前会先从记忆里取出相关上下文来组装Prompt。下面是我当时跑通最小闭环的代码如果你照抄只需要替换模型配置from agentscope.agent import ReActAgent from agentscope.memory import TemporaryMemory memory TemporaryMemory() agent ReActAgent( nameassistant, model_config_namegpt-4o-mini, memorymemory, system_prompt( 你是项目助手。请记住用户提供的关键信息 例如项目名称、技术栈、偏好设定。 ), ) # 第一轮对话 response agent(我叫王工负责支付网关项目主要用Java和Python。) print(response) # 第二轮对话看看Agent是否还记得上一轮的信息 response agent(你记得我的项目背景吗) print(response)这里ReActAgent用的是经典的Thought-Action-Observation循环模型先生成思考再决定是否需要调用工具最后根据观察结果组织回答。对记忆型Agent来说ReActAgent的好处是当它需要回忆信息时它可以在循环里启动记忆检索动作而不是单纯依赖上下文里的原始文本。第二轮问你记得我的项目背景吗如果第一轮的消息成功写入了记忆并在组装Prompt时被召回Agent会重建一遍你是王工负责支付网关项目技术栈是Java和Python。通常这类信息在短期记忆里不会丢但如果你反复切换话题、跑了多轮早期信息被顶出上下文窗口也是常见的事。因此记忆组件到底怎么管理就成为了核心问题。3. 记忆不只是缓存理解AgentScope的短期记忆与长期记忆很多人对带记忆的Agent有个误解以为把历史对话一股脑塞回Prompt就算记忆了。实际上生产场景里上下文窗口是有限的塞太多会导致回答质量下降还会拖慢响应、增加费用。记忆的价值在于结构化地保留关键历史并在需要时精准召回。3.1 短期记忆与长期记忆的分工AgentScope把记忆分成两个层次短期记忆TemporaryMemory保存当前会话窗口内发生的消息。它的作用类似工作内存保证Agent在对话过程中记得刚才说过什么不重复提问、不把上下文搞乱。它有容量上限超限后会做裁剪或丢弃早期内容。长期记忆LongTermMemory保存需要跨会话、跨时间保持的信息。它通过向量化存储把对话内容去掉涉及的敏感信息后可选择脱敏转成Embedding后续通过语义检索召回相关记录。我给记忆加了一个落盘文件夹跑了十几个场景后核心体感是短期记忆解决前后一致性长期记忆解决跨时间积累。两者不是替代关系是配合关系。3.2 知识应该怎样流入记忆这是我实验中收获最大的一处。很多人以为长期记忆是把全文存下来再检索实际上有效做法通常是在每轮对话结束后把关键实体、事件、偏好摘录成短句结构化摘要再写入长期记忆在每轮对话开始时用用户的当前输入做Query对长期记忆做语义检索选出Top-K条相关记录拼进Prompt。这个过程类似一个记笔记-查笔记的机制。我自己实现时会把短期记忆的消息通过一个摘要Agent做提炼保证写入长期记忆的不是流水账而是用户偏好Java Python这类高信息密度的语句。这样做下来RAG效果很稳定长期记忆也不会污染Prompt。from agentscope.memory import LongTermMemory from agentscope.store import LocalVectorStore # 向量存储生产环境可替换为Milvus等 store LocalVectorStore() long_term_memory LongTermMemory( storestore, embedding_modelbge-small-zh-v1.5, similarity_top_k3, )注意这里的embedding模型我选择了中文友好的bge系列实测比通用英文Embedding模型对中文专有名词的匹配效果好很多。如果你做的是纯英文或代码类场景可以换CodeBERT或相应模型重点是匹配你的语料语言。3.3 会话隔离与生产级记忆的关键设计直接在生产环境踩过一个坑一开始图省事用一个Agent实例处理所有用户会话结果用户A的信息通过共享记忆跑到了用户B的上下文里差点造成数据串流事故。后来我改成用户会话维度一对一绑定Agent实例和记忆实例隔离问题立刻解决了。生产级记忆必须做到按会话隔离、按用户隔离、按权限隔离。每个会话创建独立的AgentAgent绑定自己的记忆对象会话结束可以持久化记忆新会话再恢复。这种设计的代价是多了一些实例管理开销但换来的是数据不会串、权限边界清晰。如果你用AgentScope做多用户产品建议从一开始就按这个思路设计不要先共享后加锁那会非常痛苦。4. 生产级改造结构化输出、可观测性与容错Demo能跑和能上线中间隔着一整套工程化改造。我在这部分做的事情是让输出可解析、运行可追踪、异常可兜底。4.1 结构化输出让Agent按约定返回格式真实业务里Agent的输出不能是自由文本。用户问天气系统需要拿到城市、温度、时间这些字段用户做订单查询系统需要拿到订单号、状态、金额。自由文本意味着后续流程难以对接。AgentScope的格式化能力在这里就很重要了。我在实践中采用的方式是自定义一个FormatAgent风格的后处理封装在Agent设置里指定格式化器并给出JSON Schemaresponse_schema { type: json_object, properties: { intent: {type: string}, slots: {type: object}, }, required: [intent, slots], }然后在Agent的构造参数里传这个Schema。模型会按Schema输出JSON。你以为这样就够了不够模型有时候会输出多行废话或者格式走样所以我额外加了一道解析校验自动重试的防抖逻辑。解析失败时把异常信息回传给模型让它修正输出最多重试两次还不行就走兜底路由。这个设计直接把我项目里下游解析失败率从8%压到了不到1%。4.2 可观测性从黑盒对话到全链路消息流AgentScope在消息通信上的设计让我在排查问题时特别省力。每个Message都有id、timestamp、name等元信息你可以在Agent的响应处理环节做一层拦截把输入Message和输出Message完整记录到结构化日志里。我的做法是写了一个日志装饰器import json import logging def traced_agent(agent): def wrapped(message): logging.info( [trace] agent%s input%s, agent.name, json.dumps(message, ensure_asciiFalse), ) response agent(message) logging.info( [trace] agent%s output%s, agent.name, json.dumps(response, ensure_asciiFalse), ) return response return wrapped日志记录的是消息流而不只是最终回答文本。这样在问题排查时我可以完整复现用户的意图是怎么流转的哪一步模型调用消耗了多少token工具结果是否被正确注入。另外AgentScope提供了message_id的关联关系输入和输出通过这个id串联连续多轮可以还原出完整的决策链路。这一点在生产排错时价值巨大。4.3 容错设计模型会挂服务会抖Agent要会扛生产环境有个铁律别假设模型调用100%成功。我在上线第一周就撞上了模型服务超时。设计容错的时候我把重点放在三处调用超时给模型调用设置合理的超时时间比如60秒超时后根据业务策略重试或降级回答。响应格式异常模型返回内容不是合法JSON时进入格式化重试流程。工具调用失败Agent要能识别工具返回了错误并把它作为Observation写回推理循环而不是直接崩溃。我还给Agent加了一层兜底回复策略。当模型连续重试还是失败时返回一句安全、通用的提示并标记任务状态为handoff_to_human。这样下游系统至少知道这条会话需要人工介入而不是把错误膨胀到用户面前。5. 接入RAG服务让Agent学会按需查资料AgentScope 2.0把RAG做成了服务化的能力也就是RAG as a Service。作为一个带记忆的生产级Agent只有通用对话能力是不够的它还需要能访问私有知识库、查阅技术文档、检索历史工单。这正是RAG要解决的问题。5.1 从全量塞上下文到检索增强生成第一版RAG实现几乎所有人都会做一件事把知识库内容全部塞进Prompt。结果模型被海量无关文本干扰回答质量惨不忍睹token费用也高。后来才改成了正规的检索-注入-生成链路离线阶段文档加载、切分、向量化、索引在线阶段用户Query向量化检索Top-K片段拼入Prompt再让模型生成。这套流程在AgentScope里被抽象成了Service。你注册一个文档检索ServiceAgent在ReAct循环里判断这个问题需要查知识库于是发起Service调用拿到检索结果再生成回答。5.2 在AgentScope里配置RAG服务我照着官方RAG示例改了一套核心代码长这样from agentscope.service import ServiceTool from agentscope.rag import RAGService, DocumentLoader, SentenceSplitter doc_loader DocumentLoader(pathdocs/) splitter SentenceSplitter(chunk_size256, chunk_overlap32) rag_service RAGService( nameknowledge_rag, loaderdoc_loader, splittersplitter, embedding_modelbge-small-zh-v1.5, storestore, top_k4, )然后把这个Service注册给AgentAgent的system prompt里声明技术问题请通过knowledge_rag查询资料后再回答。实测下来知识类问题的正确率提升很明显关键原因在于召回回来的Top-4片段都是和问题最相关的模型基于这些片段做生成比让它凭空编靠谱得多。5.3 RAG生产中容易忽略的三个细节第一是切分的句子粒度。切得太碎语义不完整切得太长注意力被稀释。我用的chunk_size在200-300字之间、重叠32字这个配置对中文技术文档效果比较均衡你可以根据语料微调但没有绝对最优解。第二是知识库更新机制。生产系统的知识库不是静态的——文档会改、产品会迭代。你需要做增量更新别每次全量重建索引成本高还容易导致线上短暂无索引。AgentScope的存储层支持追加写入可以按文档ID做增量同步。第三是权限边界。不是所有Agent都有权限查所有知识库。内部资料、客户数据、平台配置要分开存储按Agent角色隔离。我一开始把所有文档丢一个库后来发现Agent回答中会把内部运维细节也讲出来只好紧急调整成按库隔离检索前权限过滤双保险。6. 实测踩坑本地模型、并发调度与上下文超限这部分是真实运营暴露出来的问题也是我认为最值得分享的一节。每个坑都会附上排查和解决思路你在自己的项目里大概率也会撞见。6.1 本地模型接入的兼容性迷雾我最初图成本低想用Ollama启动本地模型跑通全流程。接入后发现一个问题AgentScope在解析模型返回时需要拿到规范的content字段而本地模型的响应格式五花八门有的自带reasoning链文本有的把工具调用包装在content里而不是独立的tool_calls里。这导致ReAct流程直接断裂。排查链路是这样的第一步我在日志里打印模型原始响应发现content是一大段思考过程最终回答的混合体第二步检查AgentScope消息解析逻辑它需要的是纯回答或结构化工具调用第三步解决方式是给本地模型配置添加响应格式说明在提示词里明确要求只输出最终结果不要输出思维链。如果你用的是支持工具调用的本地模型例如某些经过tool_aligned训练的模型务必在配置里打开对应开关否则AgentScope传过去的tool_schema不会被正确处理。6.2 并发场景下的记忆串扰前文提到的共享记忆问题这里再展开一下。我在压测时用20路并发直接让多个用户会话共用同一个Agent实例的memory。结果出现了恐怖的幻觉片段——用户A问项目状态Agent回答里混入了用户B的项目信息。定位到根因后修复方案是会话容器每个会话进来创建一个新的Agent实例并绑定独立的记忆实例会话结束后把长期记忆写入持久化存储新会话如果要求恢复记忆则用会话ID检索历史长期记忆重新加载。这个会话即实例模式在AgentScope的Actor模型语境下非常自然。Agent本身不持有跨会话共享的全局状态全局状态都收敛在存储层实例是轻量的创建销毁成本可控。实测后再也没出现串扰问题。6.3 上下文超限与记忆裁剪的平衡第七轮对话之后上下文开始接近模型窗口上限这是所有记忆型Agent都会撞的墙。我第一反应是增大窗口长度但发现效果不好还非常贵。后来老老实实做裁剪策略优先保留最近的N轮完整消息保证当前对话的连续性保留系统提示词中提到的关键实体如项目名、技术栈这部分单独存短期记忆摘要早期细节如果需要通过长期记忆检索补全。这个策略跑下来回答质量不仅没下降反而因为Prompt更聚焦而有所提升。裁剪不是丢信息而是把信息按当前需要重新组织。我总结的经验是先定必须留在窗口里的底线再谈压缩不要盲目裁剪。7. 最后一公里把Agent封装成可部署的服务到这里Agent已经能带记忆、能检索、能容错、能结构化输出但还差最后一步——让它真正跑在服务里被外部系统调用。我用了FastAPI来做这层封装实测起来还是顺手的。7.1 无状态服务 外部会话存储服务实例要支持水平扩展就必须保持无状态。Agent实例可以被创建和销毁真正需要持久化的是会话状态和长期记忆。封装时维护一个session_pool用会话ID索引内存中的Agent实例对话结束后同步记忆到外部存储。from fastapi import FastAPI, HTTPException app FastAPI() app.post(/api/chat) async def chat(session_id: str, user_message: str): if session_id not in sessions: sessions[session_id] create_agent_ws_memory(session_id) agent sessions[session_id] response agent(user_message) return {session_id: session_id, reply: response}这样服务重启后记忆还在。水平扩容时加节点即可不需要在应用层维护跨节点的Agent状态。7.2 模型分级与成本控制生产跑起来后我观察到一个现象不是每轮对话都需要大模型。闲聊、寒暄、简单查询这些低难度请求用轻量模型就够了真正复杂的多步推理、工具编排才需要调用大参数模型。AgentScope的模型配置支持多模型组合我按意图分流处理实测成本下降了约四成。如果你做的量大这个优化值得投入。7.3 从单Agent到多Agent协作的演进一个带记忆的Agent已经能解决不少问题但真实业务往往是多角色的。做客服系统的话你需要接待Agent和质检Agent做数据分析的话你需要解析Agent和执行Agent。AgentScope的msghub可以在多个Agent之间做消息广播Pipeline可以做流程编排。我目前已经在设计一个客服回复风险预警的双Agent流程回复Agent生成内容预警Agent独立检查消息中是否有敏感或风险词。这种拆分的价值在于Agent各司其职、各持一套记忆整个系统的可维护性明显更高。最后分享一个实操体会搭完这个记忆型Agent我最大的收获并不是会用它了而是理解了Agent在生产环境真正难在哪。模型的进步是快但工程上的记忆隔离、输出稳定、成本控制每一件都是体力活也都是决定产品能不能真正跑下去的关键。你如果也想上手建议先把我前面第2节的最小闭环跑通然后立刻按第3、4节的思路去做隔离和结构化最后再逐步加RAG和多Agent协作。这一步一个脚印比直接去啃一个大而全的项目更稳。
