1. 从agency-agents这个标题说起一个多智能体协作框架的完整拆解第一次看到agency-agents这个标题的时候我脑子里蹦出来的第一个念头是这大概率是一个围绕代理和智能体做文章的项目而且从命名习惯来看它很可能不是单指某一个具体的Agent而是一整套代理体系或者代理机构式的架构。为什么这么说因为agency这个词在英文语境里本身就带有机构、中介、代理关系的含义它强调的不是单个个体而是一群个体之间的协作、委托与执行关系。把它和agents放在一起基本可以确定这是一个**多智能体协作Multi-Agent Collaboration**方向的项目。我在过去几年里陆陆续续接触过不少Agent相关的项目从最简单的单轮工具调用到复杂的多角色编排踩过的坑不算少。所以当我拿到这个标题的时候我第一反应不是去查它到底用了什么框架而是先想清楚一件事一个叫agency-agents的东西它到底要解决什么问题我的判断是它要解决的是单个Agent能力边界有限而真实任务往往需要多个角色分工协作这个核心矛盾。换句话说它想做的事情是把一个复杂任务拆解成若干子任务然后交给不同的Agent去分别执行最后再汇总结果。这篇文章我会按照我自己做项目复盘的习惯来写不讲空话直接从架构设计、核心细节、实操落地、问题排查这几个维度把这个项目从头到尾拆一遍。如果你正在做多智能体相关的开发或者你手上有一个复杂任务想用Agent的方式去自动化那这篇内容应该能给你不少可以直接抄作业的东西。我会尽量把每个设计决策背后的为什么讲清楚因为我自己最烦的就是那种只告诉你怎么做却不告诉你为什么这么做的教程。2. 整体架构设计为什么是代理机构而不是单个超级Agent2.1 核心思路把一个全能选手拆成一个专业团队在动手设计任何多智能体系统之前有一个根本性的架构选择摆在面前你是做一个能力极强的单体Agent还是做一群能力专精但需要协作的Agent这两种路线我都实际做过各有各的适用场景但agency-agents这个命名本身就暗示了它选择了后者。单体超级Agent的思路是给它挂上足够多的工具写一个足够长的系统提示词让它自己判断该调用什么、该怎么处理。这种方案在任务类型单一、流程线性的时候非常好用开发成本低调试也简单。但一旦任务变得复杂比如需要同时处理信息检索、数据分析、内容生成、质量校验这几个环节单体Agent就会开始精神分裂——它在一个上下文里既要记住原始需求又要记住中间结果还要兼顾最终输出的格式要求上下文窗口很快就被塞满了而且它很容易在某个环节跑偏导致整个任务失败。多智能体协作的思路则完全不同。它把上面那个复杂任务拆成几个独立的角色一个负责检索信息的研究员一个负责处理数据的分析师一个负责写内容的撰稿人还有一个负责检查质量的审核员。每个角色只关心自己那一亩三分地上下文干净职责清晰。这就是agency这个词的精髓——它不是一个员工而是一家公司公司里有不同的岗位岗位之间有明确的协作流程。我个人的经验是当任务可以清晰地拆分成3个以上相对独立的子任务且子任务之间有明确的输入输出关系时多智能体架构的收益会明显大于成本。反之如果任务本身就是线性的、简单的硬上多智能体只会增加复杂度和调试难度。2.2 方案选型编排模式决定了系统的上限确定了多智能体的方向之后下一个关键决策是编排模式。我见过和用过的编排模式大致有这么几种这里用一个表格对比一下方便你根据自己的场景选。编排模式核心特征适用场景主要缺点顺序流水线Agent按固定顺序依次执行流程固定的任务如检索-分析-写作缺乏灵活性无法应对分支主管调度一个主管Agent动态分配任务任务类型多变需要动态决策主管Agent容易成为瓶颈黑板模式所有Agent共享一块黑板读写需要频繁共享中间状态状态管理复杂易冲突辩论/投票多个Agent对同一问题给出答案再汇总需要高可靠性的判断类任务成本高耗时长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, toolsNone): 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, toolsself.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。在批量处理场景下这个数字要提前算清楚否则很容易超预算。参数推荐值说明单Agent超时30-120秒按任务复杂度分档最大重试次数3次配合指数退避上下文保留轮数3-5轮避免上下文膨胀单任务token预算15000-20000含重试余量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 常见问题速查表问题现象可能原因排查方向解决技巧输出格式不稳定提示词缺示例检查是否有完整输出示例加示例开结构化输出Agent互相踢皮球职责边界不清检查各Agent提示词明确不负责范围响应速度慢串行过多/上下文过大分析调用链路并行化上下文隔离任务中途崩溃缺失败处理检查异常分支加显式错误输出结果质量差上游污染下游检查数据传递结构化消息格式校验5.5 几个我踩过的坑第一个坑是过度依赖模型动态决策。早期我让协调者完全靠模型来决定调用哪个Agent结果模型经常做出奇怪的决策比如跳过研究员直接让撰稿人写。后来我改成主流程硬编码只在异常处理时用模型决策稳定性大幅提升。第二个坑是忽视日志记录。多智能体系统的调用链路很长出问题时如果没有详细的日志根本不知道是哪一步出的错。我现在会在每个Agent的输入输出都打日志包括时间戳、token消耗、耗时排查问题时一目了然。第三个坑是没有做幂等设计。有一次系统在重试时把同一个任务重复执行了两遍导致下游收到了两份数据。后来我在每个任务上加了一个唯一ID重复ID直接跳过问题就解决了。6. 扩展方向这个架构还能怎么用agency-agents这套多智能体协作的思路其实不局限于报告生成。我自己把它迁移到过好几个场景效果都不错。一个是代码审查场景。把角色换成代码规范检查员、逻辑漏洞检查员、性能优化建议员三个Agent分别从不同角度审查同一份代码最后汇总。这种多视角审查比单个Agent审查的漏检率低很多。另一个是内容多平台适配场景。一个Agent负责写原始内容另外几个Agent分别负责把它改写成适合不同平台风格的版本。因为每个平台的风格要求不同用独立的Agent来处理比让一个Agent兼顾所有风格效果更好。还有一个是数据清洗场景。多个Agent分别负责去重、格式统一、异常值检测最后汇总。这种流水线式的处理每个环节职责单一出错容易定位。我的体会是多智能体架构的价值不在于Agent本身有多强而在于它把一个复杂问题拆解成了若干个简单问题。当你发现一个任务用单个Agent做总是顾此失彼的时候就该考虑用agency的思路把它拆成一个团队来做了。当然拆解本身也是有成本的拆得太细会导致协作开销超过收益这个度需要根据具体任务来把握。我一般的经验是单个Agent的任务复杂度控制在一个明确的目标 两三个步骤比较合适超过这个范围就该考虑拆分了。
