多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

注册表管身份，状态机管"生死"。我定义了五个状态，后来证明这五个状态基本够用：

一开始我的状态机只有"运行"和"结束"两个状态，后来发现根本不够。比如一个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-data，worker执行完把结果以结构化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 起步三件套

不管底层用什么模型、什么框架，先把这三样建起来：

1. 注册表：所有agent的身份、角色、prompt版本、工具列表集中登记。
2. 状态机：每个agent都要有清晰的生命周期状态，不能只有"运行"和"结束"。
3. 审计日志：所有关键动作记录在案，方便回溯。

这三样东西是agent管理的骨架，成本很低，收益却巨大。我甚至觉得，哪怕你只想管理一个agent，也应该把这三样建起来，因为"唯一"恰恰是最容易被忽略管理的场景。

8.2 推荐的起步顺序

不要一上来就上多agent。我的建议是先单agent跑稳，再双agent协作，再逐步增加。先串行流水线，再考虑并行。先共享一个记忆库，再考虑隔离。每一步都确认稳定了，再往下一步走。我自己的教训是步子迈得太大，第一个项目就六agent并行，差点把业务数据搞成一锅粥。慢不是问题，乱了才是问题。

8.3 两句话总结我这次初试的体会

第一句：agent管理本质上不是单纯的技术问题，而是组织问题。一个agent像一个员工，要有岗位说明书（注册表）、有上下班打卡（生命周期）、有工作留痕（审计），还要有权限边界（默认拒绝）和记忆档案（命名空间隔离）。你越早用管人的思路去管agent，越能少踩坑。

第二句：框架会变、模型会变，但"身份明确、状态可控、记忆隔离、权限最小"这十六个字不会变。尽早把管理思维建立起来，比你用哪个热门框架重要得多。

如果非要给后来者一个建议，那就是从一次会失败的实验开始。让几个agent没有管理地跑一次，亲眼看它们互相覆盖、循环、串记忆，你才会真正理解为什么要做agent管理。纸上谈兵的管理方案我一晚上能写十个，但只有被真实故障打过脸，那些约束条件才会变成你自己的本能。