Agency Agents实战：多智能体协作、角色编排与自动化工作流

"agency-agents"，单看这个项目名，就能品出一点产品层面的想法。agency是代理机构，agents是智能体，连在一起说的是——把一群AI智能体组织起来，让它们像一家代理公司那样配合着运作。这个项目本质上是一个面向多智能体编排与自动化协作的开源框架类项目，核心解决的，不是单个Agent怎么变强，而是多个Agent之间怎么分工、怎么通信、怎么把一件复杂的事情拆开干完、再合起来交付。

对正在从"给模型写提示词"转向"给一群模型设计工作流"的开发者来说，这个项目把多智能体协作的骨架直接摆了出来。它适合谁？适合那些已经开始用单Agent做自动化、但明显感觉到单点瓶颈的人；也适合技术团队里负责评估Agent编排方案的同学。下面的内容，我会从项目定位、环境搭建、一个完整的多角色编排案例、问题排查，再到扩展方向，把实践记录和踩坑笔记完整过一遍，每一步尽量写到可以直接照着复现的程度。

1. 项目定位与核心设计思路

1.1 为什么要把多智能体设计成"代理机构"模式

单Agent的局限其实很明显。你给一个模型配上工具、加上记忆、写上一大段系统提示词，它能完成一些独立任务，但随着任务复杂度上来——比如"整理资料、结合多个来源形成判断、再生成一份结构化报告"——单个Agent很容易出现上下文混乱、执行到一半忘掉前置条件、或者只顾着生成内容而忘了校验事实。

"agency-agents"这套框架的设计思路，本质上是把多智能体的协作关系，投影成了现实世界中代理机构的组织结构。机构里会有负责人、有研究员、有文案、有审核岗，每个岗位只对自己的环节负责，任务通过一套明确的交接机制流转。对应到系统里，就是一个主控Agent负责任务拆解和派发，若干执行Agent负责具体环节，最后还有一个汇总或者质检Agent把中间产物收敛成最终结果。

这种组织化设计的价值在于三点。第一，职责隔离。每个Agent的提示词和工具都限定在自己职责范围内，不容易互相干扰，也不会出现一个Agent又当裁判又当球员的混乱局面。第二，上下文可控。每个节点只需要关注自己的输入和输出，避免把所有消息全部塞进一个超长的上下文，这在模型上下文窗口有上限的现实条件下尤其重要。第三，可观测。你可以清楚地看到任务流转到哪个环节、谁在处理、处理结果是什么，出了问题能精准定位到节点。

1.2 框架的四个关键抽象：角色、任务、工具与消息

我在实际用下来，发现这套框架的核心抽象并不复杂，主要就是四个东西。

角色（Agent）是最基本的执行单元，它跟一个普通的大模型会话的区别是，角色会被赋予职责描述、专属工具、以及独立的上下文空间。任务（Task）是流程里的基本工作单位，每一个Task都包含目标、输入数据、期望输出格式。工具（Tool）是Agent跟外部世界交互的入口，可以是搜索接口、数据库查询、文件读写，本质上就是一个可被模型调用的函数。消息（Message）则负责角色之间的通信，流程能够跑通，靠的就是消息在角色之间按照编排逻辑流动。

这个设计跟我之前用过的"一条链表把多个Agent串起来"的做法最大的不同，在于它引入了一个流程协调层。任务派发给谁、完成后消息往哪儿传、哪个角色需要等待哪个角色的结果，这些逻辑被单独抽出来，而不是散落在各个Agent的提示词里。这样做的好处非常实际——改流程的时候，你不需要动角色本身的提示词和工具配置，只需要调整编排定义，就可以改变整个协作逻辑。

2. 环境准备与最简示例

2.1 运行环境与前置依赖

我在一台配置不算高的机器上跑通了这套框架，系统是常见的Linux环境，Python版本用的3.11。之前用3.10跑过，也没有问题，所以环境的话只要不低于3.10基本都能正常使用。安装过程比较顺利，核心依赖直接通过包管理器安装，官方文档里附了完整的依赖清单。如果你在依赖下载阶段遇到速度慢或者超时的情况，建议直接配置镜像源来加速，这一步属于常规操作，配好之后后续会顺畅很多。

安装完成之后记得验证一下是否可以正常导入主模块，如果导入成功，说明基础依赖没有问题。这里有一个比较隐蔽的坑：机器上可能存在多个Python版本，依赖装到了别的环境里，然后导入的时候一直报错还找不到原因。所以我的习惯是新建一个独立的虚拟环境来安装，避免跟系统Python产生冲突。这个习惯帮我省了非常多排查时间。

2.2 配置模型接入

