Engineering

04. 你的 Agent 越改越乱？先把这 8 个对象分开 系列来源：本文属于 Agent 开发系列，内容来自 gusibi/molibot 的真实开发记录与项目文档整理。这是系列第四篇，前三篇分别讲了 Agent 的四层分类、runtime 整体架构和最小 run 闭环——没看过不影响理解本篇。 你有没有过这种经历—— Agent demo 跑通以后，你开始往上加功能。文件上传、图片生成、记忆、停止命令、trace 页面。 然后系统开始变乱。 加个「停止」功能，不知道该停哪一次执行。工具失败了，模型却看不到错误。清理临时文件，把用户要的报告一起删了。排查线上问题，只能翻聊天记录猜。 你以为是代码写得不好。其实不是。 是对象混在了一起。 Session 和 run 混了，停止命令不知道该停哪次执行。 Tool result 和 assistant answer 混了，模型看不到真实工具结果。 UI notice 和 message 混了，临时控制污染后续上下文。 Artifact 和 attachment 混了，用户上传的文件和 Agent 生成的产物一起被清理。 Trace fact 和业务消息混了，排障记录又被回灌给模型。 这些问题，demo 阶段一个都看不出来。因为只有一条消息、一个工具、一次执行，混了也能跑。 但系统只要长期运行，边界就会反过来找你。 这篇不画漂亮的类图，只回答一个问题：Agent runtime 里，哪些东西必须分开？ 一个对象混乱的事故 先看一个真实场景。 用户发来： 帮我分析这个日志文件，如果里面有异常，生成一份报告。 系统做了四件事：读日志、调模型分析、生成 HTML 报告、把链接发给用户。 这时用户又补了一句： 先停一下，我发现上传错文件了。 如果对象边界不清，这里会同时出现五个问题。 第一，系统不知道「停一下」要停哪次执行。它只有 session，没有 run。session 里有很多消息，但没有一个明确的 active run。 ...

03. 没有 Run 对象，你的 Agent 只是个高级 Chatbot 套壳 系列来源：本文属于 Agent 开发系列，内容来自 gusibi/molibot 的真实开发记录与项目文档整理。这是系列第三篇，前两篇分别讲了 Agent 的四层分类和 runtime 的整体架构——没看过不影响理解本篇。 你有没有过这种经历—— 线上 Agent 出问题了，你翻日志翻了半小时，还没搞清楚它当时到底在执行哪个任务。用户问"刚才那个请求还在跑吗"，你只能回答"大概吧"。服务一重启，内存里那些 running 状态全丢了，外面还以为任务卡住了。 如果你有过，那这篇就是写给你的。 上一篇我们区分了 Chatbot、Tool-using Chatbot、Agent Service 和 Agent System。结论很简单：差别不在模型，而在 runtime。 但 runtime 这个词还是太大了。真正落到工程里，第一个问题应该更小： 一条用户消息进来以后，系统到底怎么把这一轮跑完？ 先别急着做多 Agent。也别急着接 Telegram、飞书、微信。更不要一开始就设计一堆工具市场、插件系统、长期记忆。 如果一轮 run 都跑不清楚，后面所有功能都会挂在一团不稳定的东西上。 没有 Run 对象的 Agent 系统，本质上还是个 Chatbot 套壳。 这一篇只讲一件事：一个最小 Agent 服务，如何把一轮 run 跑清楚。 为什么先讲 run？ 很多 Agent demo 没有 run 的概念。 用户发来一句话，程序把历史消息拼一下，调用模型。模型要工具，就执行工具。最后把回答发回去。 看起来也能跑。 ...

02. 从 Chatbot 到 Agent Service：差别不在模型，而在运行时 系列来源：本文属于 Agent 开发系列，内容来自 gusibi/molibot 的真实开发记录与项目文档整理。 上一篇我们先画了一张地图：一个 Agent 系统不只是模型和工具，还会自然长出入口层、runtime、工具层、状态层、权限层、观测层和后台。 但如果只看概念，这些层还是有点抽象。 所以这一篇先解决一个更具体的问题：Chatbot、Tool-using Chatbot、Agent Service、Agent System 到底有什么区别？ 这个问题很重要。 因为很多团队第一次做 Agent，最容易卡在这里：系统明明已经能调用工具了，却还是很难稳定地交给用户用。用户一刷新，状态没了；工具失败后，模型不知道发生了什么；任务执行一半，用户想停止，后台还在跑；生成出来的文件，本地能看到，发到平台却失败。 这时如果继续堆 prompt，通常没用。 问题不在模型，而在运行时。 先用一个真实任务来看差别 假设用户发来这样一个需求： 帮我生成一张赛博朋克风格的猫咪海报。 如果效果可以，再用这张图生成 5 秒短视频。 最后把图片和视频都发给我。 这个任务很适合用来区分不同系统。 它看起来只是“调用两个工具”：先生成图片，再生成视频。 但真实执行时，马上会出现很多细节： 图片生成是同步返回，还是异步任务？ 图片结果是本地路径，还是公网 URL？ 视频服务能不能访问本地文件？ 生成成功但平台上传失败，算不算失败？ 用户中途说“停一下”，已经提交的视频任务怎么办？ 后台能不能查到这个任务用了哪个模型、哪个工具、哪个 provider？ 用户第二天追问“昨天那张图再换个风格”，系统还能找到原始结果吗？ 如果这些问题没有回答，你做出来的可能只是一个能演示的工具链，不是一个 Agent 服务。 下面我们按四个层级来看。 第一层：Chatbot 只负责回答 最普通的 Chatbot 会怎么处理这个任务？ 它会回答一段文字。 可能是这样： 当然可以。你可以先使用图片生成模型生成一张赛博朋克风格猫咪海报， 再把生成结果作为参考图传给视频生成模型。 这个回答不一定错。 但它没有做事。 ...

