多Agent协作框架agency-agents：角色定义与任务编排实战指南

最近这个项目名在开发者圈子里出现频率挺高——agencey-agents。我第一次看到这个关键词的时候，第一反应是：这不就是把现实中广告公司、设计工作室那套“甲方对接、创意策划、执行交付”的流程，全部交给AI智能体来跑一遍吗？后来实际动手梳理了一遍，发现它确实不只是个概念，而是一种把大模型能力变成“可分工、可管理、可审计”的协作框架。说白了，就是给你一支由多个AI智能体组成的“虚拟团队”，每个智能体扮演一个岗位角色，互相配合完成一个完整的项目交付。

这个思路解决了一个很现实的问题：单个AI对话窗口能力再强，也扛不住多步骤、多角色协作的复杂任务——比如你让一个Agent既做市场调研又写文案又出设计稿又做数据复盘，中间一定会出现上下文混乱、角色打架、输出质量崩盘的情况。而agency-agents要做的，就是把每个AI能力单元拆开、定岗、编排成一条流水线。它适合谁？适合正在做AI应用落地、智能体工作流设计、或者想把自己的业务流改造成AI协作模式的人来参考。

1. 内容整体设计与思路拆解

1.1 从“一个人用好AI”到“用AI管好AI”

我先说一个观察：很多人在用大模型的时候，习惯性地把它当作一个超级个体来用——一个对话框里塞进所有需求，希望它什么都能干。但真实业务场景里根本不是这么回事。你在一个项目里既需要做战略分析的“大脑”，需要做内容生产的“手”，还需要做质量把关的“眼睛”，这三个角色如果塞进同一个上下文里，互相干扰几乎是必然的。

agency-agents的核心设计思路，恰恰是把这三个能力拆开。它模仿的是现实中的机构运作逻辑：项目立项之后，由项目经理角色去拆分任务，由执行角色去产出内容，由质检角色去审核结果，最后再由一个调度中枢来汇总和交付。每个Agent只干一件事，只关注自己的那一段上下文，整个链条下来，错误率要低得多。

这个架构的好处在于：第一，职责边界清晰，每个Agent的提示词（System Prompt）可以做得非常专注，不需要在一段提示词里既教它写文案又教它做数据分析；第二，上下文窗口的压力骤减，单个Agent只需要装载与自己岗位相关的信息，比塞满全项目资料的巨型上下文稳定得多；第三，每个环节的可观测性极强，因为每个Agent的输入输出都是独立记录的，哪里出了问题，一眼就能定位到具体环节。

1.2 核心设计：角色、任务、工具三层分离

我实际拆解过这类项目后，发现它的设计逻辑可以归纳成三层：

• 角色层：定义每个智能体的身份、职责边界、输出规范。比如“调研专员”角色，它的System Prompt里会写明：你只负责收集和整理公开渠道的信息，不负责给出结论性建议，输出格式是结构化清单。
• 任务层：定义项目的拆解方式、流程顺序、节点间的衔接逻辑。比如一个“周报自动生成”项目，可以拆解成“本周数据汇总”任务、“亮点与问题分析”任务、“下周计划起草”任务，前一个任务的输出直接作为后一个任务的输入。
• 工具层：把外部API、数据库、脚本、网页阅读能力包装成Agent可调用的函数。比如调研专员可以调用一个“网页搜索工具”，质检专员可以调用一个“语法检查工具”，这些工具与角色绑定，避免无关调用。

这个设计的精妙之处在于，三个层是解耦的。你想增加一个角色，不需要改任务流程；你想调整流程顺序，也不需要动角色定义。对于从零搭建智能体工作流的朋友来说，这应该作为第一原则刻在脑子里：先把角色和任务的边界划清楚，再写代码。

1.3 为什么不做“一个超级Agent”？

有人会问：现在大模型上下文窗口已经做到百万级了，直接塞给它完整任务不行吗？为什么要搞多Agent协作这么复杂？

我用一个现实中的例子说明。假设你要做一个“行业竞品分析报告”，如果只用一个Agent来做，它在处理到第三十个竞品的资料时，大概率会忘记最开始定的分析维度，开始跑偏；或者它会为了迎合你之前的某句表述，强行往那个方向凑结论。这就是“全知型Agent”的典型问题——什么都沾一点，什么都不精。

