多Agent协同实战教程:选型、搭建与评测

作者:da吃一鲸8862026.11.18 11:18浏览量:0

简介:本教程面向准备落地多 Agent 协同的开发者、架构师与技术负责人,系统讲清"该不该上多 Agent"的判断依据,并给出任务拆解、角色契约、通信与共享记忆、编排调度、结果聚合、埋点评测的完整实现路径,附带通用伪代码、验证清单与排查思路,帮助你用可量化的对照实验回答"多加 Agent 是否真的让系统变好"。

一、教程目标:读完这篇你能完成什么

很多团队在做 Agent 系统选型时,是凭直觉或惯例”拍板”的:感觉任务复杂,就默认拆成多个 Agent;感觉不稳,就再加一个”评审 Agent”。但多加一个 Agent 并不总能让系统变好——它同时带来了专业化收益的上升和协调成本的上升,两者哪一边更大,取决于任务本身的结构。

本教程要带你完成的不是”如何堆 Agent”,而是一条可验证的完整链路:

  1. 判断当前任务是否值得从单 Agent 升级为多 Agent,并给出可判定的信号清单;
  2. 设计 Agent 的任务分解与拓扑结构,为每个角色写清”角色契约”;
  3. 实现结构化通信、共享状态、编排调度与失败降级;
  4. 建立埋点与对照评测,用数据证明多 Agent 带来的收益是否覆盖其成本;
  5. 在效果不佳或成本失控时,知道从哪一层开始排查和优化。

agent-">二、先建立正确的选型观:多 Agent 到底在换什么

在动手之前,必须先理解多 Agent 的本质:它是用协调成本换取专业化收益的一种架构选择。收益侧主要来自四个方面:

  • 任务分解:把一个大目标拆成若干可独立求解的小目标,降低单次推理难度;
  • 角色专门化:不同 Agent 拥有不同的系统提示词、不同的工具白名单、不同的知识边界,比一个”什么都会一点”的 Agent 更专注;
  • 并行与隔离:无依赖的子任务可并行执行;长文档、多数据源的信息可分别装入不同 Agent 的上下文,避免单个上下文被打爆;
  • 交叉校验:由独立 Agent 对结果做评审或对抗性检验,能捕获生成者自己难以发现的错误。

成本侧则包括:Token 与调用费用的非线性增长、端到端延迟上升、信息在多跳传递中的失真、责任扩散(出问题时难以定位是哪个 Agent 的错)、错误传播(上游一个小偏差被下游放大)、以及调度与状态管理的工程复杂度。

因此,是否上多 Agent,可以用下面这组信号来判定。

倾向多 Agent 的正向信号:

  • 任务可分解为低耦合子任务,子任务之间接口清晰、交互次数少;
  • 子任务所需的工具、数据格式、专业技能差异明显(例如”检索类”与”计算类”与”格式转换类”);
  • 存在天然的并行结构,可以同时处理多个互不依赖的分支;
  • 单任务需要处理的上下文量已接近或超过模型上下文窗口的舒适区;
  • 业务本身要求交叉校验或多方意见(如方案评审、争议裁决、复杂代码审查)。

倾向单 Agent 的反向信号:

  • 任务目标单一,主要工作是”调用几个工具再总结”;
  • 对响应延迟敏感,用户在线等待;
  • 成本敏感且任务调用量大;
  • 出错代价低、可容忍人工兜底;
  • 子任务之间需要频繁来回确认——这类”强耦合”任务拆开后,协调开销往往吃掉全部收益。

一个容易被忽略的前提信号:你是否有一套评测集。 如果没有 20 条以上、带明确评分标准(标准答案、断言规则或人工评分表)的代表性样例,就贸然上多 Agent,你事后将无法判断效果变化来自架构调整还是随机波动。评测集应当作为选型的前置条件,而不是事后的补救。

三、前置准备

3.1 基础知识与能力

  • 提示词工程基础,尤其是结构化输出约束(要求模型按固定 JSON 结构返回,而非自由文本);
  • 大模型的工具调用(函数调用)机制与使用方式;
  • 基本的并发/异步编程,理解并行调用的超时与异常处理;
  • 基本的可观测性概念:日志、链路追踪、指标、告警。

3.2 数据与评测资产

  • 一份评测集:覆盖典型场景、边界场景与已知失败场景,每条包含输入、期望输出或判定规则;
  • 一份任务契约草案:最终交付物长什么样(字段、类型、必填项、枚举取值);
  • 一份基线记录:当前单 Agent 版本在同一评测集上的成功率、平均调用次数、平均耗时、平均成本。

没有基线,后续所有”是否变好”的讨论都只是主观感受。

