多智能体协作框架agency-agents全拆解：架构设计与实操落地

1. 从"agency-agents"这个标题说起：一个多智能体协作框架的完整拆解

第一次看到"agency-agents"这个标题的时候，我脑子里蹦出来的第一个念头是：这大概率是一个围绕"代理"和"智能体"做文章的项目，而且从命名习惯来看，它很可能不是单指某一个具体的Agent，而是一整套"代理体系"或者"代理机构"式的架构。为什么这么说？因为"agency"这个词在英文语境里本身就带有"机构、中介、代理关系"的含义，它强调的不是单个个体，而是一群个体之间的协作、委托与执行关系。把它和"agents"放在一起，基本可以确定这是一个**多智能体协作（Multi-Agent Collaboration）**方向的项目。

我在过去几年里陆陆续续接触过不少Agent相关的项目，从最简单的单轮工具调用，到复杂的多角色编排，踩过的坑不算少。所以当我拿到这个标题的时候，我第一反应不是去查它到底用了什么框架，而是先想清楚一件事：一个叫"agency-agents"的东西，它到底要解决什么问题？我的判断是，它要解决的是"单个Agent能力边界有限，而真实任务往往需要多个角色分工协作"这个核心矛盾。换句话说，它想做的事情，是把一个复杂任务拆解成若干子任务，然后交给不同的Agent去分别执行，最后再汇总结果。

这篇文章我会按照我自己做项目复盘的习惯来写，不讲空话，直接从架构设计、核心细节、实操落地、问题排查这几个维度，把这个项目从头到尾拆一遍。如果你正在做多智能体相关的开发，或者你手上有一个复杂任务想用Agent的方式去自动化，那这篇内容应该能给你不少可以直接抄作业的东西。我会尽量把每个设计决策背后的"为什么"讲清楚，因为我自己最烦的就是那种只告诉你"怎么做"却不告诉你"为什么这么做"的教程。

2. 整体架构设计：为什么是"代理机构"而不是"单个超级Agent"

2.1 核心思路：把"一个全能选手"拆成"一个专业团队"

在动手设计任何多智能体系统之前，有一个根本性的架构选择摆在面前：你是做一个能力极强的单体Agent，还是做一群能力专精但需要协作的Agent？这两种路线我都实际做过，各有各的适用场景，但"agency-agents"这个命名本身就暗示了它选择了后者。

单体超级Agent的思路是，给它挂上足够多的工具，写一个足够长的系统提示词，让它自己判断该调用什么、该怎么处理。这种方案在任务类型单一、流程线性的时候非常好用，开发成本低，调试也简单。但一旦任务变得复杂，比如需要同时处理信息检索、数据分析、内容生成、质量校验这几个环节，单体Agent就会开始"精神分裂"——它在一个上下文里既要记住原始需求，又要记住中间结果，还要兼顾最终输出的格式要求，上下文窗口很快就被塞满了，而且它很容易在某个环节跑偏，导致整个任务失败。

多智能体协作的思路则完全不同。它把上面那个复杂任务拆成几个独立的角色：一个负责检索信息的"研究员"，一个负责处理数据的"分析师"，一个负责写内容的"撰稿人"，还有一个负责检查质量的"审核员"。每个角色只关心自己那一亩三分地，上下文干净，职责清晰。这就是"agency"这个词的精髓——它不是一个员工，而是一家公司，公司里有不同的岗位，岗位之间有明确的协作流程。

我个人的经验是，当任务可以清晰地拆分成3个以上相对独立的子任务，且子任务之间有明确的输入输出关系时，多智能体架构的收益会明显大于成本。反之，如果任务本身就是线性的、简单的，硬上多智能体只会增加复杂度和调试难度。

2.2 方案选型：编排模式决定了系统的上限

确定了多智能体的方向之后，下一个关键决策是"编排模式"。我见过和用过的编排模式大致有这么几种，这里用一个表格对比一下，方便你根据自己的场景选。