多智能体框架的模型接入层做得比较灵活，可以通过统一的配置项加载。它的设计是套了一个模型调用层，底层支持多种模型提供方，这样你在角色定义里不需要关心模型怎么调用，直接把模型实例传给角色配置就行。不同模型提供方的API访问策略和网络条件各不相同，建议你根据自己实际的部署环境做好适配，让模型调用这一层稳定可用就行。框架关注的更多是编排逻辑本身，底下的模型连接属于基建。

这里我踩过一个小坑：本地环境中模型访问需要配置访问密钥，但框架在加载配置时对密钥格式有一定要求，如果密钥配置不对，角色实例化的时候不会立刻报错，要到第一次实际调用模型时才报认证错误。这个排查起来要多花一些时间。建议的做法是，先写一个最小的模型调用测试脚本，确认模型能正常拿到回复之后，再去启动多智能体流程，这样能把问题范围缩小，尽快定位到底哪一层出了问题。

2.3 第一个双角色协作Demo

纸上谈兵没有意义，我直接写了一个双角色协作的示例来验证这套流程。这个例子的核心逻辑是，一个"规划者"角色负责理解用户需求并生成执行计划，一个"执行者"角色负责拿到计划之后具体执行，然后返回结果。

先定义规划者角色，给它配置好模型实例、角色名称和角色说明。角色说明里直接写清楚职责边界，比如"你负责分析用户请求并拆解出可执行的步骤清单，不参与具体内容的生成"。然后定义执行者角色，职责说明反过来，写的是"你负责根据执行计划完成任务并输出结果"。

下一步最关键：设置流程协调逻辑。我参考框架的编排方式，定义了消息传递规则，用户初始请求先传给规划者，规划者输出的计划通过消息封装之后传给执行者，执行者的输出作为流程的最终返回结果。

这个示例跑通之后，我有点意外，因为它比我想象中要"安静"得多。整个流程没有复杂的配置界面，没有黑盒调度，代码量也不大，核心就是角色定义加消息路由。这让我对这套框架的第一印象是：它更像是一个认真实现了多智能体协作模型的轻量框架，而不是一个为了演示而做的玩具。

不过这里我也得说一句实在话——双角色Demo跑通，离真正能用还有很长一段路。流程编排中最麻烦的部分（比如分支判断、异常回滚、结果校验）在这个Demo里都还没有涉及。它更大的意义是帮我验证了基础的通信通道是通的，后面再往上加复杂度，心里就有底了。

3. 多角色任务编排的完整实操

3.1 场景设计：一份行业调研报告的自动生产

为了把"agency-agents"的能力完整展示出来，我设计了一个稍微复杂一些的场景：让多个角色配合完成一份"智能客服行业应用调研报告"的自动生产。

任务拆解是这样的：一个"主管"角色负责总体拆分，它把任务切分成"市场现状调研"“典型应用场景收集”"结论与趋势分析"三个子任务，并且为每个子任务指定对应的执行角色。一个"研究员A"负责市场现状调研，它的工具是搜索引擎访问和网页内容抓取。一个"研究员B"负责应用场景收集，侧重收集具体行业案例。一个"撰写者"角色拿到两个研究员的调研结果之后，负责把原始材料整合成一份结构完整的报告，同时进行去重、结构化、统一格式。

这个场景的难度在于，它不是简单的串联流水线，而是一个"先并行后汇总"的结构。主管角色拆完任务之后，研究员A和研究员B是并行工作的，两边的结果都出来后，撰写者才开始汇总。这对框架的任务调度能力是一个实际的考验，也是我觉得最能体现这套框架设计意图的一个案例。

3.2 角色定义与提示词设计

角色定义的核心是提示词设计。这套框架里每个角色的提示词直接影响生成质量，写得太模糊会导致角色越权，写得太死板会限制执行。我给主管角色的提示词里刻意强调了"你只负责拆解任务、分配任务和理解目标，不执行任何调研动作"，因为我的经验是，如果不加这句约束，很多模型角色会忍不住自己把活干了，完全打乱编排逻辑。

研究员角色我配置了搜索工具，用了一个简单的正则表达式来提取搜索结果，这个正则虽然简单，但比较实用，可以直接从搜索引擎的返回页面里抓取结果标题和链接。这里其实是一个典型的工程取舍：不做复杂的页面解析，只提取框架需要的字段，减少依赖、加快响应。对调研型角色来说，工具能返回多少条有效结果，通常比结果页面的完整性更重要。

撰写者的提示词里我放了一句话："请基于提供的研究材料进行整合，不要自行编造不存在的案例和数字。"这句话在我所有的内容生成类角色里几乎是必备的。调研类工具返回的资料多多少少会有噪声，如果没有这句约束，模型在整合时很容易脑补出一些"看起来合理"但实际并不存在的内容，对报告类任务的危害特别大。字数限制我也会写清楚，比如"输出控制在800字以内，按章节结构化输出"，不然模型有时候会过度发挥。

