1. 从“agency-agents”这个标题说起它到底在解决什么问题第一次看到“agency-agents”这个标题很多人会愣一下这到底是个什么东西是某个开源库、一套架构模式还是一个产品名我最初的反应也是这样。拆开来看“agency”在软件语境里通常指向“代理能力”或“代理机构”这层含义而“agents”则是复数形式的“智能体”。把这两个词拼在一起它指向的核心领域其实非常明确——一套围绕多智能体协作、让智能体具备自主代理能力的系统设计。说白了这个标题背后要解决的是一个很现实的问题单个智能体能力再强遇到复杂任务也会力不从心。比如你要做一个完整的市场调研报告需要有人负责搜集资料、有人负责数据分析、有人负责撰写、有人负责审校这些环节如果全塞给一个智能体它很容易在长链路里“跑偏”或者“遗忘”。而 agency-agents 的思路就是把一个大任务拆给多个各司其职的智能体让它们像一个小型代理机构一样协同工作每个智能体有自己的角色、工具和职责边界。这套东西适合谁来参考我认为有三类人最值得看第一类是正在做 AI 应用开发、想把单点能力升级成工作流的工程师第二类是做自动化、RPA、流程编排的技术人员想看看智能体怎么替代传统脚本第三类是对多智能体系统好奇、想动手搭一个 demo 的爱好者。哪怕你之前没接触过智能体框架只要懂一点编程基础跟着思路走也能理解个七八成。我写这篇东西的出发点不是复述某个官方文档而是把这套“代理机构式”的多智能体设计思路从架构选型、角色划分、通信机制到落地踩坑完整地拆一遍。你看完之后应该能自己动手搭一个最小可用的多智能体协作系统而不是停留在“听起来很厉害”的层面。2. 整体架构设计为什么是“代理机构”而不是“单体智能”2.1 核心思路把任务拆成岗位而不是堆给一个人传统做法里我们习惯写一个大而全的智能体给它挂一堆工具然后指望它自己规划、自己调用、自己纠错。这种单体架构在简单任务上没问题但一旦任务链条变长问题就暴露了上下文窗口被塞爆、工具选择混乱、中间结果无法复用、出错后难以定位是哪一步崩的。agency-agents 的核心思路用一句话概括就是**“分岗定责”**。它把整个任务流程类比成一家代理机构有负责对接需求的客户经理有负责执行的专员有负责质检的审核员还有负责统筹的项目经理。每个“岗位”就是一个独立的智能体拥有独立的系统提示词、独立的工具集、独立的记忆空间。这样做的好处非常直接职责隔离写文案的智能体不需要知道数据库怎么连它只管把内容写好。上下文可控每个智能体只加载自己需要的信息不会因为全局上下文过长而“失忆”。可替换性强某个环节效果不好单独换掉那个智能体就行不影响整体。可观测性好每一步是谁做的、用了什么工具、产出了什么链路清晰。我个人的经验是当任务步骤超过 4 步、或者涉及 2 种以上不同性质的操作比如既要检索又要计算又要生成就应该考虑拆成多智能体而不是硬塞给一个。2.2 方案选型为什么不用“一个大模型加一堆 if-else”有人会问那我用一个大模型外面套一层 if-else 判断不也能实现流程控制吗能但那是“工作流”不是“智能体协作”。两者的本质区别在于决策权在谁手里。if-else 方案里流程是写死的模型只负责在固定节点做固定的事。而 agency-agents 里每个智能体可以根据当前情况自主决定下一步做什么、调用哪个工具、要不要把任务转交给别的智能体。这种自主性带来的灵活性是硬编码流程给不了的。当然代价是调试难度上升所以我在实际项目里通常采用混合模式主干流程用编排器控制局部环节给智能体自主权。这样既有可控性又保留了灵活性。选型时还要考虑通信方式。常见的有三种共享内存所有智能体读写同一块状态、消息传递智能体之间发消息、以及黑板模式把中间结果写到一个公共区域谁需要谁去取。agency-agents 这类系统我倾向于用共享状态加消息通知的组合状态集中管理便于排查消息通知保证实时性。2.3 影响范围这套设计能用在哪些场景多智能体协作不是玩具它的应用面比想象中广。我梳理了几个典型场景场景类型具体例子为什么适合多智能体内容生产调研报告、营销文案、技术文档检索、撰写、审校可分离数据处理数据清洗、分析、可视化各步骤工具差异大隔离更稳客户服务意图识别、知识检索、回复生成不同环节模型和知识库不同研发辅助需求拆解、代码生成、测试用例角色边界清晰便于质量把控运营自动化监控、告警、处置、复盘需要多角色接力链路长可以看到只要任务具备“多步骤、多技能、可分工”这三个特征多智能体架构就有发挥空间。反过来如果任务就是简单的一问一答那完全没必要上这套纯属给自己找麻烦。3. 核心细节解析角色、通信与状态管理3.1 角色定义每个智能体的“人设”怎么定角色定义是整个系统的地基。我见过太多项目失败在角色划分上——要么角色重叠导致互相抢活要么角色缺失导致任务卡住。一个好的角色定义应该包含四个要素职责描述、可用工具、输入输出约定、边界条件。以我搭过的一个内容生产系统为例角色是这样切的协调者Coordinator不直接干活只负责接收任务、拆解、分派、汇总。它的工具集里只有“任务管理”和“智能体调用”两类。检索员Researcher负责搜集资料工具是搜索接口和网页解析。它的输出必须是结构化的资料列表。撰写员Writer负责把资料组织成文章工具是文本生成。它不碰搜索只吃检索员的输出。审校员Reviewer负责检查事实错误和逻辑漏洞工具有事实核查和文本对比。它可以打回给撰写员重写。这里有个关键细节每个角色的系统提示词里必须明确写清楚“你不负责什么”。比如撰写员的提示词里要写“你不需要验证事实那是审校员的职责”。这句话看着多余但实测能大幅减少智能体越界行为。提示角色数量不是越多越好。我试过拆成 8 个角色结果协调开销比干活还大。一般 3 到 5 个角色是比较舒服的区间超过 6 个就要考虑合并了。3.2 通信机制智能体之间怎么“说话”智能体之间的通信本质上是结构化消息的传递。我强烈建议不要用自然语言裸传而是定义一套消息格式。原因很简单自然语言有歧义智能体 A 说“这个数据不太对”智能体 B 可能理解成“数据格式错”也可能理解成“数据值错”结果就是来回扯皮。我常用的消息结构是这样的{ from: researcher, to: writer, task_id: task-001, status: completed, payload: { content: ..., sources: [..., ...], confidence: 0.85 }, next_action: write_draft }字段不多但每个都有用。status让接收方知道上游是完成了还是失败了confidence让下游判断要不要复核next_action给出明确的下一步建议。这套格式我用了大半年最大的感受是排查问题快了很多出问题时直接看消息日志一眼就知道断在哪。通信模式上我推荐事件驱动加轮询兜底。正常情况下智能体完成工作后主动发消息通知下游但如果下游等太久没收到就主动去查状态。这样既避免了纯轮询的资源浪费又防止了消息丢失导致的死锁。3.3 状态管理中间结果存哪里、怎么存状态管理是最容易被忽视、但出问题最致命的一环。多智能体系统里状态分三类任务状态进行到哪一步了、数据状态中间产物是什么、会话状态对话历史。我的做法是分开存任务状态用轻量数据库或内存表字段包括任务 ID、当前阶段、负责智能体、开始时间、超时时间。数据状态用对象存储或文件系统大文本、大文件都放这里数据库里只存引用路径。会话状态按智能体隔离每个智能体有自己的历史记录不共享。为什么要隔离会话状态因为共享会导致“上下文污染”。检索员看到的搜索结果如果被写进撰写员的上下文撰写员可能会被无关信息干扰。隔离之后智能体之间只通过显式的消息传递交换必要信息干净很多。注意状态一定要有版本号或时间戳。我踩过一次坑两个智能体同时更新同一条状态后写的覆盖了先写的导致任务回退。加了乐观锁之后就没再出现过。4. 实操过程从零搭一个最小可用系统4.1 环境准备与依赖选择动手之前先把环境理清楚。我用的技术栈比较朴素不追求花哨编程语言Python 3.10 以上生态成熟调试方便。智能体框架可以用现成的多智能体框架也可以自己写调度逻辑。我建议第一版自己写理解更透彻。模型接口任意支持对话补全的模型接口都行关键是稳定和便宜因为多智能体调用次数是单体的好几倍。状态存储开发阶段用 SQLite 加本地文件就够了生产再换。消息队列小规模用内存队列规模大了再上专业消息中间件。安装依赖的时候有个小技巧把模型调用封装成统一接口不要在业务代码里直接调。这样以后换模型、加缓存、加重试都只改一个地方。class LLMClient: def __init__(self, model_name, api_base, api_key): self.model_name model_name self.api_base api_base self.api_key api_key self.cache {} def chat(self, messages, temperature0.7): cache_key str(messages) str(temperature) if cache_key in self.cache: return self.cache[cache_key] # 实际调用逻辑 response self._call_api(messages, temperature) self.cache[cache_key] response return response这个缓存看着简单但在调试阶段能省下大量重复调用的钱和时间。4.2 定义智能体基类与角色实例基类负责所有智能体共有的逻辑接收消息、调用模型、执行工具、发送消息。角色实例只定义差异部分提示词、工具集、处理逻辑。class BaseAgent: def __init__(self, name, system_prompt, tools, llm_client): self.name name self.system_prompt system_prompt self.tools tools self.llm llm_client self.history [] def handle(self, message): self.history.append(message) prompt self._build_prompt(message) response self.llm.chat(prompt) action self._parse_action(response) if action[type] tool: result self._run_tool(action[tool], action[args]) return self.handle({role: tool, content: result}) return self._format_output(response) def _build_prompt(self, message): return [ {role: system, content: self.system_prompt}, *self.history[-10:], {role: user, content: str(message)} ]这里有个细节值得说self.history[-10:]只保留最近 10 条。为什么因为多智能体系统里每个智能体的历史都会累积如果不截断上下文会越来越长成本和延迟都会飙升。10 条是我实测下来比较平衡的值既能保留足够上下文又不会太臃肿。定义具体角色时提示词要写得像“岗位说明书”researcher BaseAgent( nameresearcher, system_prompt你是检索员。你的职责是搜集与任务相关的资料。 你可以使用 search 工具。你不负责撰写和判断只负责提供原始资料。 输出格式必须是 JSON包含 content 和 sources 两个字段。 如果搜索无结果返回空列表不要编造。, tools[search], llm_clientllm )注意最后那句“不要编造”这是血泪教训。早期版本里检索员搜不到东西就开始瞎编下游全被带偏。加了这句之后编造率明显下降。4.3 编排器与任务流转实现编排器是整个系统的大脑负责接收用户任务、拆解、分派、监控、汇总。它的逻辑不复杂但细节很多。class Orchestrator: def __init__(self, agents): self.agents agents self.task_state {} def run(self, task): task_id self._create_task(task) plan self._plan(task) for step in plan: agent self.agents[step[agent]] result agent.handle({ task_id: task_id, instruction: step[instruction], context: self._get_context(task_id) }) self._save_result(task_id, step[agent], result) if not self._check_quality(result): self._retry_or_escalate(task_id, step) return self._aggregate(task_id)_plan方法可以用模型来做也可以用规则。我建议第一版用规则把常见任务的拆解逻辑写死稳定之后再换成模型规划。因为模型规划虽然灵活但不确定性太高调试阶段会让你怀疑人生。任务流转里有个关键设计每一步都要有超时和重试。我设的是单步超时 60 秒重试 2 次还失败就升级给协调者处理。没有这套机制一个环节卡住整个系统就僵住了。4.4 参数选择与性能调优多智能体系统的参数比单体多得多我挑几个最关键的讲。温度temperature不同角色应该用不同温度。检索员和审校员要准温度设 0.1 到 0.3撰写员要有点创造力设 0.7 到 0.9。我一开始所有角色都用 0.7结果检索员老是“发挥”搜出来的东西不靠谱。最大轮次max_turns单个智能体处理一个任务最多循环几次。设太小任务做不完设太大可能死循环。我的经验值是 5 到 8 轮超过还没完成基本就是提示词有问题。并发度没有依赖关系的智能体可以并行。比如检索员搜三个不同主题可以同时跑。但要注意模型接口的速率限制别把配额打爆。我一般设并发 3 到 5。上下文长度前面提过每个智能体保留最近 10 条。但如果任务特别复杂可以动态调整比如关键步骤保留 20 条普通步骤保留 5 条。调优的时候建议先固定其他参数一次只调一个不然你根本不知道是哪个参数起的作用。我吃过这个亏一次改了三个参数效果变好了但不知道为啥好下次换个任务又不行了。5. 常见问题与排查技巧实录5.1 智能体“踢皮球”怎么办这是多智能体系统最典型的问题A 把任务转给 BB 觉得不该自己管又转回 A来回循环。根本原因是职责边界模糊。排查方法打开消息日志看任务在哪些智能体之间来回跳。找到循环的那两个检查它们的提示词里职责描述是不是有重叠。解决办法是在提示词里加一句“如果任务不属于你的职责转交给 X且不要再次接收同类任务”。另外编排器要设一个转交次数上限超过就强制指定一个智能体处理。5.2 输出格式不稳定怎么治模型输出 JSON 偶尔会多几个字、少个括号导致解析失败。这个问题几乎每个做智能体的人都遇到过。我的处理是三层防护第一层提示词里明确要求“只输出 JSON不要任何解释文字”第二层解析时用容错解析器能自动补全常见错误第三层解析失败就重试重试时把错误信息一起发给模型让它修正。三层下来格式问题基本能压到 1% 以下。def safe_parse_json(text): try: return json.loads(text) except json.JSONDecodeError: # 尝试提取 JSON 片段 match re.search(r\{.*\}, text, re.DOTALL) if match: try: return json.loads(match.group()) except: pass return None5.3 成本失控的排查与优化多智能体调用次数多成本容易失控。我有一次跑了个任务账单出来吓了一跳。后来排查发现两个问题一是缓存没生效同样的查询重复调用二是某个智能体陷入重试循环一直调模型。优化手段加缓存、设重试上限、监控调用量。我在 LLMClient 里加了缓存在编排器里设了全局调用上限比如单任务最多 50 次模型调用超过就告警。另外把简单任务路由给小模型复杂任务才用大模型成本能降一半以上。5.4 常见问题速查表问题现象可能原因排查方向解决手段任务卡住不动某智能体超时未返回看任务状态表加超时和重试智能体互相转交职责边界模糊看消息日志明确职责加转交上限输出格式错乱提示词约束不够看原始输出三层防护加容错解析成本异常高缓存失效或重试循环看调用统计加缓存设上限结果质量差角色划分不合理看各环节产出重新划分角色上下文污染状态未隔离看各智能体历史隔离会话状态提示排查问题时先看日志再看代码。多智能体系统的日志就是你的眼睛没有日志等于闭眼开车。我建议从第一天就把日志做全消息收发、工具调用、模型请求都记下来。6. 我踩过的坑与实操心得6.1 不要一上来就追求“全自动”我最初的想法很美好给个任务系统全自动跑完。结果发现全自动意味着任何环节出错都没人兜底一个小问题就能让整个任务崩掉。后来我改成半自动模式关键节点人工确认普通节点自动流转。这样既保留了效率又有了可控性。等系统稳定运行一段时间、你对它的行为有把握了再逐步放开自动化程度。6.2 提示词要“说人话”别堆术语写智能体提示词的时候很多人喜欢堆专业术语觉得这样显得高级。实际上模型更吃“说人话”的提示词。比如“请对输入进行语义解析并提取实体”就不如“把这段话里的人名、地名、时间找出来”效果好。我现在的提示词都写得像给新员工交代工作直白、具体、有例子。6.3 小步快跑别憋大招多智能体系统复杂度高想一次设计完美再动手基本不可能。我的做法是先跑通两个智能体的协作确认通信、状态、编排都没问题再逐步加角色。每加一个角色就测一轮确保不破坏已有功能。这样虽然看起来慢但总体比推倒重来快得多。6.4 留好“人工接管”的入口再智能的系统也有搞不定的时候。我在编排器里留了一个人工接管接口任务卡住或者质量不达标时可以一键转人工。这个接口平时用不上但关键时刻能救命。而且人工处理的结果可以反哺系统作为后续优化的样本。6.5 监控比功能更重要功能是给别人看的监控是给自己用的。我现在的系统里监控面板比功能界面还大。实时看任务队列、各智能体状态、调用量、成功率、平均耗时。这些数据不仅能帮你发现问题还能帮你做容量规划。没有监控的多智能体系统就是一颗定时炸弹。7. 后续可以怎么扩展这套 agency-agents 的架构跑通之后扩展方向其实很多。我列几个我试过或者正在试的角色动态生成现在角色是写死的未来可以根据任务类型动态生成角色。比如遇到法律类任务自动生成一个“法务专员”角色。这需要一套角色模板库和匹配逻辑。智能体学习能力让智能体从历史任务里学习把成功的处理模式沉淀下来。最简单的做法是把高质量的历史输出作为少样本示例塞进提示词里。跨系统集成把多智能体系统接到现有的业务系统上比如工单系统、CRM、数据平台。这样智能体就不只是“聊天”而是真正能干活。性能优化随着角色增多编排开销会变大。可以考虑把编排逻辑也做成智能体让“协调者”自己决定怎么调度而不是写死流程。我个人最看好的方向是垂直领域的深度定制。通用多智能体系统竞争激烈但在某个具体行业里把角色、工具、知识库都做深价值会大很多。比如专门做电商客服的多智能体、专门做代码审查的多智能体这类系统落地效果往往比通用系统好得多。最后分享一个小技巧每次系统升级后用同一批测试任务跑一遍回归对比升级前后的输出。这样能快速发现升级带来的退化。我建了一个包含 20 个典型任务的测试集每次改动都跑一遍省了很多事。