"agency-agents"这类项目，从我接触到的类似实现来看，最常用的是"主管调度 + 顺序流水线"的混合模式。也就是说，顶层有一个协调者负责理解用户意图、拆解任务、决定调用哪些Agent，而具体的执行环节则按照相对固定的流水线走。这种混合模式的好处是兼顾了灵活性和可控性——协调者负责"决策"，执行者负责"干活"，各司其职。

为什么我不推荐一上来就用辩论/投票模式？因为它的成本实在太高了。假设你有5个Agent，每个都要对同一个问题生成一遍答案，token消耗直接翻5倍，而且汇总环节本身也需要一次额外的模型调用。除非你的任务对准确性要求极高，比如涉及关键决策，否则没必要。

2.3 通信机制：Agent之间到底怎么"说话"

多智能体系统里，Agent之间的通信机制是一个容易被忽视但极其关键的细节。我见过很多项目在这里翻车，最后表现为"Agent A的输出Agent B根本读不懂"。

常见的通信方式有三种。第一种是结构化消息传递，也就是Agent之间传的是JSON格式的数据，字段明确，比如{"task": "search", "query": "xxx", "result": "..."}。这种方式最可靠，解析起来不会出错，但灵活性差，需要提前定义好所有消息格式。第二种是自然语言传递，Agent A直接把一段文字丢给Agent B，让B自己去理解。这种方式灵活，但容易出现理解偏差，尤其是当A的输出格式不稳定时。第三种是共享内存/状态，所有Agent读写同一个状态对象，类似黑板模式。

我的实操建议是：在关键的、格式要求严格的环节用结构化消息，在需要灵活表达的环节用自然语言，并且一定要在Agent的系统提示词里明确告诉它"你的输出会被谁读取，格式要求是什么"。这一点非常关键，很多协作失败的根本原因就是上游Agent不知道下游Agent需要什么格式。

3. 核心细节解析：Agent角色定义与提示词工程

3.1 角色定义：每个Agent都应该有清晰的"岗位说明书"

在多智能体系统里，定义一个Agent本质上就是写一份"岗位说明书"。这份说明书要回答几个问题：这个Agent的职责边界是什么？它有哪些工具可以用？它的输入从哪来？它的输出给谁？它的工作标准是什么？

我见过太多项目在这里偷懒，给Agent的系统提示词就一句话"你是一个助手，请帮助用户完成任务"。这种提示词在多智能体环境里是灾难性的，因为Agent根本不知道自己该干什么、不该干什么，结果就是要么什么都不做，要么越界去做别的Agent的活。

一个合格的Agent角色定义，我通常会包含这几个部分。身份定位，用一两句话说明它是谁，比如"你是一名专注于信息检索的研究员，你的任务是从给定资料中提取与问题相关的事实"。能力边界，明确告诉它什么能做、什么不能做，比如"你只负责检索和整理信息，不要进行分析和判断，分析工作由下游的分析师完成"。输入说明，告诉它接收到的数据长什么样。输出规范，明确输出的格式、字段、长度要求。工作原则，比如"如果找不到相关信息，明确说明'未找到'，不要编造"。

这里我要特别强调"能力边界"这一条。在多智能体系统里，Agent越界是最常见的问题之一。比如研究员Agent本来只该检索信息，结果它自作主张地给出了分析结论，导致下游分析师拿到的是已经被"污染"的输入。明确边界能大幅降低这类问题。

3.2 提示词工程：多智能体场景下的三个特殊技巧

单Agent场景下的提示词技巧，比如角色扮演、思维链、少样本示例，在多智能体场景下依然适用，但有几个额外的技巧是我在实际项目中总结出来的，效果非常明显。