3.3 任务分发与结果汇总的代码实现

整个编排的代码实现大概可以分成三个环节。

第一步是创建角色实例。创建研究员A、研究员B、撰写者三个角色，每个角色都配置好模型、工具和提示词。代码结构上我会把角色定义单独放到一个配置模块里，避免后面角色多了以后，流程定义和角色定义混在一起，维护起来很痛苦。

第二步是编排流程逻辑。这次我用了框架中的任务分发机制，给每个子任务指定一个执行角色。分发之后最关键的是等待两个研究员的结果，只有两边都有输出，才能进入撰写环节。这一步我在代码里对应的是一个简单的监听逻辑，两个研究员的输出都到位之后，触发下一个环节。

第三步是汇总。汇总不是把两个研究员的输出简单地拼在一起，而是把原始结果按统一格式整理成一个调研材料汇总，再传给撰写者。这一步我特别强调一下：中间有一个"转化"步骤，尽量让汇总材料的结构跟撰写者预期的一致，不然撰写者面对两份格式完全不同的输入，很容易生成混乱的内容。

运行的时候我观察到，整个流程是自动推进的，框架会在后台按编排逻辑分发任务、等待结果、继续下一步。从输出日志里可以看到任务在角色之间的流转轨迹。整个流程跑下来大概花了几分钟，主要由模型响应时间决定。让我比较满意的点是，即使某个研究员在搜索过程中遇到个别页面抓取失败，框架也没有让整个流程失败，而是继续往下走，这说明它有一定的容错能力。

3.4 关键参数与运行效果解读

第一个值得关注的参数是"最大迭代轮次"。多智能体系统里经常出现的情况是，某个角色在跟工具反复交互时陷入循环，比如发现自己对搜索结果不满意，就反复重新搜索。设置最大迭代轮次可以有效防止这类无限循环消耗时间和算力。我建议初始值设在3到5之间，后续根据任务复杂度再调。

第二个参数是消息传递超时机制。在实际跑的时候，我遇到过角色A在等待角色B的返回结果时，因为模型响应时间过长导致整个流程看起来卡死的情况。框架在等待超时这个维度上支持自定义配置，我会设置一个合理的等待上限，并确认日志里能看到任务处于等待状态，这样才能区分"在正常处理中"和"真的卡死了"。

从运行效果上看，生成出来的报告整体可用性还不错，但我必须提醒的是，这份报告充当的是"初稿"角色，肯定不能直接对外交付。我在读报告的时候发现，市场现状那部分的数字明显偏老，应用场景部分也有一些内容重复。这说明即使流程本身跑通了，未经过人工核验的调研报告，在时效性和准确性上依然存在风险。

4. 常见问题与排查经验

4.1 任务卡死与死循环

第一个高频问题是任务卡死。卡死一般有两种情况：一种是真的死锁，即两个角色互相等待对方的输出，谁也不让谁；另一种是某个角色在工具调用环节反复失败，比如搜索接口返回了空结果，角色不甘心，一遍遍重试。排查方式其实不复杂：看日志。框架的日志里会标记当前活跃的任务和角色，如果某一个角色长时间停留在同一步没有变化，那大概率就是这两个问题之一。

我的处理思路是：对于死锁，检查流程编排里是否存在循环依赖，把等待链调整成单向的；对于反复工具调用失败，最有效的办法是限制最大迭代轮次，并且在角色提示词里明确写"如果工具调用失败，请基于已有信息继续，不要重复调用"。这个简单的手段，能有效避免角色在失败中无限打转。

4.2 上下文窗口爆掉

第二个常见问题是上下文窗口爆掉。多智能体系统中，每个角色有自己的上下文，但如果你在设计时让角色承担了太多职责，或者消息传递时把原始材料一股脑全部塞进去，很容易触达模型API的上下文上限。我是一个对上下文长度比较敏感的人，之前用单Agent做长文本处理时就经常遇到截断问题，所以在这套框架里我习惯性地保持了"小步快跑"的思路。

具体做法是，每个角色只接收跟当前任务直接相关的输入，上游角色输出的原始材料先做一次精简，再传给下游。比如在调研报告的例子里，研究员返回的原始搜索结果可能有很多噪声，我会先做一个格式整理，提取出核心信息，再传给撰写者。这一步不能省，因为它既是上下文控制的关键，也是输出质量的关键。

4.3 工具调用失败但框架不报错