而多Agent协作的方式是：研究型Agent专注收集竞品信息，输出标准化的竞品档案；分析型Agent基于档案做对比分析，产出洞察结论；写作型Agent只负责把结论改写成报告文案。每个环节的输入输出都是上一环节的产物，质量是可校验的。数据证明，这种方式在长链路任务上的稳定性和可用性都高于单Agent方案。

提示：不要为了“多个Agent”而“多个Agent”。如果你的任务在单轮对话中就能完成，叠加多Agent流程只会增加延迟和成本。多Agent的真正价值在“长流程+多角色判断”的场景里才释放得出来。

2. 核心细节解析与实操要点

2.1 角色定义：一份好角色卡的三个关键要素

角色卡（Agent Profile）是整个多智能体系统是否好用的地基。我见过很多半途而废的同类项目，病根基本都在这里：要么角色卡写得像一篇作文，什么信息都往里塞；要么写得过于笼统，Agent根本不知道自己的边界在哪里。

一份实用的角色卡，我认为必须包含三个要素：

• 角色任务描述（Mission）：用两三句话说清楚这个Agent在系统里要交付什么结果。注意是“结果”不是“过程”。比如质检Agent的任务描述是“确保所有出站内容的准确性、合规性、风格一致性”，不是“阅读文本并检查错误”。
• 输入输出格式（Input/Output Contract）：设置严格的输入格式要求，Agent才知道自己该消费什么、生产什么。很多系统崩溃在Agent之间“说话”不一致——上游输出一篇长文，下游解析不了。所以我会建议用JSON Schema或严格的Markdown模板来约束输出格式。
• 边界与禁区（Constraint）：明确告诉Agent什么不能做。比如执行Agent不能修改任务拆解顺序，质检Agent不能跳过审核直接放行。大模型在自由发挥这件事上极有天赋，不加边界，它就会替你“发明”流程。

下面是我在一次模拟项目中用过的角色卡示例，你可以照着改：

agent_profiles = { "planner": { "mission": "将用户需求拆解为可执行的任务清单，明确依赖关系和验收标准。", "inputs": ["user_request", "previous_output"], "output_format": "markdown checklist with task_id, description, depends_on", "constraints": [ "不得执行任何实际的数据采集或内容生成工作", "每个任务必须指定一个执行角色", "任务数控制在3-8个之间" ] }, "researcher": { "mission": "根据指定关键词检索公开资料，输出结构化信息卡片。", "inputs": ["task_description"], "output_format": "json array with source, summary, reliability", "constraints": [ "只汇总信息，不输出分析结论", "每条信息必须附来源地址", "拒绝回答超出资料范围的问题" ] }, "writer": { "mission": "基于分析结果撰写最终交付文案，语言简洁、结构清晰。", "inputs": ["analysis_result", "style_guide"], "output_format": "markdown article with h2/h3 headings", "constraints": [ "不得虚构数据或引用不存在的来源", "严格按照style_guide的语气和句式规范" ] } }

2.2 任务编排：用状态机思想控制流程走向

如果说角色卡解决的是“每个Agent是什么”的问题，那任务编排解决的就是“这些Agent怎么排兵布阵”的问题。我在实践中发现，最好的编排方式不是写死的线性流水线，而是带状态判断的轻量级状态机。

什么是状态机思想？简单说，每个任务在执行完之后，系统要能根据输出质量、用户意图等因素，决定下一步是“继续推进”还是“返工重做”还是“交由人工介入”。这个判断逻辑看起来不复杂，但它是整个多智能体系统能否真正落地的分水岭。

举个例子，在内容生成场景里，我把流程设计成六个状态：

待拆解 -> 已拆解 -> 执行中 -> 待审核 -> 已通过/需返工 -> 已交付

当质检Agent给出“通过”结论时，任务进入“已交付”状态；当它给出“返工”结论时，任务带着修改意见回到“执行中”状态，由执行Agent根据意见重做。这样一来，系统就具备了自我纠偏的能力，而不是一条道跑到黑。

2.3 上下文管理的实操细节

多Agent协作最常见的技术坑，是上下文“交叉感染”。具体表现是：两个并行运行的Agent在你不知情的情况下共享了某段上下文，或者上游Agent的输出没有被下游正确处理，导致信息层层失真。