第一个技巧是**"交接意识"提示**。你要在提示词里明确告诉Agent，它的输出会被谁接手。比如在撰稿人Agent的提示词里写"你的输出将直接交给审核员Agent进行质量检查，请确保格式规范、逻辑清晰，便于审核"。这一句话能显著提升输出的规范性，因为Agent"知道有人在检查它"。

第二个技巧是**"失败处理"提示**。多智能体系统里，任何一个环节失败都可能导致整个流程崩溃。所以要在提示词里明确告诉Agent遇到异常情况该怎么办。比如"如果输入数据缺少必要字段，不要猜测，直接输出{"status": "error", "reason": "缺少xxx字段"}，让协调者决定如何处理"。这种显式的失败处理机制，能让系统在出错时优雅降级，而不是直接崩溃。

第三个技巧是**"输出模板"约束**。对于格式要求严格的Agent，直接在提示词里给出输出模板，甚至给出一个完整的示例。比如"请严格按照以下JSON格式输出：{"summary": "...", "key_points": ["...", "..."], "confidence": 0.0-1.0}"。实测下来，给出模板比单纯用文字描述格式要求，输出合规率能提升一大截。

3.3 上下文管理：别让Agent被无关信息淹没

多智能体系统里，上下文管理是一个隐形的性能杀手。每个Agent在执行任务时，它的上下文里应该只包含"完成当前任务所必需的信息"，而不是整个系统的全部历史。

我踩过的一个坑是，早期为了图省事，把所有Agent的对话历史都塞进一个共享上下文里，结果每个Agent的上下文都变得极其臃肿，不仅token消耗飙升，而且Agent经常被无关信息干扰，输出质量明显下降。后来我改成每个Agent维护独立的上下文，只接收上游传递的必要输入，效果立竿见影。

具体怎么做？协调者在调用某个Agent时，只传递这个Agent需要的输入，而不是把整个任务历史都丢过去。比如调用撰稿人Agent时，只传给它"分析结论"和"写作要求"，不需要传"研究员检索了哪些网页"这种中间过程。这样每个Agent的上下文都很干净，专注度自然就高了。

提示：上下文隔离是多智能体系统性能优化的第一优先级。如果你发现系统响应慢、输出质量差，先检查是不是上下文塞了太多无关信息。

4. 实操过程：从零搭建一个agency-agents式协作系统

4.1 环境准备与基础框架搭建

假设我们要搭建一个处理"行业调研报告生成"的多智能体系统，包含四个角色：研究员、分析师、撰稿人、审核员。下面我把关键环节的实现思路和代码骨架讲清楚。

首先是基础框架。我推荐用Python来做，因为生态成熟，调试方便。核心需要的是一个"Agent基类"，封装模型调用、工具调用、上下文管理这些通用逻辑。下面是一个简化的基类骨架：

class BaseAgent: def __init__(self, name, system_prompt, tools=None): self.name = name self.system_prompt = system_prompt self.tools = tools or [] self.context = [] def build_messages(self, user_input): messages = [{"role": "system", "content": self.system_prompt}] messages.extend(self.context) messages.append({"role": "user", "content": user_input}) return messages def run(self, user_input): messages = self.build_messages(user_input) response = call_llm(messages, tools=self.tools) self.context.append({"role": "user", "content": user_input}) self.context.append({"role": "assistant", "content": response}) return response

这个基类看起来简单，但已经把核心逻辑封装好了：系统提示词、上下文维护、模型调用。每个具体的Agent只需要继承它，传入自己的系统提示词和工具集就行。

这里有个细节值得说一下：上下文要不要持久化。我的做法是，对于需要多轮交互的Agent（比如需要反复检索的研究员），上下文保留；对于一次性的Agent（比如只负责格式转换的），每次调用后清空上下文。这样能避免上下文无限增长。

4.2 协调者的实现：任务拆解与调度逻辑

协调者是整个系统的大脑，它负责理解用户需求、拆解任务、按顺序调用各个Agent、处理异常。它的实现有两种思路：一种是用规则硬编码流程，另一种是让模型动态决策。我的建议是混合使用——主流程用规则固定，分支和异常处理交给模型。

