1. 为什么我要从零手搓一个记忆型 AI Agent先说结论市面上大部分所谓“AI Agent 框架”本质上只是把大模型的 API 包了一层加了个循环调用真正落到生产环境里记忆管理、流式输出、人机协同、可观测性这几块几乎全是坑。我自己在做一个企业级智能助手项目时前后换了三套方案最后决定基于 AgentScope 从零构建一个带长期记忆的生产级 Agent这篇文章就是把整个过程中的技术选型、架构设计、踩坑记录一次性讲透。如果你正在做 AI Agent 开发或者想从 0 到 1 搭建一个能真正上线的 Agent 系统而不是停留在 demo 阶段那这篇内容应该能帮你省掉至少两周的试错时间。我会围绕 AgentScope 这个框架把 DDD 架构分层、SSE 流式输出、HITL 人机协同、多 Agent 编排、记忆系统设计这几个核心模块全部拆开讲每个环节都附上我实际跑通的代码和参数配置。先厘清一个高频困惑AI Agent、LLM、AI 模型到底什么关系大模型比如 DeepSeek、GPT 系列是“大脑”负责理解和生成LLM 是这类大语言模型的统称而 AI Agent 是在 LLM 之上加了一层“手脚和记忆”——它能调用工具、能记住上下文、能自主规划步骤、能在多轮交互中保持状态。简单类比LLM 是一个博学但失忆的顾问你每次问他都得把背景重新讲一遍AI Agent 则是给他配了笔记本、电话簿和一套工作流程他能自己查资料、记笔记、分步骤完成任务。AgentScope 就是帮你把这套“笔记本工作流程”标准化的框架。2. AgentScope 核心架构与 DDD 分层设计2.1 为什么选 AgentScope 而不是自己裸写我最初是直接用 Spring AI 裸写 Agent 循环的大概两百行代码就能跑通一个带工具调用的 Agent。但问题很快暴露当 Agent 数量增加到 5 个以上、需要互相通信时消息路由、状态同步、错误重试这些逻辑开始失控。AgentScope 的价值在于它把这些分布式 Agent 的通信原语抽象好了你只需要关注业务逻辑。AgentScope 的核心抽象有这么几层Message消息Agent 间通信的基本单位、Agent智能体可以是 LLM 驱动的也可以是纯规则驱动的、Pipeline流水线定义多个 Agent 的编排顺序、Memory记忆短期对话历史和长期知识存储、Tool工具Agent 可以调用的外部能力。这套抽象和 DDD 的分层思想天然契合下面我展开讲怎么落地。2.2 DDD 四层架构在 Agent 系统中的映射DDD领域驱动设计放到 AI Agent 场景里我的分层是这样的DDD 层Agent 系统对应模块职责用户接口层Controller / SSE 端点接收请求、流式推送响应应用层AgentOrchestrator编排 Agent 调用流程、事务边界领域层Agent / Memory / Tool核心业务逻辑Agent 的决策与记忆基础设施层LLM Client / VectorStore / MQ大模型调用、向量存储、消息队列这么分的好处是领域层完全不依赖具体的大模型厂商你换 DeepSeek 还是换别的模型只动基础设施层的适配器就行。我实测下来从一家模型切到另一家改动量控制在 3 个文件以内。2.3 记忆系统的领域建模记忆是“记忆型 Agent”的灵魂。我把记忆分成三类在领域层用不同的聚合根表示短期记忆Working Memory当前会话的对话历史存在内存或 Redis 里TTL 设 30 分钟。超过 token 阈值就触发摘要压缩。长期记忆Long-term Memory跨会话的事实性知识存向量数据库用语义检索召回。情景记忆Episodic Memory历史任务的成功/失败案例用于 Agent 自我改进。这里有个关键设计决策短期记忆和长期记忆的写入时机不同。短期记忆每轮对话都写长期记忆只在检测到“值得记住的事实”时才写。我用的判断逻辑是让 LLM 做一次轻量分类prompt 大概是“以下对话是否包含用户偏好、事实性信息或重要决策只回答是或否”。这个额外调用会增加约 200ms 延迟但换来的是长期记忆库的干净非常值。3. SSE 流式输出从大模型到前端的实时渲染链路3.1 为什么必须用 SSE 而不是 WebSocket大模型回答实时渲染业界基本都用 SSEServer-Sent Events。原因很直接Agent 的输出是单向的、服务器推给客户端的流SSE 天然适配这个场景而且基于 HTTP穿透代理和网关比 WebSocket 简单得多。WebSocket 是全双工用在纯推送场景属于杀鸡用牛刀还要处理心跳、重连、协议升级一堆事。SSE 的协议格式很简单每条消息以data:开头以两个换行结尾。AgentScope 的流式输出最终会转成这个格式推给前端。3.2 后端流式链路的关键实现整条链路是LLM 流式 API → AgentScope 的流式事件 → Spring 的SseEmitter→ 前端EventSource。中间最容易出问题的是背压处理——如果 LLM 吐字速度比前端消费速度快缓冲区会堆积。我的做法是在SseEmitter上设一个超时我设的 120 秒并在应用层加一个令牌桶限流。GetMapping(value /agent/stream, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter streamAgent(RequestParam String sessionId, RequestParam String query) { SseEmitter emitter new SseEmitter(120_000L); executor.execute(() - { try { agentStreamService.stream(sessionId, query, chunk - { emitter.send(SseEmitter.event().data(chunk)); }); emitter.send(SseEmitter.event().name(done).data([DONE])); emitter.complete(); } catch (Exception e) { emitter.completeWithError(e); } }); return emitter; }注意那个name(done)事件前端靠它判断流结束。没有这个结束标记前端会一直等最后触发超时。3.3 前端实时渲染与 abort 中断前端用EventSource接收每收到一个 chunk 就追加到消息气泡里。这里有个体验细节不要每个字符都触发一次 DOM 更新用requestAnimationFrame做批量渲染否则长回答会卡。中断abort功能是生产环境必备的。用户点了停止按钮前端调eventSource.close()同时后端要能感知到连接断开并停止 LLM 调用否则白白烧 token。后端通过emitter.onCompletion()和onTimeout()回调来清理资源并在 LLM 客户端侧设置一个AtomicBoolean标志位流式循环里每轮检查一次。提示SSE 连接断开后如果后端没有及时停止 LLM 调用一次长回答可能浪费几千 token。务必在onCompletion回调里显式取消上游请求。3.4 那个经典的 idle timeout 报错怎么破很多人遇到过stream disconnected before completion: idle timeout waiting for sse。这个报错的根因是SSE 连接在某个时间段内没有任何数据推送被中间的网关或负载均衡器判定为空闲连接然后掐断。解决方案有三层应用层心跳每 15 秒推一个注释行: heartbeat保持连接活跃。网关超时配置把 Nginx 的proxy_read_timeout调到 300 秒以上。LLM 侧超时给大模型客户端设一个合理的首 token 超时我设 30 秒避免上游卡死导致下游空等。三层都配上之后我这边连续跑了一周压测没再出现过 idle timeout。4. HITL 人机协同让 Agent 在关键节点停下来4.1 什么场景需要 HITLHITLHuman-in-the-Loop不是所有 Agent 都需要但生产级 Agent 几乎绕不开。典型场景Agent 要执行一个不可逆操作比如删除数据、发送邮件、下单这时候必须停下来等人类确认。我见过太多 demo 让 Agent 直接调工具执行上线第一天就出事。AgentScope 支持在 Pipeline 里插入一个“审批节点”Agent 执行到这一步会挂起把待确认的操作推给前端等用户点“确认”或“拒绝”后再继续。4.2 挂起与恢复的状态管理HITL 的技术难点在于状态持久化。Agent 挂起时整个执行上下文当前步骤、已收集的参数、中间结果必须存下来等用户响应后能精确恢复。我用的是“检查点”模式每次 Agent 要执行敏感操作前把上下文序列化存到数据库生成一个approvalId返回给前端。public class ApprovalCheckpoint { private String approvalId; private String sessionId; private String pendingAction; // 待执行的操作描述 private MapString, Object context; // 执行上下文快照 private ApprovalStatus status; // PENDING / APPROVED / REJECTED private Instant createdAt; }用户确认后前端带着approvalId调恢复接口后端反序列化上下文从检查点继续执行。这里要注意上下文的序列化兼容性——如果 Agent 逻辑升级了旧检查点可能反序列化失败所以我在上下文里存了一个schemaVersion字段做版本校验。4.3 超时与降级策略审批不能无限等。我设了两级超时5 分钟未响应前端提示“审批即将超时”10 分钟未响应自动标记为 REJECTED 并通知用户。降级策略是敏感操作被拒绝后Agent 不是直接失败而是走一个“安全替代路径”——比如把“删除数据”降级为“标记为待删除”让用户后续手动处理。5. 多 Agent 编排与记忆共享实战5.1 多 Agent 的通信模式AgentScope 2.0 里配置多 Agent 调用核心是定义好消息传递的拓扑。我常用的两种模式流水线模式PipelineAgent A 的输出直接作为 Agent B 的输入适合有明确先后顺序的任务比如“检索 Agent → 分析 Agent → 总结 Agent”。广播模式Broadcast一个协调 Agent 把任务分发给多个执行 Agent收集结果后汇总。适合可并行的子任务。配置多 Agent 时最容易踩的坑是消息格式不一致。我的经验是定义一个统一的AgentMessage结构包含role、content、metadata三个字段所有 Agent 的输入输出都走这个结构避免解析混乱。5.2 记忆在多 Agent 间怎么共享多 Agent 场景下记忆共享是个设计难题。全共享会导致上下文爆炸不共享又会导致信息孤岛。我的方案是“分层共享”全局记忆所有 Agent 都能读的事实性知识用户画像、业务规则存向量库。会话记忆同一会话内所有 Agent 共享的对话历史存 Redis。私有记忆单个 Agent 的工作草稿只存在该 Agent 实例内。写入策略上只有全局记忆需要走“是否值得记住”的判断会话记忆直接追加私有记忆随 Agent 生命周期销毁。5.3 一个真实的多 Agent 协作案例我做过一个“智能合同审查”场景用了三个 Agent提取 Agent负责从合同文本里抽取关键条款比对 Agent负责和标准模板比对找出差异建议 Agent负责生成修改建议。三个 Agent 通过 Pipeline 串联共享一个会话记忆。实测下来这个组合比单个大模型一次性处理准确率高了不少——因为每个 Agent 的 prompt 可以高度聚焦提取 Agent 只管抽取不管判断比对 Agent 只管比对不管生成职责单一后幻觉明显减少。整个流程平均耗时 8 秒其中提取 3 秒、比对 2 秒、建议 3 秒。6. 常见问题排查与避坑速查6.1 流式输出相关问题现象根因解决方案前端收不到数据响应头没设text/event-stream检查produces配置流中途断开网关空闲超时加心跳 调大网关超时中文乱码编码未指定 UTF-8响应头加charsetUTF-8最后一条消息丢失没发结束标记显式发送[DONE]事件6.2 记忆系统相关长期记忆检索不准八成是 embedding 模型和查询语义不匹配。我的经验是写入时用文档的完整语义做 embedding检索时把用户 query 改写成陈述句再 embedding命中率能提升 20% 以上。另外向量库的相似度阈值别设太高0.7 左右比较合适太高会漏召回太低会引入噪声。6.3 我踩过的三个大坑第一个坑Agent 死循环。Agent 调用工具失败后不断重试把 token 烧光了。后来我加了最大迭代次数限制默认 10 次和失败熔断。第二个坑记忆污染。早期我把所有对话都写进长期记忆结果检索出来的全是废话。后来加了写入判断长期记忆库干净多了。第三个坑并发会话串扰。多个用户同时用sessionId 没隔离好A 的记忆串到了 B 那里。这个必须用严格的 session 隔离每个会话的记忆命名空间独立。7. 从练手到上线的学习路径建议如果你刚开始接触 AI Agent 开发我的建议是分四步走。第一步先用 AgentScope 跑通一个单 Agent 单工具的 demo理解消息流转。第二步加上短期记忆和 SSE 流式输出做一个能对话的助手。第三步引入长期记忆和向量检索让它能记住跨会话的信息。第四步加多 Agent 编排和 HITL这时候就接近生产级了。每一步都别跳过尤其是记忆系统很多人直接上多 Agent 结果记忆一团糟回头重构的成本极高。面试里常问的“AI Agent 组成结构”标准答案就是LLM 大脑 记忆系统 工具调用 规划模块 执行循环这五块缺一不可。关于 AgentScope 中文文档官网的示例偏基础真正生产级的配置比如多 Agent 的容错、记忆的持久化需要自己啃源码。我个人的习惯是先把核心类的继承关系画出来再顺着调用链读比逐行看快得多。最后分享一个我实际用下来很稳的配置短期记忆 TTL 30 分钟、长期记忆检索 top-k 设 5、SSE 心跳 15 秒、LLM 首 token 超时 30 秒、Agent 最大迭代 10 次。这套参数在我这边跑了三个月日均处理几千次会话稳定性没问题。当然具体数值还得根据你的业务量和模型响应速度微调但作为起点足够用了。