多Agent协作如何管？注册表+状态机+Harness隔离实战

1. 一次失败的多agent协作把我逼到管理这个话题面前最开始我觉得agent管理是个伪命题。模型给我prompt写好工具挂上不就是一个agent了吗直到我一次性跑了六个agent让它们协作完成一个跨部门的数据汇总任务结果三个agent在抢同一个临时文件的写权限两个agent把对方的上下文覆盖了还有一个agent把自己循环调用了十七次。那一刻我意识到单点agent的能力再强一旦数量上来真正的瓶颈全部集中在管理上。这篇就是我第一次认真做agent管理的完整记录包括我踩过的坑、推翻过的设计以及最后沉淀下来的一套管理思路。适合刚从单agent调用转向多agent协作的同学参考。站在2025年这个时间点再看AI Agent早就不是一个能对话的聊天机器人了而是能调工具、能查数据、能自动执行任务的数字员工。我所在的团队做数据自动化处理最开始只是让一个agent帮我们写SQL、跑报表后来业务方提出能不能让agent自己完成从取数到出报告的全流程于是六个agent在同一天上线了。1.1 六agent翻车的完整复盘那次任务大致是这样每个agent负责一个数据源采集完之后把结果写入同一个临时目录最后由汇总agent生成报告。听起来没什么问题但运行到一半我就发现不对劲了。三个agent几乎同时写同一个文件后写入的覆盖了先写入的最终报告里出现了大量重复数据。两个agent共享了同一个会话上下文其中一个agent的好几次中间推理过程被另一个agent读到导致它后面输出的语气、格式甚至结论都开始跑偏。还有一个agent在处理异常时进入循环反复调用数据分析工具十七次浪费了大把token还阻塞了后面任务的执行。这个问题既不在于某个模型能力不行也不在于prompt写得差而在于这些agent之间没有身份边界、没有状态管理、没有权限控制。说白了它们乱成了一团缺少一个管理者。1.2 拆解下来agent管理管的是四件事那次翻车之后我认真琢磨了很久把agent管理拆成了四个核心问题。这四个问题后来成了我做所有设计的出发点。身份问题每个agent是谁负责什么角色能调用哪些工具用的是哪个prompt版本。没有身份边界agent之间就会像那次事故一样互相串味。状态问题agent当前处于什么生命周期阶段是运行中、等待中还是失败会话状态和任务状态分别存在哪里。状态搞不清楚调度器就不知道该把新任务派给谁。记忆问题agent能记住什么记忆的作用域是什么可不可以跨会话、跨agent共享。记忆管不好轻则回答跑偏重则把别人的隐私数据翻出来。权限问题agent能碰哪些数据、哪些工具、哪些网络资源访问边界在哪。权限不管等于让一个实习生拿管理员账号在生产环境随便操作。这四个问题涵盖了一个agent从出生到退役的全过程。只要有一个没管好多agent协作就一定出乱子。这套框架也成了我后面所有工作的基础。1.3 复杂度不随agent数量线性增长而是爆炸式增长还有一个直觉上的误区两个agent协作和六个agent协作看起来只是数量乘了三倍实际上复杂度远不止三倍。两个agent之间的通信链路只有一条六个agent两两之间的通信链路是十五条如果再加上工具调用、共享文件、外部API复杂度直接呈指数上升。这也是为什么管理比开发更容易成为瓶颈。后来我甚至觉得一个团队的agent管理能力上限决定了这个团队能把多少agent真正投放到生产环境里。2. 我给agent建的第一份花名册注册表与生命周期搞清楚了要管什么第二步就是动手落地。我做的第一件事不是写调度器而是先建了一张agent注册表。它很像公司的员工花名册——每个agent入职前先登记离职后销号所有关键信息结构化存档。2.1 注册表agent的唯一身份档案我的注册表很简单用JSON文件就够。每个agent都有一个全局唯一的agent_id然后关联角色、底层模型、prompt版本、工具列表和记忆命名空间。这是我最开始定义的一个示例{ agent_id: agent-reporter-001, role: reporter, display_name: 报告生成员, model: gpt-4o, prompt_version: 2025-11-01, tools: [query_db, write_report], memory_namespace: mem://reporter/001, status: active }之所以要把prompt版本单拎出来是因为我在这里吃过亏。prompt改一版线上agent的行为就可能变一个样子没有版本记录的话你根本不知道这次结果为什么和上周不一样。把prompt版本写进注册表之后每个agent的行为画像就有了可回溯的依据。后来我又加上了owner字段标注这个agent由团队里谁负责维护出了事直接找对应的人。2.2 生命周期状态机created, running, paused, terminated, failed注册表管身份状态机管生死。我定义了五个状态后来证明这五个状态基本够用状态含义进入条件created已注册未运行注册表写入成功running正在执行任务收到任务请求paused暂停保留上下文手动暂停或等待外部输入terminated正常结束上下文归档任务完成failed异常退出内部错误、超时、权限拒绝一开始我的状态机只有运行和结束两个状态后来发现根本不够。比如一个agent要等待外部人工确认这段时间它既不是运行中也不是结束如果没有paused状态调度器就会认为它死了把任务重复派发给别人造成重复处理。加了paused之后调度逻辑才清晰起来。2.3 配置与状态分离千万别把状态写进配置这里要特别强调一个设计原则配置是声明式的状态是运行时的两者必须分离。我见过有人把会话状态直接塞进agent的配置文件里跑完一次任务配置文件就变了下次启动直接读到脏数据。正确做法是配置层保持稳定只记录身份、模型、工具、prompt这种静态信息状态单独存到会话存储里每次任务结束归档新任务重新初始化。有些新手会觉得多存一份很浪费但等你排过几次诡异bug之后就会明白这份分离能救命的。2.4 启动前的体检在注册表和状态机基础上我给每个agent在启动前加了一道体检流程检查模型连接是否正常、工具是否可用、临时目录是否可写、记忆库是否可以连接。这套检查看起来繁琐但能避免大量跑一半才发现环境没了的尴尬。有一次某个数据库地址悄悄变了如果没有启动前检查六个agent会集体挂在第一步。有了体检调度器能第一时间把失败的agent标记为failed然后拉起备用方案。3. 框架选型框架管执行我管养成做完注册表我开始对比市面上怎么做agent搭建。那段时间我先后体验了几个主流方案包括直接用模型API裸写、微软的Agent Framework、Hermes Agent的本地部署也接触了Codex Agent的相关思路。最终结论可能会让一些人意外我没有选一个全套框架而是用一个轻量管理层把底层框架包起来。3.1 我踩过的选型弯路先说结论框架解决的是agent怎么跑管理解决的是agent怎么养两者不是一回事。微软Agent Framework我上手体验过它把编排、工具调用、状态管理做得比较成体系适合企业级大规模部署但心智负担不低。尤其当你只想管理两三个agent的时候框架本身的配置就成了主要工作量。Hermes Agent我很喜欢它的命令行体验和Agentic系统本地部署可控性强但它的关注点更多在agent本身怎么设计对多agent统一管理并不算核心强项。至于直接用模型API裸写自由度最高但一切都要自己造轮子包括轮子的刹车。3.2 我的最终方案核心管理逻辑不绑定框架我最后的选择是底层模型调用灵活切换OpenAI、Claude、Llama、Qwen都可以中间层自己写一个不到一千行的管理模块负责注册、调度、记忆、审计。如果某个环节需要成熟的Agentic Loop可以直接外包给现成框架但管理模块始终握在自己手里。这个决定是出于一个很实际的考虑agent领域迭代太快了。今天这个框架火明天那个框架跑出来如果我把管理逻辑也写进某个具体框架里后面每次换框架都是一场灾难。不如让管理接口保持轻量和稳定框架只是底层执行者。现在回头看这个决定帮我在后续几次框架切换中省下了大量返工时间。3.3 什么时候才建议上重框架当然我不是说框架没有用。如果你的团队要管理几十上百个agent而且需要完善的权限体系、观测面板、审计合规那成熟框架是值得的。但对于初次尝试做agent管理的团队我的建议是先用最小实现跑通注册、调度、审计三个基础能力摸清楚自己的痛点再去决定要不要上重框架。不然容易陷入先学框架还没学会就开始管理agent的怪圈学完发现框架解决不了你真正的问题。4. harness和agent到底有什么区别一次执行态与长期身份在搜索资料的时候我发现harness和agent区别是很多人困惑的点我自己一开始也没绕明白。这里直接分享我后来的理解。4.1 harness是工位agent是员工如果用一句话概括agent是一个长期存在的身份角色harness是某一次任务执行时的运行环境。agent决定我是谁、我记得什么、我擅长什么harness决定这次干活的时候我能碰哪些工具、临时目录在哪、环境变量是什么、超时多久。这个类比帮我解决了之前很多混乱。以前我把工具绑定在agent上导致同一agent的两次不同任务共享同一批工具配置状态互相污染。后来把所有运行期配置全部挪到harness层agent只声明我需要数据库查询能力harness在每次执行时才具体分配对应的数据库连接和访问凭证。这样一来agent的身份定义变得非常稳定变的只有每次执行的环境。4.2 一个任务一个harness实例我现在的做法是每次任务创建一个全新的harness实例包括独立的工作目录、独立的工具上下文、独立的临时凭证。任务结束后harness销毁现场归档。这样同一个agent跑不同任务时不会把上次任务的环境残留带到下一次。你可以理解成每个员工每天上班都换一个干净的工位而不是在同一个污染过的工位上战战兢兢地干活。{ task_id: task-2025-11-03-001, agent_id: agent-reporter-001, harness: { workdir: /tmp/harness/task-2025-11-03-001, env: { EXCLUDE_SENSITIVE: 1 }, tools: [query_db], max_steps: 20, timeout_seconds: 300 } }注意这里的max_steps和timeout_seconds这就是我前面提到循环调用十七次之后加的保护。没有这两个限制一个失控的agent可以把你的token和计算资源全部烧完。在我看来这两个参数是agent管理系统里性价比最高的投入几行配置就能挡住最恶劣的事故。4.3 工具白名单与控制在harness层面做工具白名单是agent管理里能获得最大安全感的一件事。默认拒绝所有工具只有显式声明的才允许调用。每个工具调用都记录审计日志包括参数、返回状态、耗时。这样即使某个agent真的出问题了你也能根据日志倒推它在哪一步走偏了。比如有一次我们发现某个agent突然开始大量读取无关数据表翻日志才发现是prompt被改坏了工具白名单加审计日志让我们在十分钟内定位到了根因。5. 记忆管理session记忆、任务记忆、长期记忆三层拆开摸清harness和agent的区别之后我开始处理记忆问题。agent的记忆如果管不好之前那个两个agent共享上下文导致互相污染的情况会反复出现而且比单agent场景严重得多。5.1 三层记忆模型我采用三层记忆按生命周期和作用域严格区分工作记忆当前任务内的短期上下文任务结束立即归档并清空。会话记忆同一个智能体与用户之间的多轮对话历史存到session存储里。长期记忆知识库、偏好、历史结论需要经过提炼后写入向量库或结构化存储。这三层之间不是共享的而是逐层提炼的关系。任务结束工作记忆中的关键结论可以提炼为长期记忆但原始上下文就不留着了。一开始我试图把所有记忆都塞进同一个存储里后来查询速度和准确性都出了问题才下决心分层。5.2 记忆命名空间与检索隔离很多初次接触agent记忆管理的人都会踩同一个坑所有agent共享一个向量库结果A读到了B的私有记忆。我也踩过。后来的修复方案是给每类记忆定义明确的命名空间不同agent之间的记忆物理隔离。mem://reporter/001/session/{session_id} mem://reporter/001/longterm mem://analyst/001/session/{session_id}检索时强制加入namespace过滤同时每条记忆写入时都带来源标注agent_id、时间戳、任务id。这样即使出现串记忆问题也能快速定位是哪条记录导致的而不是对着满屏向量一头雾水。5.3 记忆过期与归档记忆不能只进不出。我给不同层级的记忆设了不同保留策略工作记忆几乎立即释放会话记忆根据业务要求保存一定周期长期记忆定期做去重和摘要压缩。项目里有个agent一度因为记忆库无限膨胀每次检索都变慢最后清理掉大量过期chunk之后速度才恢复。这就是典型的没有管理带来的成本问题。后来我加了一个定期任务每周统计一次记忆库的增长量和命中率把长期没有命中的记忆自动降级归档既保留知识又控制成本。5.4 一次串记忆问题的排查示例我举个真实例子analyst agent生成的报告里突然混进了reporter agent的报告风格连标题格式都变成了另一个人的习惯。当时我们排查了很久最后发现两个agent的长期记忆向量库没有做namespace隔离analyst检索时命中了reporter的高权重chunk。修复只需要在检索query里强制加filter但如果没有来源标注这个bug可能会潜伏很久。这件事给我的教训是记忆管理不是等到出问题再处理而是在一开始设计存储结构时就把隔离性考虑进去。6. 多agent首次协作跑通编排与死锁处理管理机制搭好之后我开始真正尝试多agent协作。这里也踩了不少坑其中最深的两个坑是角色拆得太碎和死锁。6.1 角色拆分的反面教材第一次我学微服务的思路把流程拆成了七个角色需求分析、数据采集、数据清洗、数据分析、画图、校对、发布。结果任务链条太长每个agent都缺乏全局上下文而且大量时间花在agent之间传递阶段结果上相当于把一次本来可以串行完成的任务硬生生搞成了七次对话。后来我砍到三个角色才跑通coordinator负责接收需求、拆解任务、分派给worker、汇总结果。worker负责干活一个worker对应一类具体能力。reviewer负责把关对worker的输出做质量检查。分工的价值只有在复杂任务上才体现得出来。新手不要一上来就整微服务式的编排够用就好。我甚至觉得三个角色是绝大多数场景下的最优解一个统筹、一个执行、一个质检再多就是给自己添乱。6.2 统一的消息协议多agent之间要通信必须有一套统一协议不能靠自然语言互相发消息。我的消息结构很简单{ request_id: req-001, type: task/request, from_agent: coordinator, to_agent: worker-data, payload: {}, timestamp: 2025-11-03T10:00:00Z }每个消息都带request_id这样整条任务链可以追溯。type用来区分是任务请求、状态回报还是错误通知。没有这套协议之前agent之间靠自然语言互相发消息解析成功率低得令人抓狂经常出现对方发来一段话这边理解成另一个意思的尴尬场面。6.3 死锁与循环调用的处理两种典型故障我都在初试阶段遇到过。第一种是死锁coordinator等待worker返回结果worker又在等待coordinator进一步指令两边互等整个任务卡死。解决办法是在harness层设置超时任何一次等待超过阈值就主动降级比如由coordinator直接终止当前分支任务并给出中间结论。第二种是循环调用agent A调B、B又调A形成调用环。解决办法是设置最大调用深度和总步数限制一旦超过就直接中断。我在最开始翻车时遇到的循环调用十七次就是缺少这两个限制。现在任何一个harness配置里max_steps和timeout_seconds都是必填项写不上去就直接拒绝启动。6.4 一次真实的协作流程实录最后我说一个跑通的场景coordinator收到生成上周销售周报的需求后拆成三个子任务取数、分析、绘图。它通过协议消息把取数任务发给worker-dataworker执行完把结果以结构化JSON返回analysis worker拿到JSON后生成结论画图agent拿到数据源和结论生成图表最后coordinator汇总文本与图表交给reviewer检查reviewer通过后输出最终报告。全程有消息记录任何一步出错都能定位到具体agent和请求id。整个过程说实话并不快但稳定性和可解释性比我之前那六个agent乱跑要好太多。7. 安全与测试agent管理的两条底线如果一个agent管理系统只有功能没有安全和测试那它只适合做demo。我在初试阶段就把安全审计和可测试性提到了几乎最高的优先级因为agent一旦能调工具、能碰数据风险和收益就同时被放大了。7.1 默认拒绝的权限模型给agent分配权限时我采用默认拒绝而不是默认允许。新建的agent没有任何工具权限管理员必须显式声明它可以使用哪些工具、访问哪些数据。比如reporter需要读数据库但不需要删表那我给它database:read绝不顺手给database:write。这个原则听起来简单但很多团队嫌麻烦直接给agent配了管理员权限等出了事故才开始后悔。权限最小化不是限制效率而是给失控加一道保险。7.2 全链路审计日志每个关键动作都要留痕。我的审计表字段包括agent_id、动作类型、目标资源、请求参数、返回状态、耗时、触发任务id。刚开始觉得有点繁琐但后来一次线上agent数据异常时全靠审计日志从几千条记录里倒推出问题步骤。没有这一步你可能只能靠猜。审计日志还有一个隐藏价值它能帮你测算每个agent的真实调用频率和token消耗对成本归因特别有用。7.3 剧本化测试与回归集测试方面我给agent准备了两类用例。一类是确定性用例固定输入期待固定输出。比如给reporter一段标准数据要求它必须返回符合字段规范的结构化结果。这类用例适合做回归测试防止prompt迭代后旧能力失效。另一类是剧本测试模拟一段业务剧情看agent在较长交互链里是否按预期走。比如用户在对话里先提出数据需求再追加约束条件最后要求调整格式剧本测试能暴露agent在上下文太长时的行为漂移。我现在每次修改prompt都要先跑一遍这两类用例全部通过才允许上生产。7.4 初试途中的典型事故临时目录污染我犯过一个很典型的错六个agent共享同一个临时目录导致文件互相覆盖。现在的规定是每次任务创建独立workdir任务结束自动清理任何agent都只能写自己的目录外界的文件一律通过harness注入。这个改动虽然小但直接减少了至少一半的偶发故障。很多所谓的随机性问题最后查下来都是资源隔离没做好。8. 现在回头看我的agent管理起步清单如果你也想从零开始尝试agent管理我不想给你列一个三十条的复杂手册只想分享一下最后沉淀下来的核心清单。这些东西不依赖任何特定框架任何技术栈都能实现。8.1 起步三件套不管底层用什么模型、什么框架先把这三样建起来注册表所有agent的身份、角色、prompt版本、工具列表集中登记。状态机每个agent都要有清晰的生命周期状态不能只有运行和结束。审计日志所有关键动作记录在案方便回溯。这三样东西是agent管理的骨架成本很低收益却巨大。我甚至觉得哪怕你只想管理一个agent也应该把这三样建起来因为唯一恰恰是最容易被忽略管理的场景。8.2 推荐的起步顺序不要一上来就上多agent。我的建议是先单agent跑稳再双agent协作再逐步增加。先串行流水线再考虑并行。先共享一个记忆库再考虑隔离。每一步都确认稳定了再往下一步走。我自己的教训是步子迈得太大第一个项目就六agent并行差点把业务数据搞成一锅粥。慢不是问题乱了才是问题。8.3 两句话总结我这次初试的体会第一句agent管理本质上不是单纯的技术问题而是组织问题。一个agent像一个员工要有岗位说明书注册表、有上下班打卡生命周期、有工作留痕审计还要有权限边界默认拒绝和记忆档案命名空间隔离。你越早用管人的思路去管agent越能少踩坑。第二句框架会变、模型会变但身份明确、状态可控、记忆隔离、权限最小这十六个字不会变。尽早把管理思维建立起来比你用哪个热门框架重要得多。如果非要给后来者一个建议那就是从一次会失败的实验开始。让几个agent没有管理地跑一次亲眼看它们互相覆盖、循环、串记忆你才会真正理解为什么要做agent管理。纸上谈兵的管理方案我一晚上能写十个但只有被真实故障打过脸那些约束条件才会变成你自己的本能。