我自己的处理方案是：每两个Agent之间的交接信息，必须采用“双通道”传递。第一个通道是“结构化数据”，比如JSON格式的结果清单；第二个通道是“负责人解读”，即上游Agent用一段自然语言概括自己的交付结论。下游Agent优先读取结构化数据，遇到疑问时参考负责人解读。这么做能避免因为“格式完美但语义模糊”导致的错误理解。

再有一个细节：给每个Agent配上足够但不过量的上下文背景。比如执行Agent执行某一个具体任务时，只需要给它任务描述、相关输入、角色卡，不需要把整个项目的历史记录都塞给它。很多系统越跑越慢、越跑越乱，就是因为上下文里堆了太多历史包袱。

3. 实操过程与核心环节实现

3.1 从零搭建一个“调研-分析-成稿”的最小闭环

纸上谈兵先告一段落，我们来看一个能真正跑起来的最小闭环。这个Demo只包含三个角色：调研助理、分析专员、内容编辑，外加一个简单的调度逻辑。目标是：输入一个话题，自动输出一份结构完整的文章初稿。

我选用的技术栈很简单：Python 3.10以上版本，前后端不分离，用命令行触发。核心流程是：

1. 启动时读取一个YAML格式的配置文件，加载角色卡和任务流程。
2. 创建三个Agent实例，每个实例持有一个独立的大模型会话上下文。
3. 调度器按流程顺序依次调用Agent，并传递上一环节的输出。

关键代码如下（去掉了与具体API相关的细节，保留核心逻辑）：

# dispatcher.py class Dispatcher: def __init__(self, agents: dict, flow: list): self.agents = agents self.flow = flow self.results = {} def run(self, user_input: str): current_input = user_input for step in self.flow: agent = self.agents[step["agent"]] task_prompt = step["template"].format(input=current_input) output = agent.run(task_prompt) self.results[step["name"]] = output current_input = output # 链式传递 return self.results

这段代码做了几件关键的事：

• 通过flow列表定义流程顺序：你可以按“调研->分析->成稿”排，也可以按“成稿->分析->调研”排，流程调整只改配置，不动代码。
• 每次都把上一步的输出作为下一步的输入：这就是最简单的链式传递。在实际项目中，你还需要对中间结果做校验和清洗，防止无效数据进入下一步。

3.2 一个带记忆与工具调用的增强版编排

链式传递虽然简单，但处理不了需要“回溯”“并行”“条件分支”的场景。所以我通常会在基础版本上增加两个能力：短期记忆和工作日志。

短期记忆的作用，是让每个Agent记住“我在为哪个项目干活”“这个项目当前进展到哪一步了”。我实现的方式是维护一个全局的Key-Value存储，键是任务ID，值是当前状态、执行结果、Agent反馈。每次Agent执行完毕后，调度器都会更新这个存储。

工作日志的作用，是让系统可以随时复盘。我会为每一个执行操作生成一条结构化日志，内容包括：时间戳、Agent名称、输入摘要、输出摘要、消耗Token数、执行时长。这套日志在后续排查问题时价值巨大——下面第4部分会专门讲，这里先按下不表。

增强版的执行流程我一般这样写：

class EnhancedDispatcher: def __init__(self, agents, flow, memory, logger): self.agents = agents self.flow = flow self.memory = memory self.logger = logger def _format_agent_input(self, agent_name, raw_input): # 从记忆中加载该任务相关的历史上下文 context = self.memory.get_context(agent_name) return { "task": raw_input, "context_summary": context, "agent_profile": self.agents[agent_name]["profile"] } def execute_step(self, step, payload): agent = self.agents[step["agent"]] formatted = self._format_agent_input(step["agent"], payload) response = agent.execute(formatted) self.logger.record( agent=step["agent"], action=step["name"], input=payload, output=response, token_cost=response.usage ) self.memory.update(step["agent"], step["name"], response.content) return response

这里有一个很容易被忽视的点：每次Agent调用的输入，不是简单地把用户问题直接塞进去。必须加上系统提示词，明确告诉Agent“你现在处于整个流程的哪一步，你前面是谁，你后面是谁，你的输出要给谁用”。这能显著减少Agent“自作主张”的概率。你别说，很多系统跑着跑着就崩，多数就是输给Agent的指令太模糊。

3.3 真实运行演示：一次完整的“菜谱生成器多Agent流程”