01. 课程导读：Agent 服务和 Agent 系统的全景图 你是不是也遇到过： 看了一堆教程，写了一个能调用工具的 Agent demo，自己跑起来样样都好 真接给用户用，刷新就丢状态，工具错了模型不知道，用户喊停了后台命令还在跑 想接第二个渠道，发现 80% 代码要重写 这些问题，从来都不是模型聪不聪明的问题。 它们属于另一件事：你有没有把 Agent 做成一个服务。 一句话记住：Demo 拼模型能力，服务拼工程边界。 这组文章要讲的，就是这件事。 不是怎么调一个大模型 API。不是怎么写一句神奇 prompt。也不是把几个工具函数绑到模型后面，然后说"这就是 Agent"。 我想从一个真实系统的角度，拆开看：一个 Agent 服务从最小闭环走到完整系统，中间到底要补哪些层。你读完这一篇，先不需要记住所有细节，但应该有一张地图。后面每篇文章，都能在这张地图上找到位置。 为什么"能聊天"不等于 Agent 服务？ 普通聊天机器人只需要完成一件事：用户问一句，模型答一句。 它也可以有多轮上下文，但本质上还是"生成回复"。只要回答看起来合理，这一轮就结束了。 Agent 不一样。 Agent 的关键不是"会说"，而是"会做"。它可能要读文件、查网页、执行命令、调用图片生成服务、创建定时任务、写入记忆、等待用户审批、把结果发回不同平台。 只要开始"做事"，系统就不再只是模型调用了。 因为做事会带来后果。 比如用户让 Agent 修改一个配置文件。一个聊天机器人可以告诉你"应该这么改"。一个工具增强聊天机器人可能会真的写文件。但一个 Agent 服务还要继续回答： 写之前有没有确认路径在允许范围内？ 写坏了有没有记录旧内容？ 工具失败后，模型能不能看到失败原因？ 用户中途停止时，文件写入有没有被打断？ 最终结果有没有保存到这次 run 的记录里？ 过几天排查问题时，能不能知道当时发生了什么？ 这些问题如果没有答案，系统可能仍然能 demo，但很难交给真实用户长期使用。 所以这组文章的第一条判断是： Chatbot 关心回答。 Agent Service 关心一次行动如何被执行、记录、恢复和约束。 Agent System 关心这些能力如何跨渠道、跨任务、跨模型长期运行。 这三者不是名字上的区别，而是工程边界的区别。 ...

系列来源：本文属于 Agent 开发系列，内容来自 gusibi/molibot 的真实开发记录与项目文档整理。 原文：02-内容创作/02-图文长文/agent-dev-series/01-course-map.md 重写说明：本文是 01-course-map.md 的重写版，保留原有核心观点，调整了结构和表达，并更换了标题。 为什么很多 Agent Demo 能跑却不能上线？一张图讲清 Agent 服务全景 你可能见过这样的 Agent demo：能聊天，能调用工具，能读文件，甚至还能生成图片。看着很厉害。 但真把它接给用户，问题立刻就来。 用户刷新页面，刚才那个任务还在不在？工具执行失败了，模型还知不知道失败原因？用户发了一句"停一下"，后台命令真的停了吗？如果同一个 Bot 同时接 Telegram、飞书和 Web，排队、审批、记忆和上下文到底写在哪里？ 这些都不是"模型聪不聪明"的问题。 它们是另一件事：你有没有把 Agent 做成一个服务。 这组文章要讲的就是这件事。不是怎么调大模型 API，不是怎么写一句神奇的 prompt，也不是把几个工具函数绑到模型后面就叫 Agent。我想从一个真实系统的角度拆开看：一个 Agent 服务从最小闭环走到完整系统，中间到底要补哪些层。 这一篇你不用记住所有细节，但读完应该手里有一张地图。后面每篇文章，都能在这张地图上找到自己的位置。 为什么"能聊天"不等于 Agent 服务？ 普通聊天机器人只做一件事：用户问一句，模型答一句。 它也能有多轮上下文，但本质还是"生成回复"。只要回答看起来合理，这一轮就结束了。 Agent 不一样。它的关键不是"会说"，而是"会做"。它可能要读文件、查网页、执行命令、生成图片、创建定时任务、写入记忆、等待审批、把结果发回不同平台。 只要开始做事，系统就不再只是一次模型调用了。 因为做事会带来后果。 比如用户让 Agent 改一个配置文件。聊天机器人会告诉你"应该这么改"；工具增强的聊天机器人可能真的去写文件；但一个 Agent 服务还得继续回答这些问题： 写之前确认过路径在允许范围内吗？ 写坏了，旧内容有没有留底？ 工具失败了，模型能看到失败原因吗？ 用户中途喊停，文件写入会不会被打断？ 最终结果有没有存进这次 run 的记录？ 过几天排查，能不能还原当时发生了什么？ 这些问题没有答案，系统也许还能 demo，但很难交给真实用户长期用。 所以这组文章的第一条判断是： Chatbot 关心回答。 Agent Service 关心一次行动如何被执行、记录、恢复和约束。 Agent System 关心这些能力如何跨渠道、跨任务、跨模型长期运行。 这三者不是名字的区别，是工程边界的区别。 ...