第三个要说的坑比较隐蔽——工具调用失败时，框架不一定报错。我遇到过的情况是，搜索引擎返回结果为空时，模型会一本正经地用"没有找到相关结果"作为研究结果向下传递，整个流程照常往下走，日志也全部正常。如果不仔细看结果内容，你根本不知道某个环节的数据是空的。

针对这种情况，我总结了一套"结果校验"的做法：不要相信角色说自己完成了，要检查输出里是否有实际内容。具体操作上，我在关键节点都会加一个简单的规则校验，比如检查输出文本长度、检查是否包含关键字段、检查是否包含空结果标记。命中校验条件的输出不能直接传给下游角色，而是要么重试，要么标记为"该模块数据缺失"并传给下游。这套机制在真实的业务场景里非常实用，算是我在这个项目里收获最大的一条经验。

4.4 结果"看起来不错"但实际不可用

第四个问题最容易让新手放松警惕，就是流程跑通了，结果看起来满满当当，但其实不能用。我在第一次跑调研报告流程的时候，出来的报告结构完整、段落丰富，读起来像模像样。但当我认真核对里面引用的数字和案例时，发现有几个细节经不起推敲。这就是多智能体系统特有的"流畅但不准确"陷阱。

对这个问题，我的建议是：一方面在角色提示词里强化"禁止编造"的约束，另一方面在工程上加入人工核验节点。尤其在对外交付类的任务里，一定要安排一个独立于生成流程的校验步骤。框架本身可以通过设计"审核角色"来做这件事，让一个不参与生成的角色去校验生成结果，效果比同一个角色自查靠谱得多。这个跟现实中"写代码的人不做测试"是同一个道理。

我把这四类问题整理成一个速查表，方便后面查：

5. 从Demo到可用系统的扩展方向

5.1 把Agent封装成可复用的服务

Demo跑通只是起点，要把这套多智能体编排真正落地到业务里，有几个方向值得认真做。第一个方向是把单个Agent封装成可复用的服务。这套框架现在的问题之一是，角色跟流程的耦合比较多，一个角色最好通过一门"统一接口"向外暴露能力。我尝试过把调研角色包装成一个独立的服务模块，外部只需要传入调研主题，就能返回结构化结果，其他细节完全封装在内部。

这样做的好处是，上层业务不用关心这个调研是怎么实现的，是单Agent做的还是多Agent协作做的，只要接口稳定，底层随时可以替换。这在实际工程项目里是特别重要的一个原则。我当时花时间重构接口之后，明显感觉后面加新角色轻松了很多，复用度高了很多。

5.2 事件驱动与异步任务队列

第二个方向是引入事件驱动与异步任务队列。Demo版本的执行是同步的，子任务A完成之后才能启动子任务B。而这个项目的编排特性天然适合做异步化——尤其是"先并行后汇总"这类结构，如果每个子任务都能独立地异步执行，整体效率会高很多。

我尝试过把任务执行器接到消息队列上，让每个任务成为一条独立的消息，消费者在各自的节点上执行任务。这样做的收益有两个：建模能力更强，复杂流程可以直接用消息状态机来表达；失败重试也更自然，消息失败后可以重新入队。这个方向虽然要写的代码比直接用框架多不少，但对于要面对真实并发量的场景来说，值得投入。

5.3 状态持久化与人工审核节点

第三个方向是状态持久化和人工审核节点。多智能体流程里跑出问题的成本，往往要到流程结束、结果不可用时才显现出来。最好的做法是在流程里设置多个"检查点"，每个检查点都把中间产物持久化到存储里，这样即使后续步骤失败，也能从最近一个正常的检查点恢复，而不是整个流程重跑。

同时，在所有外发型任务（比如对外发布内容、生成合同文本、给出投资建议）的下游，都应该加入一个人工审核节点。自动化生成的责任边界必须划清楚：机器负责初稿和批量生产，人负责方向和底线。这也是我在这套框架的实践当中，总结出的最重要的一个边界原则——多智能体系统可以替代很多"体力活"，但还不能完全替代"判断力活"。

我在实际使用这套框架的过程中，有过一个比较深的触动。最开始我只是想跑通一个多Agent的例子，结果后来发现，真正麻烦的从来不是让单个Agent变聪明，而是怎么让一群Agent在协作时不掉链子。这个项目给我的帮助在于，它把"多智能体协作"这个看起来很玄的东西，拆成了角色、任务、工具、消息这些可以落地设计的东西。如果你也在做类似的Agent编排项目，我的建议是：不要一上来就追求大而全的框架和酷炫的效果，先用手里的工具跑通一个最简协作流程，然后把出错的可能性一个一个堵住，最后再往里面加复杂度。就像打地基一样，基础稳了，后面盖多高都不慌。希望对你有参考价值。