3.3 环境与依赖(按通用能力类目准备)

  • 运行时:可部署无状态服务的容器平台或普通应用服务器;
  • 消息队列:用于 Agent 之间的异步协作与削峰;
  • 对象存储:存放中间产物、大文件、历史会话快照;
  • 数据库:存放任务状态、评测记录、审计日志;
  • 日志服务 + 监控告警:采集每次调用的输入输出、耗时与 Token 消耗;
  • 身份认证与密钥管理:模型密钥、工具凭证必须走环境变量或密钥管理服务,禁止硬编码进代码仓库。

在百度智能云等云平台的通用产品体系中,上述能力分别对应容器平台、消息队列、对象存储、日志服务、监控告警与身份认证等标准类目,可按自身账号与权限体系接入。

四、实施步骤

步骤一:先定义输出契约,再拆角色

做什么:把”最终要交付什么”写成一份可机器校验的契约,例如 JSON 的字段结构、必填项、枚举范围。

为什么:角色是从契约反推出来的,而不是凭空想象出来的。先定契约能保证每个 Agent 的输出都有明确的验收标准,也便于后续用确定性代码做校验,而不是再让另一个模型去”感觉一下对不对”。

注意:契约中的每个字段都要说明”由哪个角色负责产出”和”由谁校验”。存在争议的必填字段,往往就是需要拆分角色的地方。

  1. {
  2. "task_id": "string",
  3. "conclusion": { "summary": "string", "evidence_refs": ["string"] },
  4. "risks": [ { "level": "high|medium|low", "desc": "string" } ],
  5. "actions": [ { "step": "string", "owner": "string" } ],
  6. "confidence": "number(0-1)"
  7. }

步骤二:拆解任务并选定 Agent 拓扑

常见的三种拓扑,按可控性从高到低排列:

  • 流水线型(Sequential):A → B → C 顺序流转。适合子任务有明确先后依赖的场景,如”检索 → 分析 → 成稿”。优点是可预测、易调试;缺点是无并行收益。
  • 并行聚合型(Fan-out / Fan-in):一个调度者把任务分发给多个同构 Worker,收集后统一聚合。适合可切分的批处理、多来源调研、多方案并行生成。这是收益最容易兑现的一类。
  • 主管—下属型(Supervisor):由一个主管 Agent 决定下一步交给谁。灵活但可控性最差,容易出现路由错误与轮次膨胀。建议将”可枚举的分支”改为规则或固定编排决定,只把真正模糊的决策留给模型。

建议做法:画出任务流程图,在每个节点上标注”输入是什么、输出是什么、失败怎么办”。如果两个相邻节点的输入输出高度重叠,说明拆得太碎;如果需要来回三次以上才能收敛,说明拆错了边界。

步骤三:为每个 Agent 写”角色契约”

每个 Agent 的提示词应至少包含五要素,缺一项就会出现行为漂移:

  1. 目标:一句话说清这个 Agent 唯一要达成的结果;
  2. 输入:能收到哪些字段、哪些来自上游、哪些来自检索;
  3. 输出:严格遵循步骤一的契约片段,不允许自由发挥;
  4. 边界:明确”不做什么”——不修改上游结论、不臆造数据、不调用未授权的工具;
  5. 终止条件:什么情况下必须交回结果,什么情况下必须上报异常。

反模式是给所有 Agent 共用一份”万能提示词”。角色一旦不区分,多 Agent 就退化为”同一个 Agent 调用多次”,只会增加成本而不会增加收益。

步骤四:实现通信与共享记忆

通信必须结构化。 自由文本传递是多跳失真的主要来源。建议统一消息信封:

  1. Message {
  2. msg_id, trace_id, // 全链路追踪
  3. from, to, // 角色标识
  4. type, // 任务分派 / 结果 / 追问 / 异常
  5. payload, // 严格符合契约
  6. attempt, deadline, // 重试次数与超时
  7. parent_msg_id // 关联上游,便于回溯
  8. }

共享状态集中管理。 维护一个只由编排层写入的工作区对象,包含原始输入、各角色产出、当前阶段、已消费预算。避免让各 Agent 直接读写一个”全局黑板”——那会导致并发写入冲突与不可复现的状态。

上下文要有节制。 长任务采用”滚动摘要 + 关键信息锚点”:历史轮次压缩为摘要,关键数据(原文引用、编号、数值)以锚点形式保留。切勿把完整历史无脑透传给每个 Agent,这既是成本黑洞,也会稀释关键指令的注意力。

步骤五:编排调度与失败处理

做什么:实现调度器,负责路由、并发控制、重试、超时、熔断与降级。必须包含以下护栏:

  • 最大轮次上限:防止 Agent 互相推诿或循环往复;
  • Token / 成本预算上限:按任务粒度设定,超限时强制收敛并产出部分结果;
  • 超时与重试:重试采用指数退避,并保证操作幂等(同一 msg_id 重复处理不产生副作用);
  • 降级链路:当多 Agent 流程连续失败或超预算时,自动降级为”单 Agent + 工具”直接求解,保证可用性;
  • 人工介入点:涉及不可逆或高风险动作时,必须暂停等待确认。