空谈没用，我们看一个实战案例。这是我的一个朋友的实操项目，用agencey-agents的思路做了一个“菜谱生成器”：

• 用户需求：输入“三个人的家常晚餐，两荤一素一汤”
• 角色池：营养师（评估食材搭配）、创意主厨（设计菜谱）、文档专员（格式化输出）
• 流程：营养师先给出食材建议清单和禁忌提示 -> 创意主厨在清单范围内设计具体菜谱 -> 文档专员把菜谱排版成标准格式

实际运行日志摘要如下：

[10:02:01] 用户输入: 三个人的家常晚餐，两荤一素一汤 [10:02:03] 营养师执行中... [10:02:10] 营养师输出：建议三荤一素，荤素比例建议1:1，注意补充优质蛋白... [10:02:11] 创意主厨执行中... [10:02:23] 创意主厨输出：红烧鸡翅、清蒸鲈鱼、蒜蓉西兰花、番茄蛋花汤... [10:02:24] 文档专员执行中... [10:02:29] 完整菜谱已生成，包含食材清单、步骤和预估耗时 [10:02:30] 本次流程总耗时28秒，总Token消耗约4200

你可能会说，这样的流程明明可以一个Agent完成，为什么要拆三个？因为如果由一个Agent全包，它可能在给出菜谱之后又忍不住去评论“这个菜谱比较健康”或者“如果你们吃不了辣可以换成…”——这些无意义内容在真实内容生产场景里就是杂质。拆分之后，每个环节的输出都聚焦，交付文档由文档专员格式把关，质量明显更稳定。

4. 常见问题与排查技巧实录

4.1 多Agent协作中的“死循环”问题

这是所有同类项目跑起来后最先遇到的坑。表现形态是：Agent A认为需要Agent B的输入才能继续，Agent B又认为需要Agent A的输出才能推进，两边互相等待，调度器也没有设定超时机制，整个系统卡死。

我在真实项目里遇到过最离谱的一次，是上游Agent觉得“信息不充分”自动发起了补充调研，而调研Agent拿着调研结果反问“这个结论是要给哪一步用的”。两个Agent在对话层面上自己聊起来了，完全绕过了调度流程。

解决办法有两个方向。最直接的是在设计角色卡时，给每个Agent加上“禁止主动向其他Agent发起对话”的约束。第二个是在调度器层面增加超时和熔断机制：单个步骤执行超过一定时间或轮次，直接终止并标记为失败，交由人工处理。没有熔断机制，多Agent系统就像没有安全阀的锅炉，迟早爆给你看。

4.2 上下文污染引发的“记忆错乱”

另一个高频问题是上下文污染。具体表现是，Agent在执行当前任务时，莫名其妙地引用了很久之前另一个任务的输出，甚至是另一个项目的资料。导致这个问题的核心原因是：共享会话上下文或共享工具状态时，没有做隔离。

我的排查经验是：先看工作日志，确认每个Agent每次调用的输入到底是什么。如果发现输入里混入了不该出现的字段，那基本可以断定是上下文拼接逻辑写错了。修复方式也很简单，每次调用前强制重置上下文缓冲，只保留当前任务必需的信息。

4.3 排查技巧：从“结果不对”到“定位病灶”的三板斧

在多Agent系统里排查问题，和传统软件完全不同。传统软件出问题，你查代码逻辑就行；这里出问题，你得像“案发现场勘查”一样，把每个Agent的思维过程还原出来。我总结了三板斧：

• 第一板斧：轨迹回放。打开工作日志，按时间线把每个Agent的输入输出重放一遍。重点看上一次调用的输出是不是下一次调用的输入，中间有没有被截断或被改写。
• 第二板斧：上下文审查。把某个Agent执行某次任务时携带的所有上下文打印出来，逐条核对。很多时候你会发现，输出里出现的一个奇怪信息，其实来自某段被错误拼接的历史记录。
• 第三板斧：降级测试。把多Agent流程改为单Agent直接调用，看相同输入下结果是否正常。如果单Agent正常而多Agent不正常，说明问题出在流程衔接或上下文管理上；如果单Agent也不正常，那问题在模型能力或工具调用上，跟多Agent协作无关。

4.4 成本失控：Token消耗量远超预期