下面是一个简化的协调者实现：

class Coordinator: def __init__(self): self.researcher = ResearcherAgent() self.analyst = AnalystAgent() self.writer = WriterAgent() self.reviewer = ReviewerAgent() def execute(self, user_request): # 第一步：研究员检索信息 research_result = self.researcher.run(user_request) if is_error(research_result): return handle_error(research_result) # 第二步：分析师处理数据 analysis_result = self.analyst.run(research_result) if is_error(analysis_result): return handle_error(analysis_result) # 第三步：撰稿人撰写报告 draft = self.writer.run(analysis_result) # 第四步：审核员检查，不通过则打回重写 review_result = self.reviewer.run(draft) retry_count = 0 while not review_result["passed"] and retry_count < 3: draft = self.writer.run( f"请根据以下审核意见修改：{review_result['feedback']}\n原文：{draft}" ) review_result = self.reviewer.run(draft) retry_count += 1 return draft

这段代码里有一个关键设计：审核不通过时的重试机制。我设置了最大重试次数3次，避免死循环。这个重试机制是多智能体系统里非常实用的一个模式，它让系统具备了自我纠错的能力。实测下来，大部分问题在1到2次重试内就能解决。

4.3 关键参数计算：超时、重试与成本控制

多智能体系统比单Agent系统更容易出现"跑飞"的情况，所以参数设置要格外谨慎。这里我把几个关键参数的计算逻辑讲一下。

超时时间。每个Agent的单次调用都应该设置超时。我的经验值是，简单任务（如格式转换）设30秒，复杂任务（如长文生成）设120秒。超时后不要直接失败，而是触发重试或降级处理。

重试次数。重试次数不是越多越好。我一般设置最大重试3次，且采用指数退避策略，第一次等1秒，第二次等2秒，第三次等4秒。这样既能应对偶发的网络抖动，又不会在真正失败时浪费太多时间。

成本预估。这是很多人忽视的一点。假设一个任务要调用4个Agent，每个Agent平均消耗2000 token输入、1000 token输出，那么单次任务的总消耗大约是12000 token。如果加上重试，实际消耗可能是1.5倍，也就是18000 token。在批量处理场景下，这个数字要提前算清楚，否则很容易超预算。

4.4 实操现场记录：一次完整的报告生成流程

我拿一个实际跑过的案例来说明整个流程。用户输入是"帮我生成一份关于智能家居行业现状的调研报告"。

协调者首先把这个需求交给研究员Agent。研究员的系统提示词里明确写了"你只负责检索和整理信息，输出格式为要点列表，每条要点注明来源"。它调用检索工具，返回了大约15条要点。

接着分析师Agent接手。它的提示词是"你负责对研究员的要点进行归类、提炼和趋势判断，输出结构化的分析结论，包含'市场现状'、'主要玩家'、'技术趋势'、'风险提示'四个部分"。它把15条要点整理成了四个部分的分析。

然后撰稿人Agent根据分析结论撰写报告。它的提示词里包含了报告的结构要求和字数要求，输出了一份大约2000字的初稿。

最后审核员Agent检查。它的提示词是"你负责检查报告的事实准确性、逻辑连贯性和格式规范性，输出JSON格式的审核结果，包含passed字段和feedback字段"。第一次审核时，它指出"风险提示部分论据不足"，于是撰稿人根据反馈补充了内容，第二次审核通过。

整个流程跑下来，从输入到最终报告，耗时大约90秒，消耗token约16000。这个效率对于一份2000字的调研报告来说，我认为是可以接受的。

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

5.1 Agent输出格式不稳定怎么办

这是多智能体系统里最高频的问题。表现是：明明在提示词里写了要输出JSON，结果Agent有时候输出JSON，有时候输出一段带解释的文字，导致下游解析失败。

