AI Agent最近两年成了大家讨论最多的话题但真正能跑在生产环境里的Agent其实不多。很多时候我们看到的Demo很热闹一落到业务里就发现缺这缺那上下文记不住、状态一断就丢、跟业务系统接不上。这次我想从零开始基于AgentScope把一个带持久记忆的AI Agent完整搭起来把这套过程中的设计取舍和实操细节一起复盘出来。如果你刚接触智能体开发或者已经在用LangChain这类框架想看看AgentScope到底适不适合自己的场景这篇文章应该能帮你少走不少弯路。标题里最值得玩味的是“生产级记忆型”这六个字。这意味着我们不是搭一个玩具级的聊天机器人而是要做成可以长期运行、能记忆用户偏好和业务上下文、能稳定接入外部系统的智能体。我从项目立项、架构设计、代码实现到部署上线完整走了一遍里面踩过的坑绝对比顺滑的部分多得多所以这篇内容我会尽量把“为什么这样做”也讲清楚而不是只丢一堆代码。1. 项目全景拆解我要构建的“记忆型 AI Agent”到底是什么1.1 从标题看核心需求先拆一下“从零构建一个生产级记忆型 AI Agent”这个标题。它其实压着三层需求第一层是从零构建。不是二次开发不是给开源项目打补丁而是从空目录开始设计工程骨架。这就需要我们对底层通信机制、消息流转、插件化能力都有一定掌控力不能只会调用高级API。第二层是生产级。生产级意味着要面对真实流量、真实数据、真实故障。请求可能超时模型可能抽风向量库可能出问题用户可能把Agent聊到逻辑混乱。这要求系统有清晰的模块边界、可观测性和容错能力而不是单机脚本。第三层是记忆型。这是整个项目的灵魂。AI Agent如果没有记忆每次问答都是“第一次见面”的新人所有对话都是无状态的。而记忆型Agent至少要做到三件事记住用户说过什么记住自己之前给过什么结论记住业务场景中沉淀下来的规则和知识。这三层缺一不可。只做“从零构建”可以选一个简单框架随便搭只做“生产级”可以不用Agent直接用服务编排只做“记忆型”可以写一个RAG demo。但把三者叠加难度是相乘的不是相加。1.2 为什么选 AgentScope 而不是从零造轮子市面上做AI Agent的框架不少各有各的偏科。AgentScope最吸引我的是它对“智能体”这个概念的建模方式它有清晰的消息对象、Agent生命周期、分布式通信机制同时提供了比较高阶的RAG能力和多语言支持。在AgentScope 2.0里还出现了“RAG as Service”的方向这给我的记忆型Agent架构带来了很大的便利。选AgentScope还有一个现实原因它的能力边界比较收敛。它没有把所有事情都替你做完而是给你提供可扩展的接口。比如消息传递机制是它的核心你可以在消息上挂各种元数据记忆管理和检索可以对接外部向量数据库也可以用官方提供的高级组件。这种“框架管通信、业务管逻辑”的做法在生产级项目里其实更好维护。如果你用过其他Agent框架会有一种感觉框架绑定太深很多底层细节被黑盒封装出了问题根本不知道在哪一层。AgentScope虽然也在封装但它的模块设计能让你快速定位问题这在生产环境里是很大的优势。1.3 适用范围与能力边界在动手之前建议先明确能力边界。记忆型AI Agent不是万能的它适合做这些事长期陪伴型助手能记住用户过去聊过的兴趣、偏好、待办事项企业内部知识助手能记住不同部门的术语、项目背景、历史决策复杂任务规划需要在多个轮次中持续推进而不是一次性问答。但如果你需要的只是一个“客服自动回复机器人”输入问题输出答案不需要跨会话记忆那用AgentScope确实有点大炮打蚊子。另外如果你的业务场景对生成内容准确性要求极其苛刻比如医疗诊断、法律合同那现阶段任何Agent都不能做到完全可靠必须在系统外层加人工审核和规则兜底。2. 生产级 AI Agent 的整体架构与核心设计2.1 从“单轮问答”到“有记忆的大规模交互”传统大模型应用是“用户发送请求→模型生成回复→结束”整个过程无状态。但生产级Agent必须能处理上千轮对话、多个并发会话、不同用户的隔离记忆。所以架构上最基础的变化是把有状态会话和无状态推理做彻底分离。我的设计里Agent的核心不再是一个大Prompt而是一个具备三层结构的运行体接收消息、维护状态、执行决策。用户消息进来后先是接入层校验和解析然后把消息写进短期记忆接着Agent从长期记忆里召回相关信息和当前消息拼装成模型输入模型生成决策后再把决策写入记忆。这样每一轮交互都同时带着“过去的我”和“现在的我”。这听起来不复杂但很多Agent项目失败就失败在状态管理上。如果所有状态都塞在内存里进程一重启全丢如果都塞在数据库里每次对话都要做大量I/O如果状态没有隔离用户A的对话可能会污染用户B的记忆。所以架构设计必须一开始就考虑存取路径和隔离策略。2.2 模块拆解会话层、记忆层、规划层、执行层我最终把系统拆成了四个核心层。会话层负责接收和发送消息把不同渠道的请求格式统一成AgentScope的Msg结构。记忆层负责短期和长期记忆的读写是这次项目的重点。规划层决定Agent下一步要做什么是直接回答还是调用工具还是需要追问用户。执行层负责真正调用外部工具或服务比如查数据库、发邮件、调用业务API。这样的拆法有几个好处。第一每一层可以独立测试会话层挂了不会影响记忆层的数据。第二每一层都可以独立扩缩容比如记忆层连接的是向量数据库和Redis瓶颈在I/O可以单独加缓存。第三规划层可以被替换比如初始用大模型直接决策后续想接入强化学习策略只需要改这一层。在AgentScope里Agent和Agent之间的通信也遵循类似的分层逻辑。每个Agent是一个独立节点消息通过AgentRuntime分发。我的做法是让主Agent作为“调度者”它负责解析用户意图然后转发给不同的子Agent处理。子Agent只处理特定类型的任务完成后把结果回传。这种多智能体分工结构在业务复杂的时候比单Agent堆Prompt要好维护得多。2.3 记忆分层的具体方案记忆不是一块硬盘它应该分层。我参考了认知科学里对记忆的分类方式结合工程可实现性把记忆分成了四类第一类是会话短期记忆也就是当前对话窗口里的上下文。这个用Redis或者共享内存做就行TTL设置成30分钟到2小时过期自动清理。第二类是工作记忆指当前正在执行的任务状态。比如用户正在填一份申请表填到第二步了这个进度要保存下来。工作记忆需要有结构的存储比如JSON存到数据库里任务完成后归档。第三类是一般长期记忆包括用户偏好、历史问答记录、关键结论。这类记忆适合做向量化后存到向量数据库里用语义检索召回。第四类是领域知识库也就是业务文档、操作手册、规则条款。这类记忆属于静态知识适合用RAG方案定期更新索引。上面四类对应到AgentScope里短期记忆和工作记忆可以直接挂在会话消息中长期记忆和知识库则通过RAG as Service做统一接入。这个分层方案看起来绕但实际跑起来以后排查问题上非常舒服用户说“你忘了”可能是长期记忆召回失败用户说“你怎么每次都问我”可能是短期记忆丢了用户说“你乱回答”可能是知识库检索到了错误片段。每一类问题都有明确的排查入口。3. 环境准备与工程骨架先把 AgentScope 跑起来3.1 安装与版本选型AgentScope目前已经发布了2.0版本功能比我最早接触的1.x版本要丰富很多。官方文档也提供了中文版搜索“agentscope中文文档”就能找到这对国内开发者非常友好。安装过程很简单Python环境推荐3.9以上然后执行pip install agentscope如果你需要用到RAG相关能力2.0版本的特性是“RAG as Service”可以把它理解成把知识库检索做成一个独立的服务端点Agent通过服务接口调用而不是把检索逻辑硬编码在Agent内部。这样做的优势是知识库更新、切换向量库、扩容检索能力都不需要改动Agent主流程。Java开发者可能会有疑问Agentscope Java是完整的新实现吗早期AgentScope主要以Python为主后来官方社区陆续出现了Java SDK的适配和分享网上甚至有人整理了二十多篇关于agentscope java的系列文章。我的经验是如果核心服务是Python写的主链路上还是用Python最省心如果业务系统以Java为主可以启动一个独立的Agent服务通过HTTP/ gRPC让Java业务调用不要在Java侧强行复刻整个Agent Runtime。3.2 最小可运行示例一个会自我介绍的Agent为了让项目先跑起来我先写了一个最小Agent。这个Agent不接数据库、不做记忆只验证AgentScope的消息链路是否通。以AgentScope 2.0 Python接口为例大致写法如下import agentscope from agentscope.agent import Agent from agentscope.message import Msg agentscope.init( model_configs{ config_name: default_model, model_type: openai_chat, model_name: qwen-plus, api_key: your_api_key, temperature: 0.7 } ) agent Agent( nameassistant, model_config_namedefault_model, sys_prompt你是一个耐心、细致的个人助理。 ) user_msg Msg(nameuser, content你好请介绍下你自己) reply agent(user_msg) print(reply)这个例子如果跑通了说明模型接入、消息创建、Agent调用链路都没问题。在实际生产中需要把api_key用环境变量管理模型名称和参数也建议通过配置中心下发而不是硬编码在代码里。3.3 项目目录与工程化配置项目结构从一开始就不能太随意。我的工程骨架是这样的ai-agent/ ├── app/ │ ├── main.py # 服务入口 │ ├── agent/ │ │ ├── core_agent.py # 主Agent定义 │ │ ├── memory/ # 记忆模块 │ │ ├── tools/ # 工具调用 │ │ └── prompts/ # Prompt模板 │ ├── api/ # HTTP接口 │ ├── service/ # 业务服务层 │ ├── config/ # 配置中心 │ ├── tests/ # 单元/集成测试 │ └── utils/ # 工具函数 ├── data/ │ ├── knowledge/ │ └── vector_db/ ├── scripts/ └── requirements.txtapp/agent/memory里是记忆机制的实现app/api是暴露给外部系统的接口层。整个项目分成配置、业务、API三个大模块。配置集中的好处是以后部署到不同环境测试、预发、生成只需要替换配置中心里的值不用改代码。还需要加一个requirements.txt把版本锁住。生产环境最忌讳的就是依赖版本漂移今天跑得好好的明天pip一更新底层库不兼容了排查半天找不到原因。我习惯在requirements.txt里用锁版本并定期在测试环境统一升级。4. 核心记忆机制实现短期上下文与持久化记忆4.1 短期记忆会话消息的持久化短期记忆最直观的实现就是让Agent在每一轮对话中带上历史消息。AgentScope内部的消息列表天然支持多轮对话我们只需要把历史消息按顺序组织好再塞进新请求里。但在生产环境里直接把所有历史消息无限塞给模型是行不通的。一方面模型有上下文窗口限制另一方面历史过长会增加响应延迟和Token成本。我的做法是做一个滑动窗口最近20条用户消息必须完整保留超过20条但还在同一会话内的消息用摘要提取关键信息跨会话的信息不放在短期记忆里统一沉淀到长期记忆。短期记忆的存储我用Rediskey为会话IDvalue为消息列表的序列化数据。每次会话开始时加载对话过程中更新。会话结束或者超过TTL后清理。这套方案的好处是内存可控、速度足够快。要注意的是AgentScope的Msg对象除了content还支持metadata字段。我利用它在消息上打标签比如turn_id、timestamp、intent_type这样在做消息过滤和摘要的时候能按条件精确取数据。4.2 长期记忆向量库 RAG as Service长期记忆的核心是向量检索。用户在历史对话里提到过“我喜欢跑步”“我住在北京朝阳区”“我不吃香菜”这些碎片信息需要被编码成向量存到向量数据库里。当Agent接收新问题时把当前问题向量化从长期记忆库中召回最相关的几条记录再拼进Prompt。在AgentScope 2.0中RAG as Service把这个过程进一步服务化了。我的经验是不要自己去调Embedding接口、向量数据库读写、相似度计算那一整套而是把知识文档和用户记忆统一交给RAG服务管理。Agent需要什么知识直接发起检索请求服务返回Top-K相关内容。一个简化的实现思路如下from agentscope.rag import RagService rag RagService( collection_nameuser_memory, embedding_modelyour_embedding_model, vector_storemilvus, # 也可以是qdrant/chroma top_k5 ) relevant_memory rag.search(用户的运动偏好是什么) print(relevant_memory)这里有一个关键点长期记忆不是“一次写入永久有效”它有自己的生命周期。用户今天说喜欢跑步下周可能就骑自行车了。所以每条记忆都要带时间戳和置信度检索时按相关性和时间衰减做加权排序。老记忆如果长时间没有被命中可以进入“遗忘”队列由人工或定时任务决定是否归档。4.3 记忆读写与AgentScope消息机制的联动AgentScope的消息机制是我在整个项目里用得最爽的部分。它的Msg对象本质上是一个带类型的消息体除了文本内容外还能附带结构化字段。我的记忆模块就是通过这些字段和Agent主体联动的。流程大致是这样def process_user_message(user_msg: Msg): # 1. 从长期记忆召回 memory_hits rag.search(user_msg.content) # 2. 从短期记忆加载 session_cache redis_client.get(user_msg.metadata[session_id]) # 3. 组装成上下文 agent_context { current: user_msg.content, history: session_cache, memories: memory_hits } # 4. 交给Agent决策 response core_agent(agent_context) # 5. 更新短期记忆异步沉淀长期记忆 update_short_term_memory(user_msg, response) async_save_to_long_term_memory(user_msg, response)这里面最关键的是第5步。沉淀长期记忆不能同步写因为这会阻塞用户请求。我改成异步任务从对话中抽取“值得记住的事实”交给一个专用的记忆提取Agent它会判断哪些内容需要写入长期记忆库并且抽取结构化字段。记得给每条记忆加上session_id、user_id、timestamp否则未来要做用户隔离和记忆追溯都会非常痛苦。5. 完整实操链路从零构建一个生产级记忆型Agent5.1 定义Agent的个性与业务角色在写代码之前先把Agent的“人设”定下来。我这里是构建一个“个人事务助理”负责帮助用户记录待办事项、查询日程、推荐活动、回答一些常识问题。它的性格是耐心、简洁、不外露情感懂得在不确定时礼貌追问。这个环节看似虚实际非常重要。Prompt的system部分决定了Agent的决策风格。如果把system prompt写得过于笼统Agent在真实场景里会表现得很飘写得太死板用户又会觉得机器味太重。我参考了AgentScope教程里关于Prompt工程的经验采用“角色定义行为准则边界说明”三段式你是用户的个人事务助理名叫小策。 你需要记住用户透露的偏好、约定、重要日期。 回答问题时先思考最相关的记忆再组织回复。 如果不确定用户意图不要猜明确询问。 不要编造事实不知道就说明不知道。这段system prompt在生产环境里也不是一成不变的我后续会根据用户的真实反馈做版本迭代并记录不同版本的通过率变化。5.2 接上大模型与记忆存储基础Agent已经能跑通现在把记忆模块接进来。为了让效果可对比我用了三种配置跑同一组测试配置是否使用记忆效果表现A无记忆每次都重新认识用户回答正确但非常机械B仅短期记忆能持续当前对话但第二天就忘光了C短期长期记忆能主动提到用户之前的偏好个性化程度明显提升配置C的实现方式就是第4节写的方案。需要注意的是长期记忆的召回结果不能直接全部塞进Prompt否则相关内容太多又会把主题带偏。我一般设置Top-K3到5召回的片段长度也限制在200字以内。如果调研结果不够可以放宽召回数量但一定不能放松质量阈值。实测下来记忆型Agent最明显的改善并不是“答案更准”而是“对话更自然”。用户说“我想订个酒店”如果Agent记得用户上次出差常住某品牌酒店就会主动问“还是老样子吗”这种体验来自于长期记忆而不是模型推理能力。5.3 工具调用与外部系统对接生产级Agent必须能调用外部工具。我接了两个工具一个查询日程的日历服务一个保存待办事项的笔记服务。在AgentScope里工具调用可以通过定义工具函数并注册到Agent上。以一个简单的待办事项工具为例def add_todo(todo_text: str, due_date: str ) - str: 把用户交代的待办事项写入数据库 # 这里省略数据库写入细节 return f已保存待办{todo_text} # 在Agent上注册工具 agent.register_tool(add_todo)有一个我从早期项目中吸取的教训工具调用返回结果不要直接作为最终回复应该让Agent先理解工具结果再组织回复。比如工具返回“已保存”Agent应该回复“好的我已经记下了周日下午三点去机场接人到时候我会提醒你”。这一步就体现了Agent的规划能力和语言生成能力。工具调用还有一个通信细节AgentScope的消息中要把工具调用结果标记为function_result不能和普通用户消息混在一起。否则模型可能误以为工具结果也是用户输入回答时就容易出现“幻觉”。5.4 构建服务API与部署上线当Agent在本地跑通之后要把它变成可对外提供的服务。我用FastAPI包了一层接口把Agent核心和外部世界隔开from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class ChatRequest(BaseModel): session_id: str user_id: str message: str app.post(/agent/chat) async def chat(req: ChatRequest): response await run_agent( session_idreq.session_id, user_idreq.user_id, messagereq.message ) return {reply: response}这里比较重要的是会话和用户的身份隔离。AgentScope给每个Agent调用传入消息时如果在Msg.metadata里加上了user_id和session_id那么消息在后续流转中就不会互相串线。我在部署环境里给每个租户用的向量数据库collection做了隔离避免用户A的记忆泄漏到用户B那里。部署方面服务本身是无状态的可以水平扩展但需要把Redis和向量库改成独立部署。否则Agent实例扩容之后短期记忆还是单机内存那就白扩容了。我的部署架构是Agent服务Docker容器 Nginx负载均衡短期记忆Redis Cluster长期记忆Milvus或者Qdrant集群模型服务统一接入公司内部的模型网关上线之前一定要做压力测试。我试过用一个最简单的并发脚本压100个并发请求发现极限瓶颈不在Agent代码里而在模型服务的返回时长和向量库的查询QPS上。先压外围依赖再优化Agent内部逻辑这个顺序不要搞反。6. 常见问题与避坑实录6.1 AgentScope 1.x 到 2.0 的迁移问题如果你之前用的是1.x版本的AgentScope升级到2.0的时候要格外注意API变化。我在迁移过程中遇到的主要变化在消息结构和RAG调用方式上。1.x里你自己拼消息列表、自己写检索逻辑还比较常见2.0则强化了RAG as Service鼓励把检索从Agent逻辑中拆出去。迁移建议是先把核心功能回归一遍别急着上新特性。优先把消息传递跑通再逐步迁移记忆模块和工具注册。很多第三方教程还是基于旧版本写的所以看agentscope教程时一定要先确认版本号否则照抄会报一堆奇怪的错。6.2 记忆污染与上下文截断的坑记忆型Agent最常见的问题就是“记忆污染”。我举个例子有次测试时用户随口说了一句“我觉得这里太贵了”我的长期记忆模块把这句话当作偏好存了下来结果第二天用户问“有什么推荐的餐厅”Agent优先推荐便宜餐馆但用户其实是个高档餐厅爱好者。这就是把临时情绪误判成长期偏好的典型误伤。解决方法是给记忆分类加置信度标签。像“我不吃香菜”这种明确且反复出现的偏好置信度高像“太贵了”这种情绪化表达置信度低不能进长期记忆。另外还有个坑是上下文截断。AgentScope的窗口满了之后如果直接丢早期消息很多关键信息可能被丢掉。我建议对早期消息做“分段摘要”而不是粗暴截断。摘要本身也可以存入记忆下次用到时还能恢复细节。6.3 向量检索召回的准确率问题RAG方案的收益和痛苦都在召回环节。我调试记忆型Agent时经常发现该记住的事情根本没被检索出来。这通常不是模型的问题而是Embedding环节或检索策略的问题。几个经验第一不要只对用户问题做向量搜索可以把用户问题改写成一个查询语句比如“用户喜欢什么运动”召回效果会更好。第二需要把不同来源的向量放到不同集合里比如用户偏好集合和知识库集合分开避免互相干扰。第三Embedding模型的选型很重要泛化能力强的模型通常比专业领域小模型更适合做记忆召回因为用户对话非常口语化。6.4 Java调用与多语言协作在Java为主的团队里你会经常搜“agentscope java”。我的建议是不要期待Java SDK和Python SDK完全同构也不要自己徒手重新实现一遍。最省事的方式是把Python端的Agent服务部署成一个内部服务Java项目通过HTTP或gRPC调用。Java是中国企业后端的主力语言如果你们团队真要做AI Agent中台那更应该把Agent能力做成服务而不是在每个Java项目里嵌入Agent逻辑。我见过有些团队在Java侧和Python侧各维护一套配置和Prompt结果两边答案不一致。正确的做法是Agent逻辑完全收敛在Python服务里Java只负责业务编排和调用这样对账、灰度、回滚都只在一个地方做。6.5 评测指标如何定义“生产级”意味着可评测。如果上线前说不清楚Agent好不好那上线后一定会被用户的反馈淹没。我建了一套三层评测指标第一层是基础准确率包括回答是否包含正确事实、工具调用参数是否合法。 第二层是记忆能力包括跨会话是否能回忆起相关偏好、短期记忆是否在多轮后仍然保持一致。 第三层是体验指标包括用户修改一次错误后Agent下一次是否不再犯同样的错对话是否自然地使用了之前的信息。我还构建了一个回归测试集里面放了50条用户问题覆盖常见场景。每次改动Prompt或记忆策略都跑一遍回归集对比回答质量的整体上升或下降。不要凭感觉调参否则越调越乱。7. 学习路线与项目扩展建议7.1 从练手小项目到中台化如果你是刚开始学AI Agent建议不要直接上“生产级”项目先做一个练手小项目。可以用AgentScope搭一个“记住你名字的聊天机器人”第一天测试它能否记住名字第二天测试它能否记住你的爱好第三天测试它能否综合这些信息给你推荐东西。把这三个小目标做完你对Agent的消息、记忆和推理链路就会有直观理解。等练手项目跑通再去看那些大厂盘点的AI Agent产品就会发现大家的底层能力其实都是相通的会话管理、工具调用、记忆检索、模型路由。理解了一套框架再迁移到别的框架不会太难。如果是在企业里做AI Agent中台还需要把Agent配置、Prompt版本、模型密钥、知识库权限都收归统一管理。AgentScope作为开源框架可以承担底层运行时但中台的权限设计和审核机制要靠团队自己建设这是另一块硬骨头。7.2 值得关注的方向从AgentScope 2.0的演进来看RAG as Service正在把知识管理从Agent里彻底抽离出来。未来Agent的记忆能力会越来越像一个独立基础设施你不需要在Agent里判断用什么向量库、用什么Embedding模型只需要声明“我要一个长期记忆服务”。这种服务化趋势会让Agent的应用门槛大大降低。另一个值得关注的方向是多Agent协作。我的个人事务助理里主Agent调子Agent干活就是最简单的多Agent。生产级系统里可以把客服、知识检索、任务执行拆成不同Agent通过消息中间件协同工作。Agent之间的消息通信也需要统一格式和超时机制一旦子Agent不回复主Agent要有降级策略。7.3 我的一些心得体会把整个项目从零跑通以后我最大的体会是Agent框架只是底牌真正决定项目上限的其实是“记忆的组织方式”。你可以用很牛的大模型但没有合理的记忆机制它依然做不了一个称职的私人助理反过来即使模型不是最顶尖的只要记忆分层清晰、检索精准用户的体验依然可以非常好。还有一点经验是生产级不是“一次做成”而是“可持续迭代”。我的第一版记忆型Agent问题很多但它让我有了一个可以观察、可以改进的系统。之后每次迭代都围绕具体的失败案例做调整比如上周一条记忆召回丢了这周就加日志跟踪。持续做下去Agent会真的越来越像“了解你的人”。如果你也想从零开始做类似的项目建议先从最小的对话闭环做起然后加上短期记忆再加长期记忆最后接工具调用。每一步都要留测试集、留日志、留复盘记录不要着急一次到位。AI Agent这个领域往后还会涌现更多新玩法但只要底层的工程能力扎实你随时都能跟上。