多Agent协作天然比单Agent调用消耗更多Token，这一点在立项时就要有心理准备。但有一些浪费是可以避免的。最常见的是：Agent把相同的上下文重复传给每一个子任务，导致上下文账单暴涨。

我的优化办法是：控制上下文“只送必要片段”。另外，为每个Agent调用设置单次Token上限和整个流程的总预算，一旦超出就终止流程并告警。从经验看，经过上下文精简后的多Agent流程，Token消耗能比“全量上下文”方案节省40%到60%，而且任务完成质量不降反升，因为减少了噪音干扰。

下面整理了一张自检清单，适合在部署上线前逐项打勾：

4.5 我踩过印象最深的一个坑：Agent“人身攻击”式互评

一次项目中，我设置了“统计员”和“文案员”两个角色。结果文案员输出初稿后，统计员审核时用“这段数据明显有问题”直接否掉了初稿，但统计员并没有给出具体的修改建议，文案员也不知道该改什么，来回拉锯三次之后流程才终于结束。后来我排查发现，是统计员的角色卡里“严格审核”写得太绝对了，导致它倾向于“一刀切”式否决。

这件事让我意识到：在多Agent协作中，角色卡的语气指令，比功能指令更容易影响行为。同样是审核角色，“你负责检查数据准确性，发现问题时列出具体清单，并给出修改建议”和“你要严格把关，发现问题就退回”这两种表述，实际走查出来的效果截然不同。后者会让Agent动辄退回，产出极不稳定。所以你在设计角色卡时，一定要避免使用模糊的情感倾向词汇，尽量把动作指令写具体。

5. 技术选型与工具建议

5.1 技术栈选型：别一上来就上重型框架

关于实现方式，我强烈建议新手从“直接调用模型API+自行编排”起步，而不是一上来就套一个重型多Agent框架。原因很简单：重型框架虽然提供了很多现成模块，但也把关键细节藏在了黑盒里。一旦流程出问题，你很难判断是框架bug还是你自己的逻辑问题。

自行编排最简实现我上面已经写过了，大概两百行核心代码就能跑通。当你把基础流程跑顺之后，再考虑引入框架来提升效率也不迟。挑选框架时，我建议优先关注三点：是否支持自定义角色卡、是否支持任务级状态管理、是否提供完整的日志系统。

5.2 模型选型：不同角色可以搭配不同模型

多Agent系统一个常被忽略的优势是：没必要让所有Agent都使用同一个最强模型。调研类角色、格式化输出类角色可以用响应更快、成本更低的小模型；分析判断类角色、创意生成类角色再上推理能力更强的大模型。这个模型路由策略能显著降低整体成本，同时保持关键节点的输出质量。

我自己在项目里常用一个非常简洁的路由规则：

任务类型 = 信息提取、格式转换 -> 小型模型（低延迟优先） 任务类型 = 分析推理、复杂生成 -> 大型模型（质量优先） 任务类型 = 质量审核 -> 大型模型 + 特殊审核提示词

实际操作时，调度器只需在调用模型前根据任务类型做一次模型选择即可实现。对于刚起步的朋友，这算是最容易落地的一笔“省钱优化”。

5.3 部署经验：本地优先，云上备份

最后说说部署。多Agent系统最怕的是单一模型服务商出问题导致整个流水线瘫痪。我的建议是：本地部署一套开源模型作为备用通道，平时跑廉价任务用它，关键任务优先用商业API，一旦商业API超时或报错，自动切换本地模型兜底。这套双通道冗余机制，已经被我验证过不止一次——在API高峰期能救命。

一点个人体会

项目拆到这里，我再啰嗦两句实在话。这个项目给我最大的启发，不是“AI有多智能”，而是“人的管理经验有多值钱”。你在现实中怎么带团队、怎么做项目管理、怎么盯交付质量，这套方法论几乎可以一比一翻译成多Agent系统的设计。反过来，它也逼着我去反思自己平时协作流程里到底哪些环节是多余的、哪些指令是模糊的、哪些信息是不该共享的。想不清楚这些，别说AI Agent，真实的团队也一样跑不起来。

最后分享一个我屡试不爽的小技巧：每次新增一个Agent角色之前，先问自己一句——如果这个环节没有AI，你会找一个什么样的同事来干？照着这个“真人标准”去写角色卡和边界约束，出来的系统往往比想象中要稳得多。