注意:降级链路不是可选项。它既是稳定性保障,也是你最诚实的对照实验组——如果生产环境中大部分任务最终都走了降级路径,说明多 Agent 编排在多数场景下并未带来净收益。

步骤六:结果聚合与冲突消解

聚合策略按任务性质选择:

  • 多数表决:多个同构 Agent 独立求解同一问题,取一致结果,适合有明确答案的判定类任务;
  • 置信度加权:按各 Agent 自评估算或历史准确率加权,适合能力不对等的角色组合;
  • 结构化合并:不同 Agent 负责不同字段,直接按契约拼装,适合流水线型;
  • 优先级规则:把”可被确定性校验的结论”置于最高优先级,校验不通过的结论一律不采纳。

关键原则:最终一致性校验应由确定性代码完成,而不是由模型完成。 例如数值求和、日期先后、必填项完整性、引用是否真实存在——这些用代码校验既准确又零成本。评审型 Agent 适合发现”代码难以判断”的问题(逻辑漏洞、遗漏风险、表述歧义),且应强制它给出证据引用;无法给出引用的意见判为无效,不进入聚合。这样可以显著抑制评审 Agent 的”幻觉式挑错”。

步骤七:埋点与可观测性(贯穿全程,不可后补)

每次模型调用都要记录:trace_id、角色名、提示词版本号、输入摘要、输出摘要、Token 输入/输出量、耗时、重试次数、错误码。指标分三类:

  • 任务指标:成功率、正确率、契约校验通过率;
  • 过程指标:平均轮次、返工率、工具调用失败率、人工介入率;
  • 经济指标:单任务 Token 消耗、单任务成本、P50/P95 端到端延迟。

步骤八:对照实验,用数据回答”是否该加 Agent”

这是本教程的核心环节。设计要点:

  1. 单一变量:除 Agent 数量/拓扑外,模型、温度、提示词质量、工具集、预算上限全部保持一致;
  2. 同一评测集:包含简单、中等、困难三档样例,避免只测简单样例得出乐观结论;
  3. 重复采样:大模型输出具有随机性,同一配置至少重复 3~5 次取均值与方差,单次结果不具备说服力;
  4. 预先设定判定阈值:例如”正确率提升幅度需超过预设的最小可感知差值,同时单任务成本增幅不超过预算容忍区间”,阈值必须在实验前写死,避免事后挑选对自己有利的指标;
  5. 同时报告方差:如果多 Agent 版本的方差显著更大,即使均值略高,对生产环境的可运维性也是负面信号。

实验结论只有三种:值得上、不值得上、只在部分任务类型上值得。第三种最常见,也是最应被接受的结果——按任务类型分流,简单任务走单 Agent,复杂任务走多 Agent,通常比全局一刀切更优。

五、通用伪代码示例(主管 + 两个 Worker + 降级)

  1. # 说明:以下为结构示意,不含任何具体平台命令或专有接口
  2. BUDGET = {"max_rounds": 6, "max_tokens": 60000, "deadline_s": 120}
  3. def run_task(raw_input):
  4. ws = Workspace(input=raw_input, trace_id=new_id(), cost=0, history=[])
  5. plan = planner_agent.plan(ws) # 输出必须校验为 DAG 结构
  6. if not validate_dag(plan):
  7. return fallback_single_agent(ws) # 规划失败直接降级
  8. for round_i in range(BUDGET["max_rounds"]):
  9. if ws.cost.tokens > BUDGET["max_tokens"]:
  10. break
  11. batch = [n for n in plan.ready_nodes() if n.kind in PARALLEL_KINDS]
  12. results = parallel_map(execute_node, batch, timeout_s=30)
  13. for node, res in zip(batch, results):
  14. if res.error:
  15. res = retry_with_backoff(execute_node, node, attempts=2)
  16. if res.error:
  17. continue # 单节点失败不阻塞全局
  18. ws.commit(node, res) # 仅编排层可写状态
  19. if plan.is_complete(ws):
  20. break
  21. draft = aggregate(ws) # 按契约字段合并
  22. verdict = code_level_validate(draft) # 确定性校验优先
  23. if verdict.failed:
  24. draft = critic_agent.review(ws, draft, must_cite_evidence=True)
  25. draft = aggregate_after_fix(ws, draft)
  26. if still_broken(draft) or human_gate_required(draft):
  27. return fallback_single_agent(ws) # 兜底路径,保证有结果返回
  28. persist(ws) # 中间产物落对象存储,便于复盘
  29. return draft

这段伪代码刻意体现了三个设计取向:编排以固定 DAG 为主、模型决策为辅;单点失败不拖垮整体;任何情况下都有确定性兜底路径。

