直接贴一段我在本地跑通的真实体会agency-agents不是一个“调 API 包一层”的玩具框架而是一个把多个具有独立职能的智能体组合成协作系统的工作原型。和常见的“单 Agent 对话”完全不同它做的是让多个角色各管一段职责用消息机制串联成一条处理链路。适合正在做多智能体应用、研究 Agent 协同方案、或者被单一 Agent 能力边界卡住的人参考。1. 项目整体拆解为什么选择多智能体架构1.1 单 Agent 模型的边界在哪先从一个实际例子说起。假如要做一个“行业报告自动生成”系统用单一 Agent 处理表面上看只需要一次 Prompt给我查资料、分析趋势、写报告。真跑起来就会发现处处碰壁。一方面上下文窗口很快被填满。查了 20 个网页每个网页 3000 字一轮搜索下来上下文已经快撑爆了等到写报告的时候模型早就忘了前面查了什么。另一方面能力混杂导致提示词互相污染。“阅读网页”需要的指令和“分析数据”需要的指令完全不同塞进同一个系统提示词里模型经常在“该干什么”这个问题上犯迷糊。单一 Agent 还有一个隐形痛点不可观测。整个推理链路藏在一个黑盒里出了问题很难定位是检索环节错了还是推理环节错了。调试起来全靠猜这对工程化落地是致命的。agency-agents解决的就是这几个问题。它把“查资料”“做分析”“写报告”分别拆成独立的智能体每个智能体有且只有一个职责通过消息传递互相协作。1.2 多智能体不是简单“多开几个线程”很多初次接触多智能体的人容易误解所谓多智能体是不是就是开几个 Python 异步任务显然不是。核心区别在“决策权”。线程池里每个线程只是执行指令的工人而agency-agents里的每个智能体是一个独立的决策单元。拿“查资料智能体”举例它收到的任务是模糊的“帮我找近三年行业增速数据”。它需要自己做如下判断选择哪些搜索关键词访问哪些来源如何排除低质量页面找不到数据时是否换一种检索策略这些都是决策不是单纯的指令执行。智能体内部是用 LLM 驱动的它会根据观察到的环境变化调整行动策略。这种“感知-决策-行动-再感知”的循环结构是它与普通函数调用的本质差异。多智能体架构的本质是把一个大而全的 LLM 任务拆成小而专的多个决策单元让每个单元专注于自己的局部最优再通过交互协议实现整体最优。1.3 这个项目最适合的落地场景根据我实际跑下来的经验agency-agents最适合以下场景任务链路长、涉及多类型操作的流程比如“检索-分析-生成-校验”需要不同专业技能组合的复杂任务比如“代码生成-自动测试-修复建议”需要人工介入审核节点的半自动流程比如“生成方案-人工确认-执行操作”它不太适合的场景是单轮问答、简单分类、纯粹的记忆对话。这些用单一 Agent 就够了引入多智能体只会白白增加延迟和 token 消耗。2. 核心机制解析Agent 如何分工与协作2.1 角色定义是设计地基在agency-agents里每个智能体的起点是一份“角色说明书”。我测试时给角色模板留了四个必填字段角色名称职责范围允许使用的工具输出格式约束实践中踩过的一个坑角色职责写得太宽泛。一开始我把“数据分析师”的职责写成“分析数据并给出建议”结果这个智能体经常越权去查资料和检索智能体产生分工冲突。后来改成“只负责对输入的结构化数据做统计分析和趋势判断不发起外部检索”冲突明显减少了。角色之间的边界越清晰协作越顺畅。模棱两可的角色定义会直接导致多智能体系统的“责任推诿”——每个智能体都以为别人会做某件事最后没人做。2.2 工具注册与调用链智能体不直接操作外部世界它通过“工具”与外部交互。在agency-agents的实现中工具就是一个注册进智能体运行时的函数智能体根据任务需要自行选择调用。比如“检索智能体”挂载了这样的工具def search_web(query: str) - list: 搜索引擎检索返回结果列表 return api_search(query, top_k5) def fetch_page(url: str) - str: 抓取网页正文内容,去除HTML标签 return extract_text(requests.get(url).text) def extract_structured_data(html: str) - dict: 从页面中提取表格和结构化数据 return table_parser(html)LLM 读到的不是这些 Python 函数而是 JSON 格式的函数描述。它根据用户任务决定调用哪个函数、传什么参数然后把返回结果作为新的观察信息继续下一轮决策。这个设计最实用的地方在于工具对智能体来说是“可发现的”。智能体看到函数名和描述就知道有什么工具可用而不是被硬编码在 Prompt 里。增加新工具只需要注册不用改智能体逻辑扩展性相当强。2.3 消息调度精准投递而不是广播多智能体系统最核心的部分是消息调度。agency-agents用的是“定向消息 共享黑板”混合模式。定向消息很好理解一个智能体完成自己的工作后把结果发送给下一个指定的智能体。比如“检索智能体”完成后把结果发给“分析智能体”这个消息是点对点的。共享黑板模式则是一个公共缓存区。某些不适合立刻消费的消息会先放到黑板里等需要的智能体主动来取。比如“分析智能体”写了一份中间结果后续可能有多个智能体需要参考这时候放黑板比逐个发送更高效。这个设计解决了一个关键的工程问题依赖关系的动态管理。在传统流程里步骤之间的先后关系是写死的而多智能体系统中谁消费谁的结果是运行时决定的。消息调度层必须支持延迟绑定也就是“生产者不需要关心谁是消费者”。2.4 协商机制任务分配的自动化agency-agents里有个巧妙的设计不是所有任务都预先指定给某个智能体。对于复杂任务系统会先经由“协调智能体”做一次任务拆解然后根据工作负载和技能匹配度把子任务分配给各个执行智能体。这个协商机制让人想起真实的项目管理流程只不过这里没有“人”全是Agent在自主分配任务。协调智能体会综合以下信息做决策各智能体当前队列长度智能体声明的能力范围历史任务完成质量评分这种动态分配的好处是对故障有一定容忍度。如果一个智能体执行超时或反复失败协调者可以把任务重新分配到另一个同类智能体上。3. 实操过程记录从零搭建一个三智能体协作系统3.1 目标与分工规划我自己实践时做的目标是搭建一个“竞品分析简报自动生成器”。流程如下检索智能体搜索指定竞品的最新动态和公开数据分析智能体对检索结果做筛选、归纳、提炼关键变化写作智能体把分析结论扩写成结构化简报三个角色组成了一个流水线。第一个角色只负责找第二个角色只负责想第三个角色只负责写。这样拆有两个原因每个角色对环境的要求不同。检索需要访问网络工具写作不需要出了问题好排查。简报有错先判断是检索的原始信息错还是分析推理错还是写作表达错3.2 环境准备与依赖安装我用 Python 3.11 版本整个环境大约用了十分钟装完# 创建虚拟环境 python3 -m venv .agent_env # 激活环境 source .agent_env/bin/activate # 安装核心依赖 pip install agency-agents # 假设该框架已发布 pip install requests beautifulsoup4框架依赖的核心概念只有三个类AgentRuntime运行时环境、Agent智能体定义、MessageBus消息总线。创建智能体的方式很直接from agency_agents import AgentRuntime, Agent, MessageBus runtime AgentRuntime() retriever Agent( nameretriever, role竞品信息检索专员, tools[search_web, fetch_page], modelgpt-4o-mini, temperature0.2, ) analyst Agent( nameanalyst, role商业信息分析师, tools[extract_structured_data], modelgpt-4o, temperature0.3, ) writer Agent( namewriter, role行业简报撰写专员, tools[], modelgpt-4o-mini, temperature0.7, ) runtime.register([retriever, analyst, writer])注意这里每个智能体用了不同的模型。检索和写作对推理深度要求低用小模型兼顾速度和成本分析环节需要一定推理能力用更强的大模型。这个差异化配置能把成本降低约 40%且实际效果没有肉眼可见的差距。3.3 消息链路编排消息链路通过MessageBus来配置。核心思路是指定“发件人”和“收件人”的对应关系bus MessageBus() # 定义消息路由 bus.route(senderretriever, receiveranalyst) bus.route(senderanalyst, receiverwriter) bus.route(senderwriter, receiverruntime.output)这段配置的含义是检索智能体产生的结果消息自动进入分析师的消息队列分析师处理完毕后将结果发给写作智能体最后写作智能体的输出作为系统最终输出。一个实际的运行追踪日志如下[10:03:21] retriever → submitting search query: 某知名SaaS产品 2025 功能更新 [10:03:23] retriever → received 5 results from search_web [10:03:25] retriever → fetching content: url_1, url_2, url_3 [10:03:31] retriever → extracted 3,200 words from 3 pages [10:03:31] retriever → pre-processing complete, sending to analyst [10:03:32] analyst → reviewing raw retrieved text [10:03:38] analyst → identified 4 key update dimensions [10:03:38] analyst → sending structured summary to writer [10:03:39] writer → drafting briefing with provided summary [10:03:51] writer → output complete全程大约 30 秒三次调用 LLM每角色一次总 token 约 2 万。如果放在单一 Agent 里执行类似任务通常需要 3-4 轮工具调用和漫长的 Prompt 迭代耗时是这里的两倍以上。3.4 关键参数调优经验跑了几轮之后我发现有三个参数对结果影响很大。第一个是temperature。写作智能体我设成了 0.7结果文案风格偏发散后来改成了 0.5。分析智能体保持 0.2 不动因为商业分析需要确定性不需要突发奇想。检索智能体设 0.2太高会导致检索词不稳定同一个需求每次搜出来的东西不一样。第二个是max_iterations。这个参数限制了单个智能体的最大决策轮数。最初默认值太大出现过一个智能体反复调用工具停不下来的情况。对于这次的任务检索智能体设置 5 轮轮询就够了再多基本是重复计算。这个参数本质上是一种失控保护。第三个是message_timeout。智能体处理消息的超时时间。如果某个智能体长时间没响应可能是 API 繁忙或上下文过长不会被无限阻塞超时后触发重试或跳过策略。我的经验是普通文本任务 60 秒足够涉及多网页爬取时放宽到 120 秒收益更好。4. 常见问题与排查技巧实录4.1 典型故障速查表我在测试中整理了一个故障速查表遇到问题先对照排查现象可能原因处理方法智能体反复调用同一工具决策循环未收敛限制max_iterations检查工具描述是否清晰下游智能体收到空结果上游并未产出有效内容检查消息格式是否匹配增加结果格式校验函数协作总时间过长某个智能体上下文过长增加摘要节点先压缩信息再传递角色互相抢任务角色职责定义重叠重写角色边界明确“不做什么”输出质量不稳定温度设置过高分析与执行类降到 0.2写作类降到 0.5智能体使用错误工具工具描述模糊给工具加明确的前置条件和返回格式说明4.2 “协商僵局”及其解决办法多智能体实践中最有意思的问题协商僵局。两个智能体互相等待对方提供信息形成了死锁。有一次“检索智能体”等着“分析智能体”给出精确的检索关键词而“分析智能体”又说“没有数据我分析不了”。两边都在等消息队列卡死。排查时发现根因是任务拆解时出现循环依赖。解决方式是引入了一个“初始上下文”用户在启动任务时先把最粗略的背景信息注入给第一个智能体让它先动起来。后续迭代中再逐步精细化。这是从实践中得到的经验多智能体系统里每个智能体至少需要有一个“种子输入”才能启动不能指望完全靠协商解决所有前置依赖。4.3 上下文污染的隐蔽问题还有一个比较隐蔽的坑称为“上下文污染”。分析智能体处理完第一批竞品数据后它的记忆里包含了第一轮的信息。处理第二批数据时第一批残留信息可能会干扰判断导致分析结果出现张冠李戴。解决办法有两种我都验证过有效在消息中携带context_id每次任务开启新会话强制智能体“忘记”旧任务在 Prompt 中加入“忽略与本批次任务无关的历史记忆”的指令第一种效果更好更彻底。第二种有时候管用但偶尔失效属于概率性方案。4.4 监控与调试手段多智能体不好调试因为过程不可见。我建议在开发时开启“流程回放”模式。agency-agents支持记录每个智能体的输入输出快照可以完整复现决策链路。调试时从两个维度检查任务是否被正确拆解、消息是否被正确传递。约 80% 的问题出在这两层之间真正 LLM 推理错误的比例反而没那么高。5. 更进一步的扩展方向5.1 增加人工审核节点的混合流程纯自动化多智能体系统有风险尤其是面向用户输出的场景。我测试过一个增强方案在写作智能体和最终输出之间插入一个“审核智能体”但它不是做审核决定而是负责把结果整理成“审核清单”由人类做最终确认。这个“人在环上”的设计比完全自动可靠得多。5.2 横向扩展多个执行单元如果数据量增大比如要同时分析 20 个竞品而不是 1 个可以对执行智能体做横向扩展。多个检索智能体并行工作每个负责一批竞品分析完成后由汇总智能体合并结果。这个扩展并不复杂前提是所有智能体无状态化它们不保存任何跨任务的状态任务信息全部通过消息传递。无状态是水平扩展的前提。5.3 与外部业务系统的对接框架提供了 HTTP 回调接口可以把智能体过程的最终输出以 Webhook 形式发送到其他系统。我目前把它接到了企业微信机器人和内部 Wiki 上以下是核心对接逻辑import requests def send_to_webhook(payload): webhook_url https://your-app.example.com/api/agent-output requests.post(webhook_url, jsonpayload, timeout5)建议在对接层做两件事消息格式标准化和失败重试。多智能体输出格式偶尔会不规则在对接外部系统前最好经过一层严格的格式化校验和兜底重试机制。最后分享一条个人经验是我在多次尝试中踩坑换来的多智能体架构的价值不在于“用多个智能体看起来更高级”而在于它天然提供了隔离、分工和可观测性。如果你手上的任务链路短、依赖少单 Agent 可能更合适。一旦任务真正复杂起来——多步骤检索、多层分析、多角色协作agency-agents这套设计思路会让整个系统变得可控得多。我自己已经把它挂在日常的竞品追踪流程上跑了好几周稳定性和产出质量都超出预期。如果你也打算尝试多智能体架构我建议从最小的三角色流水线开始先把消息链路跑通再逐步加复杂度这个路径是最平滑的。