我的排查思路是这样的。首先，检查提示词里有没有给出完整的输出示例。只写"请输出JSON"是不够的，要给出一个具体的、填好内容的JSON示例。其次，检查有没有用结构化输出功能。现在很多模型API都支持强制JSON输出，能开就开，这是最可靠的方案。最后，如果还是不稳定，就在解析层加一层容错处理，比如用正则从文本里提取JSON部分，或者让一个专门的"格式化Agent"做二次处理。

注意：不要指望通过反复强调"一定要输出JSON"来解决格式问题，模型对否定式指令的遵循度往往不如对示例的模仿度。

5.2 Agent之间"踢皮球"或"重复劳动"

这个问题的表现是：任务在几个Agent之间来回传递，但始终没有实质进展，或者两个Agent做了重复的工作。

根本原因通常是职责边界不清。比如研究员和分析师都觉得自己该做分析，结果研究员做了分析，分析师又做了一遍。解决办法是在每个Agent的提示词里用明确的"你不负责xxx"来划清边界。另外，协调者在传递任务时，要明确告诉下游Agent"上游已经完成了什么，你只需要做什么"，避免重复。

5.3 系统整体响应太慢

多智能体系统因为要串行调用多个Agent，响应慢是常态。但如果慢到不可接受，就要排查了。

排查顺序是这样的。先看是不是串行调用太多。如果某些Agent之间没有依赖关系，可以改成并行调用。比如研究员检索多个来源，完全可以并行。再看是不是上下文太大。上下文越大，模型处理越慢，检查每个Agent的上下文是不是塞了无关信息。最后看是不是重试次数过多。如果某个Agent频繁重试，说明它的任务设计有问题，要从提示词层面解决，而不是靠重试硬扛。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是过度依赖模型动态决策。早期我让协调者完全靠模型来决定调用哪个Agent，结果模型经常做出奇怪的决策，比如跳过研究员直接让撰稿人写。后来我改成主流程硬编码，只在异常处理时用模型决策，稳定性大幅提升。

第二个坑是忽视日志记录。多智能体系统的调用链路很长，出问题时如果没有详细的日志，根本不知道是哪一步出的错。我现在会在每个Agent的输入输出都打日志，包括时间戳、token消耗、耗时，排查问题时一目了然。

第三个坑是没有做幂等设计。有一次系统在重试时，把同一个任务重复执行了两遍，导致下游收到了两份数据。后来我在每个任务上加了一个唯一ID，重复ID直接跳过，问题就解决了。

6. 扩展方向：这个架构还能怎么用

"agency-agents"这套多智能体协作的思路，其实不局限于报告生成。我自己把它迁移到过好几个场景，效果都不错。

一个是代码审查场景。把角色换成"代码规范检查员"、"逻辑漏洞检查员"、"性能优化建议员"，三个Agent分别从不同角度审查同一份代码，最后汇总。这种多视角审查比单个Agent审查的漏检率低很多。

另一个是内容多平台适配场景。一个Agent负责写原始内容，另外几个Agent分别负责把它改写成适合不同平台风格的版本。因为每个平台的风格要求不同，用独立的Agent来处理比让一个Agent兼顾所有风格效果更好。

还有一个是数据清洗场景。多个Agent分别负责去重、格式统一、异常值检测，最后汇总。这种流水线式的处理，每个环节职责单一，出错容易定位。

我的体会是，多智能体架构的价值不在于Agent本身有多强，而在于它把一个复杂问题拆解成了若干个简单问题。当你发现一个任务用单个Agent做总是顾此失彼的时候，就该考虑用"agency"的思路，把它拆成一个团队来做了。当然，拆解本身也是有成本的，拆得太细会导致协作开销超过收益，这个度需要根据具体任务来把握。我一般的经验是，单个Agent的任务复杂度控制在"一个明确的目标 + 两三个步骤"比较合适，超过这个范围就该考虑拆分了。