六、结果验证清单

分层验证,逐层排除问题来源:

  1. 单 Agent 独立评测:每个角色单独跑一遍评测集,确认它在隔离状态下能达到可用水平。这一步非常关键——如果某个角色单独都做不好,协作不可能挽救它。
  2. 契约校验:检查所有 Agent 输出的 JSON 是否 100% 符合契约,字段缺失与类型错误必须为零容忍。
  3. 两两协作验证:验证相邻角色的接口对齐,尤其是字段语义理解是否一致。
  4. 全链路跑通:完整跑完评测集,记录成功率、轮次、成本、延迟。
  5. 异常注入:人为让某个工具超时或返回空,验证重试、降级、预算超限路径是否按预期触发。
  6. 线上灰度:小流量上线,或采用影子模式(新链路只计算不生效,与旧链路结果对比),观察至少一个完整业务周期。
  7. 回归机制:把每次线上问题转化为新评测样例,防止修复 A 破坏 B。

判定成功的标准应当是复合的:任务正确率达到预设阈值、契约校验通过率接近全通过、P95 延迟在可接受范围、单任务成本在预算内、方差未显著恶化。任何一项不达标,都不应认定为”多 Agent 改造成功”。

七、常见问题与排查思路

现象 常见原因 排查方向
多 Agent 效果不如单 Agent 角色边界模糊导致重复劳动;上游误差被下游放大;聚合策略过于宽松 逐个 Agent 单独评测;对比各版本在困难样例上的差异;收紧契约与聚合规则
Token 成本成倍增长 全量历史透传;每个 Agent 重复读同一批文档;无预算护栏 引入滚动摘要;检索结果共享一次而非各自重查;设置 Token 预算上限
无限循环或互相推诿 缺最大轮次与终止条件;失败没有出口 强制轮次上限;失败节点直接跳过或降级
同一输入输出差异大 温度设置过高;并行结果聚合顺序不确定;消息拼接顺序变化 固定温度;对聚合输入做稳定排序;缓存确定性中间结果
评审 Agent 频繁误报 未要求证据引用;评审标准与生成标准冲突 强制引用证据,无引用即判无效;统一评审清单
主管 Agent 路由错误 分支过多且描述重叠,全部交给模型判断 改为规则/固定编排;仅保留真正模糊的分支给模型
延迟高、用户等待久 串行依赖过多;未使用流式返回 尽可能并行;先返回阶段性结果
问题无法复现 未记录提示词版本与中间产物 版本化提示词;中间产物落对象存储并关联 trace_id
密钥被误提交或泄露 硬编码在配置或代码中 迁移到密钥管理服务;开启仓库扫描;立即轮换泄露凭证

八、优化建议

  • 成本:分层使用模型,路由、分类、格式转换等轻任务交给小模型,复杂推理才用大模型;对高频重复查询做结果缓存;对长上下文做压缩。
  • 性能:无依赖分支强制并行;接口设计为可流式返回;调度器限制并发度以保护下游配额。
  • 稳定性:保留降级链路并定期演练;重试必须幂等;对下游依赖设置熔断与超时;把”部分结果 + 明确缺失说明”作为可接受的返回形态,优于整体失败。
  • 可维护性:建立 Agent 注册表,记录每个角色的职责、提示词版本、负责人、评测得分;提示词纳入版本管理并评审;建立契约测试;新角色先影子运行再放量。
  • 安全:工具按角色做最小权限白名单;对外部输入执行提示注入防护(把外部内容一律视为数据而非指令,并在提示词中显式声明该边界);输出侧做敏感信息脱敏;保留完整审计日志。
  • 架构演进:从单 Agent 起步,先积累评测集与埋点;当出现明确的分解信号与可验证的收益时再演进;演进后若对照实验显示净收益为负,果断回退。可回退性是多 Agent 架构设计的一项硬指标。

九、总结

多 Agent 协同的实现难点,从来不是”怎么创建更多 Agent”,而是三件事:把任务边界划对、把契约与校验定死、把收益用数据证出来。

回顾关键步骤:先用信号清单判断是否需要多 Agent,并以评测集作为前置条件;再定义输出契约、反推角色、选定拓扑;然后实现结构化通信、集中式状态、带护栏的调度与确定性兜底;最后通过单变量对照实验,把正确率、轮次、延迟、成本的增减摆在同一张表上,交由数据决定架构。

后续可继续深入的方向包括:多 Agent 任务的自动任务分解与拓扑搜索、角色能力的自动化评测与迭代、成本与质量之间的帕累托前沿刻画,以及多 Agent 系统在长周期运行下的记忆管理与知识沉淀。但无论技术如何演进,那条原则不变:每一次增加 Agent,都应当有可度量的理由。