拓冰网站定制 
广州站这场沙龙是我今年以来参加过“信息密度”最高的一场 Agent 技术活动。坦白说早两年听 Agent 相关的分享总有一种“Demo 很惊艳、落地很遥远”的悬空感但这次完全不一样——从多 Agent 协作的框架选型到生产环境里的状态管理、可观测性、权限隔离再到现场直接跑通的工程链路几乎每个议题都在回答同一个问题Agent 到底要怎么做才能从一个“会聊天的原型”变成一个敢让业务数据流经过它的系统。这篇文章算是我的现场笔记加会后复盘。我没有按嘉宾演讲顺序平铺直叙而是把当天反复出现的几条主线拎出来多 Agent 协作的模式与边界、生产级工程实践里的关键环节、现场演示的代码还原过程以及我个人踩坑后总结的排查清单。如果你正准备把一个 AI Agent 项目推向线上或者想了解多 Agent 架构该怎么选型这篇文章应该能让你少走不少弯路。1. 现场氛围与主题主线从“能跑”到“敢跑”1.1 这两年最大的变化大家开始聊“失败率”和“成本”了现场有个细节让我印象很深好几场分享的开头都没有放炫酷的对话录屏而是直接贴了一张线上环境的监控大盘。上面有请求量、Token 消耗、工具调用成功率、Agent 单次任务平均步数、重试分布。放在两年前这类指标在 Agent 分享里几乎看不到——那时候大家更愿意展示“它多聪明”而不是“它多可控”。这说明 Agent 开发这件事正在经历一次比较明显的范式转移早期阶段大家关注的是“大模型能不能理解我的指令”于是 Prompt 工程、思维链、ReAct 循环成了主角到了现在这个阶段模型能力已经不是最大瓶颈反而是工程问题——多个 Agent 之间怎么协作、任务状态放在哪里、工具调用失败后怎么恢复、用户隐私和权限边界怎么划——这些以往容易被忽略的部分变成了决定项目能不能上线的关键。这次广州站的议程也明显围绕这条主线展开。多 Agent 协作不是单纯讲“怎么让两个 Agent 对话”而是给出了可落地的架构模式谁是决策者、谁是执行者、消息走什么协议、并发怎么控制、单个任务卡住时怎么处理。生产级工程实践也不是喊口号而是细化到状态存储选型、可观测性埋点、评估集建设这些非常具体的事项。1.2 适合哪些人参考如果你是下面这几类人这篇回顾的参考价值会比较高已经在用 LangChain、LlamaIndex 或自己封装的大模型接口做原型验证正准备往生产环境迁移的开发者负责企业级 AI 平台、Agent 编排层、RAG 系统架构的技术负责人刚接触 Agent 开发想了解多 Agent 协作和传统分布式系统之间异同的后端工程师对开源项目选型感兴趣想知道哪些模块适合自研、哪些模块该拥抱社区方案的产品技术人员。我个人建议带着两个问题去读第一多 Agent 架构里的“多”到底是为了解决什么问题还是为了追热点第二生产级实践里有哪些环节是模型能力无法替代的。想清楚这两个问题很多技术选型你就不会纠结了。2. 多 Agent 协作的架构拆解模式、边界与适用场景2.1 单 Agent 不够用先搞清楚缺的到底是什么活动现场聊到一个很高的频次问题业务还没跑通是否有必要直接上多 Agent我听到的比较一致的回答是不要为了“多”而“多”。单 Agent 无法满足业务需求通常不是模型能力不够而是职责太杂导致 Prompt 失控。举个例子一个客服机器人如果既要负责意图识别、又要查订单、又要处理售后安抚、又要生成工单那你塞给它的指令会变得极其复杂。每个工具的调用说明、每次回复的语气要求、每类异常的处理方式全部堆在一个上下文窗口里模型被互相矛盾的指令干扰的概率会急剧上升输出的稳定性自然就差。多 Agent 架构的核心价值是把“一个大而全的智能体”拆成“多个小而专的智能体”每个 Agent 只负责一个边界清晰的子任务。这种拆分能带来三个直接好处Prompt 长度显著降低模型注意力更集中指令遵循率会提升单个 Agent 的工具集更小被误调用的概率下降可以针对不同 Agent 配置不同的模型便宜的模型处理分类任务更强的模型处理复杂推理成本控制更灵活。但请注意多 Agent 也意味着更高的消息传递开销、更复杂的失败链路和更难排查的问题。这是一个典型的“用工程复杂度换业务可控性”的取舍不是免费的午餐。2.2 三种主流协作模式Supervisor、Pipeline 与 Debate现场把当前常见的多 Agent 协作模式归纳成了三类我用比较通俗的方式复述一下。第一种是 Supervisor监督者/主从模式。这种模式下有一个“老板”角色负责拆解任务、调用下游的 Worker Agent、收集结果、判断是否需要返工。Worker 之间一般不做横向通信所有交互都要经过 Supervisor。它最像传统企业里的项目经理角色。这种模式适合什么场景任务边界清晰、可以自上而下拆分的场景比如“我要写一份行业分析报告”Supervisor 可以先拆出信息检索、数据分析、图表生成、文字润色几个环节然后按依赖顺序派发。它的优势是流程可控、每个子任务的产出可以被单独验证非常适合流程型任务。第二种是 Pipeline流水线模式。这个更好理解就是任务严格按阶段流动前一个 Agent 的输出是后一个 Agent 的输入。它适合处理有强依赖关系的阶段化工作流比如“客户咨询工单处理”先由分类 Agent 判断工单类型再由质检 Agent 核查合规风险最后由回复 Agent 拟稿每一步的输出不回头。需要提醒的是Pipeline 模式最怕中间环节出错。如果上游 Agent 输出了一个结构不完整的结果下游 Agent 很容易“顺着错误的格式继续编下去”。所以在流水线模式的每个阶段之间加一层结构校验输出必须符合 JSON Schema 或必须包含指定字段是现场工程分享里反复强调的实践。第三种是 Debate辩论/评审模式。多个 Agent 拿到同一个任务后分别产出结果再由一个评审 Agent 或规则引擎挑选最优解。这种模式适合开放性较强、没有唯一标准答案的任务比如代码审查、文案方案选优。它的缺点是成本会翻倍因为同一任务被好几个 Agent 各执行了一遍。生产环境里要做取舍不是所有主流程都值得用。我在项目里常用的是“Supervisor Pipeline 混合”主流程用 Pipeline 保证顺序稳定关键决策节点插入 Supervisor 做动态路由这样可以兼顾流程可控和灵活决策。沙龙上也有一位讲师给出了类似的观点他称之为“主流程确定化决策节点智能化”这个思路非常值得借鉴。2.3 多 Agent 协作的工程红线别让“协作”变成“混乱”现场有一个观点我听得很认同多 Agent 架构里的通信协议和数据格式是最容易被低估的部分。很多人一开始只定义“每个 Agent 的 Prompt”却忘了定义“Agent 和 Agent 之间传什么、传成什么样、传不过去怎么办”。如果你决定上多 Agent下面这几个问题必须在设计阶段明确回答消息协议长什么样是纯 JSON 还是结构化对象字段怎么命名有没有版本号上下文怎么共享全部塞进同一个上下文窗口还是通过外部存储按需读取结果怎么校验下游 Agent 如何判断上游给的结果是“可用的”而不是“模型幻觉产生的”失败如何传递某个 Agent 任务失败了是重试、降级还是终止并通知用户是否允许回环Agent 之间互相调用来调用去会不会出现死循环现场有人提出了一个很形象的比喻多 Agent 协作本质上是一个“分布式系统”只是每个节点不是普通服务而是带着不可预测性的模型实例。既然是分布式系统那分布式领域里那些“臭名昭著”的问题——状态不一致、消息丢失、死循环、超时无响应——一个都不会少甚至会被模型的随机性放大。关于协作边界我自己的体会是尽量让 Agent 之间的交互呈现“树状”不要出现“网状”。树状结构可以让你很清楚地知道“当前这个结果是由哪条路径产生的”出了问题能隔离、能回溯。网状结构听起来很智能但每次任务都有几十种可能的路径组合一旦出错排查看不到头。3. 生产级工程实践决定 Agent 能不能上线的关键环节3.1 状态管理Agent 不是无状态的接口而是有状态的任务流这是当天讨论最热烈的话题之一。很多从原型过渡到生产的团队第一次翻车往往不是在模型响应质量上而是状态管理没做好。过去我们写传统后端接口习惯“无状态设计”——请求进来、处理完、返回结果服务本身不保存任何状态。但 Agent 任务是典型的“长时运行、多步决策”流程一个任务可能包含“检索资料 → 生成草稿 → 调用内部 API 核对数据 → 修改输出 → 提交审核”五个环节这个过程可能要持续几分钟甚至更久。在这几分钟里如果服务重启了、Pod 被重新调度了、网络闪断了任务状态还在吗如果用户关掉了页面后台任务是否需要继续跑如果 Agent 在第五步失败是回到第四步还是从头再来这些问题的答案统统指向一个基础设施组件任务状态的持久化存储。现场的建议比较一致不要自己用内存里的全局变量硬扛要看你们团队的运维习惯选一个成熟方案。最常见的是把状态放进 Redis通过键存储任务 ID每个节点的状态快照用 Hash 数据结构存复杂任务则放进关系型数据库单表存储的多列、JSON 字段、创建时间、更新时间、每一步的输入输出有迹可循分布式场景下可以再用消息队列解耦。我自己的项目痛定思痛后的选择是把“主流程状态”放进了 PostgreSQL。原因很简单它的行级锁和事务能力可以帮我处理很多并发一致性问题而且我习惯性地把每一次工具调用的入参和出参都存进去。这样就算 Agent 最终给了一个错误答案我还能把历史回溯出来看看是哪一步开始错的。但是注意并不是把状态存数据库就万事大吉了真正复杂的是“恢复策略”。一个中断的任务恢复时是从 Agent 的“最后一步”续跑还是把整个 Agent 会话重新构建一遍这里没有标准答案完全取决于你每个步骤是不是幂等的。如果你的步骤被设计成“调用一次和调用一百次效果一样”的幂等操作那重放就是安全的如果某些步骤会产生副作用比如已经扣了款、已经发了短信那你就需要给每个步骤定义清晰的“幂等键”用来判断这个动作之前是否已经执行过。3.2 可观测性与评估体系没有度量就没有优化现场有一位做平台工程的嘉宾分享了一组数据让我触动很深他们团队在半年内迭代了几十个 Agent 版本但真正推动版本迭代的并不是“更多人提出新需求”而是“基线评估集”里的回归测试暴露的问题。换句话说Agent 能力的提升本质上靠的是一套能自动运行、能自动比对结果的评估流水线。我把这套思路拆成两层一层是“过程可观测”另一层是“结果可评估”。过程可观测指的是每一轮 Agent 运行时的完整轨迹都可追踪。大模型输出的都是 Token如果运行过程没有系统化地记录下来出了问题你根本无法判断是“用户意图理解错了”“检索召回的内容不对”“工具参数构造有误”还是“模型在最后一步撒谎了”。目前比较流行的做法是在 Agent 框架的关键节点加上分布式追踪埋点每轮循环记录下输入消息、当前使用的 Agent 角色、调用了哪个工具、工具传参是什么、工具返回是什么、模型原始输出完整内容、最终定向用户的那条消息内容。这些日志不仅用于排查更深层的价值是构建你的“案例库”——每一次线上真实运行的成功或失败案例都可以沉淀下来成为后续评估集的素材。结果可评估则是建一套“测评问题集 自动判定”的体系。这听起来是在做“测试”但和传统测试的区别是Agent 的输出是开放的你没法用断言直接比对字符串。现在的通用做法是引入“裁判模型”用另一个大模型来给 Agent 的输出质量打分或者按规则检查“是否包含核心要素”。做法可以是准备 3 类测试数据覆盖主流程的正确路径、容易出错的边界输入、不该放行的风险输入用离线任务批量跑 Agent输出结果存文件用“带评分规则的裁判模型”批量给结果打分同时把低分案例人工复核每次 Prompt 或 Agent 代码有变动就跑一遍全量回归分数对比低于基线就不允许合并。评估集听起来很“重”但它是把 Agent 从“玄学”变成“工程”的必经之路。没有评估集你就没法回答一个最基本的问题“你这次改动到底是变好了还是变差了”。3.3 权限、安全与合规Agent 越强大边界越要清晰把 Agent 接到生产业务上权限模型注定是绕不开的硬骨头。如果说传统 API 的权限控制是“一个用户调用一个接口”那么 Agent 场景的权限控制就是“一个任务通过一组可能变化路径的工具调用按钮完成”。比如一个 HR 机器人可以读取员工信息的接口但不同的提问者能访问的字段范围应该是不一样的一个普通员工查自己的信息没问题但去查全公司薪酬那就是越权。生产级方案里建议不要把权限判断逻辑塞进大模型的 Prompt 里让它“自觉遵守”因为 Prompt 随时可能被诱导或遗忘。比较稳妥的做法是在“工具调用层”做强制拦截也就是在代码层面严格控制每个 Agent 能调用哪类工具以及在工具执行前检查凭证参数是否合法。如果想做更细粒度的管控可以在 Agent 的工具执行层封装一层“策略代理”在请求工具前先从用户上下文里提取角色和权限标签再和工具自身预设的“允许调用者身份”白名单比对。凡是权限不匹配的调用直接在代码层拦截掉给出明确的“无权限”反馈。这种逻辑完全可以不经过大模型判断单纯靠代码实现可靠性高很多。除了权限还有内容安全。如果 Agent 会面向外部用户提供对话服务建议在 Agent 的输出侧再接一层独立的“内容过滤审核模块”不要完全信任模型自己的“安全指令”。因为生产系统要的是确定性的安全底线不是概率性的可解释。3.4 成本与性能优化一次任务该花多少钱必须心里有数生产落地还有一个非常现实的妈妈问题成本。我在会场随机问了几位开发者大家单次复杂 Agent 任务的 Token 消耗普遍在几千到几万之间。如果企业每天有几十万次调用一个月 Token 账单会让你谨慎起来。现场分享里关于成本控制的几个思路我觉得很实在尽量用较小的模型处理分类路由、信息抽取等简单任务把大模型留给真正需要复杂推理的节点。多 Agent 架构天然支持这件事你可以给不同角色的 Agent配置不同档位的模型。设置工具调用次数上限和任务时间上限防止 Agent 在一个问题上陷入死循环。通常我会在 Agent 循环里加一个“最大步数”参数比如最多 8 步。在模型上下文里做“信息裁剪”只把与当前目标相关的历史简报传给模型而不是把所有历史 Agent 会话一股脑塞进去。这需要你在设计状态时同步结构化的“记忆”摘要缓存到向量库或用本地内存滚动窗口。对高频工具调用结果做 Cache缓存比如两个不同会话查询同一个订单号工具返回结果可以短期复用没有必要让 Agent 每次重复调一次接口。模型推理的缓存是很有效的手段。很多框架已经支持对话级缓存也就是同一段 Prompt 前缀重复出现时直接命中缓存按输入 Token 缓存计费成本能下降一些。对于 Agent 系统来说你的 System Prompt 通常是固定长前缀天然适合这类缓存。你在工程化设计时尽量把“动态变化的信息”放在消息尾部把固定模板放前面。这是成本优化中一个几乎零成本、强烈推荐的做法。4. 现场工程 Demo 还原搭一个最小可用的多 Agent 协作骨架4.1 为什么用代码骨架来理解架构最有效现场最受欢迎的一个环节是讲师直接打开编辑器用一份不那么复杂的代码演示“Supervisor 调度两个 Worker Agent”跑通一个完整任务。虽然这个 Demo 只用了一两百行但它很清晰地展示了几个生产级关键点Agent 的循环不是“一次调用模型就结束”而是“多轮预测 工具调用”的组合Supervisor 如何根据用户的复杂请求做动态任务拆解每一步的工具调用结果如何实时回填到下一次模型请求的上下文里。我在会后把这个骨架复现了一下去掉了他们项目里的商业依赖只保留纯 Python 和大模型 API做了一个小版本让没到现场的朋友也能顺着代码走一遍。4.2 环境准备与依赖选型这一段我用的假设是你已经有可用的模型 API Key。如果你是在本地实验推荐用国产 DeepSeek 或智谱这类对开发者友好的供应商接口如果你不打算调外部 API也可以用本地部署的 Qwen 或 Llama 系列模型通过 OpenAI 兼容接口来跑。关键在于理解流程不必刻意追求模型最大。为了让下面示例开箱即用我做了这样的简化直接用 openai SDK 配置 base_url 来兼容不同的大模型供应方定义了一个轻量的工具函数调用机制没有引入重量级框架Supervisor 和 Worker 都由同一个Agent类来生产只靠不同 System Prompt 区分角色安装依赖只需pip install openai如果你要用 Redis 存储状态就再加pip install redis示例里我先用字典存运行状态你们换到数据库就是封装一个函数的问题。4.3 核心代码MyTool 与最小 Agent 循环首先定义两个模拟工具一个用来“查天气”一个用来“算运费”。注意我这里故意让工具的说明文本带参数描述这样设计的目的是让模型知道什么场景下该调用哪个工具。import json from openai import OpenAI client OpenAI( api_keyyour-api-key, base_urlhttps://your-model-provider/v1 ) TOOLS { get_weather: { description: 查询指定城市的天气情况。, parameters: {city: string} }, calc_shipping: { description: 根据重量千克计算快递运费。, parameters: {weight_kg: number} } } def execute_tool(name: str, args: dict): if name get_weather: city args.get(city, ) return {city: city, weather: 晴, temp: 26} if name calc_shipping: w float(args.get(weight_kg, 1)) # 模拟计费规则 fee 8 max(0, w - 1) * 2.5 return {weight_kg: w, shipping_fee: round(fee, 2)} return {error: unknown tool}接着实现 Agent 循环。这个循环的逻辑跟很多主流 Agent 框架的底层机制是同一个思路把系统提示词、历史消息、工具定义还给模型模型决定是直接回复还是发起工具调用直到模型输出最终回复或达到步数上限。def run_agent(system_prompt: str, user_message: str, tools, max_steps8): messages [ {role: system, content: system_prompt}, {role: user, content: user_message} ] for step in range(max_steps): try: resp client.chat.completions.create( modelyour-model-name, messagesmessages, tools[ { type: function, function: { name: name, description: meta[description], parameters: { type: object, properties: meta[parameters], required: list(meta[parameters].keys()) } } } for name, meta in tools.items() ] ) except Exception as e: return f模型调用异常: {e} msg resp.choices[0].message if not msg.tool_calls: # 模型不要求调用工具说明它已生成最终回复 return msg.content or # 模型要求调用工具把工具返回结果追加到消息序列中继续下一轮 messages.append({ role: assistant, content: msg.content, tool_calls: [ {id: tc.id, type: function, function: tc.function} for tc in msg.tool_calls ] }) for tc in msg.tool_calls: func_name tc.function.name try: args json.loads(tc.function.arguments or {}) except json.JSONDecodeError: args {} result execute_tool(func_name, args) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse) }) return 已超出最大执行步数任务终止。这就是 Agent 的最简循环。一般框架做的事本质上与此相同如果你非要自己造轮子这个骨架就是最核心的循环基础只是要做超时、并发限流、日志追踪等更多优化。4.4 Supervisor Agent 调用 Worker 的实现演示的重头戏是 Supervisor 动态拆分任务再分别让“天气 Worker”和“运费 Worker”完成最后汇总。为了展示“动态拆解”我给 Supervisor 的提示词里明确写了“你要判断用户问题是哪类任务必须调用对应的 worker”。让同一套工具机制变成“动态分派 Worker”的办法很直接把其他 Agent 当作上层 Agent 的“工具”。比如我可以把run_agent(worker_system, task)包装成worker_execute(task)这个函数放进 TOOLS 里。此时 Supervisor 调用工具会触发 Worker 的完整 Agent 循环。WEATHER_WORKER_SYSTEM ( 你是一个专门的天气助手。请使用 get_weather 工具查询天气。 只需要回答查询的实际天气数据不要自行编造。 ) SHIPPING_WORKER_SYSTEM ( 你是一个专门计算快递运费的助手。请使用 calc_shipping 工具进行计算。 给出最终运费金额保留两位小数。 ) SUPERVISOR_SYSTEM ( 你是一个任务调度助手。你需要判断用户请求的类型。\n 如果用户需要天气信息调用 task_weather 工具并填入用户的城市。\n 如果用户需要计算运费调用 task_shipping 工具并填入重量。\n 如果有多个需求请分别调用。最终把子任务结果整理成一段完整回复。 ) TOOLS_SUPERVISOR { task_weather: { description: 调用天气 Worker 获取某个城市的天气。, parameters: {city: string} }, task_shipping: { description: 调用运费 Worker 计算重量为多少千克的快递费。, parameters: {weight_kg: number} }, } def execute_supervisor_tool(name: str, args: dict): if name task_weather: city args.get(city, ) return json.loads(run_agent(WEATHER_WORKER_SYSTEM, f请查询{city}的天气, TOOLS)) if name task_shipping: w args.get(weight_kg, 1) return json.loads(run_agent(SHIPPING_WORKER_SYSTEM, f请计算导重量 {w} 千克的运费, TOOLS)) return {error: unknown tool}运行测试user_ask 北京今天天气怎么样另外我有一个3.5千克的包裹要寄运费大概多少 result run_agent(SUPERVISOR_SYSTEM, user_ask, TOOLS_SUPERVISOR, max_steps6) print(result)可以看到Supervisor 在收到混合任务后依次发起两个 Worker 调用分别拿到工具跑出来的结果最终拼出一段完整、自然的中文回复。这个骨架虽然玩具味很浓但“上层调度 下层执行”的信号链路和很多生产级编排器在核心调度层面本质一样。你在实际项目中引入框架时看到AgentExecutor、Router、SubAgent这些 API 不必慌它们都在解决同样的问题。4.5 从骨架到生产还差哪几步现场圆桌环节有个提问“如果我照着这个骨架写能不能直接上线”答案是“还差得远但方向已经对了”。这段距离概括起来至少有四步第一步把内存中的消息序列换成可持久化的会话存储Redis / PG / 对象存储让服务重启不丢失进程第二步给每一步加 trace_id 和日志上下文集成到监控系统保证每个结果可追溯第三步把工具调用包一层权限校验 SDK让不同用户的凭证隔离交由代码执行前判断第四步建一套回放测试机制有了线上日志之后把高频失败案例沉淀成回归用例做到“跑一次回归就知道新改动有没有破坏旧功能”。如果有团队人力也可以直接在这些环节使用开源框架已实现的部分。生产级的关键往往并不在“自己写一个多 Agent”而是“自己的 Agent 在多层失败发生时不至于变成黑盒”。5. 常见问题与排查技巧实录现场 QA 里的高频坑5.1 工具调用循环卡死或无限重试这是被问到最多的问题。用户会在聊天框里发一句“查一下杭州天气”结果 Agent 却在工具调用循环里反复请求怎么都出不来最终文本。出现这种问题最常见的原因有三个模型返回了 tool_calls但你的代码没有正确将“工具返回结果”追加到 messages 里或者 tool_call_id 不匹配模型每轮都看不到自己上次调用的结果只能一遍遍重新发起同样请求工具执行抛了异常你捕获之后返回了一个普通字符串而不是工具消息格式模型无法解析这种异常格式的输出内容工具返回内容是空的或者说格式混乱模型的指令遵循能力下降而开始乱猜导致一次一次换参数重进循环。我的排查方法很简单第一翻每步的 trace 日志确认“工具结果有没有成功回填”第二给循环加步数上限防止它无限消耗 Token。这两条是基础中的基础建议刚起步的开发者先做好。如果你的业务确实依赖特别多的工具更应该考虑把工具定义拆成小组让每个 Agent 只面对小决策空间降低格式化输出的出错率。5.2 多个 Agent 之间状态同步错乱多 Agent 场景里状态同步问题尤其隐蔽。现场有位开发者的案例特别典型他们在项目里让两个 Worker Agent 同时处理不同城市的天气结果两个 Worker 共用了同一个上下文变量导致最终结果把城市 A 的天气安到了城市 B 头上。这个问题本质上是“Agent 的对话记忆串了”。解决思路有两个方向一是严格隔离每个 Worker 运行时使用独立的 OpenAI 消息列表永远不要把不同任务的中间状态拼接在一起二是引入外部可检索记忆把每个子任务的结果存成带 key 的对象上层在做结果合并时要显式检查 key 对不上的结果宁可报错也不允许乱合并。我从这个案例里得到的教训很深刻Agent 的“记忆”是一个需要显式设计的状态容器不是你想当然的“上下文自然流动”。模型是概率生成器它不会自动维护变量边界你必须用工程手段帮它把边界画清楚。5.3 新版本 Prompt 改完线上效果反而变差这也是多 Agent 时代很容易让人崩溃的问题明明 Prompt 措辞更清楚了示例也加上了结果真实任务的成功率不升反降。现场有位讲师给的解释很有意思加 Prompt 和加代码一样每加一句话都会影响整个指令空间的分布甚至会导致原本正确路径的优先级下降。建议团队养成两个习惯重大 Prompt 调整不直接全量上线而是先用离线评估集跑分对比新旧两版的基线通过率在测试集之外单独保留一批“历史难例”。每次改动都确保这批难例仍然能通过防止“修复一个 bug 引入另一个 bug”。这里我再补充一个小技巧当你要给某个 Agent 的 System Prompt 增加限制时例如“禁止输出额外内容”与其反复用自然语言强调不如设计严格的结构约束——要求输出必须是一个 JSON 块且该 JSON 的字段类型有固定 schema。结构性约束往往比纯文字约束更有效果。5.4 线上效果不好排查该从哪端开始很多团队一看到 Agent 回答错误第一反应就是“改写 Prompt”。但生产的经验告诉我们先别急着动 Prompt 按下面的链路来定位先看这次任务完整链路有没有异常——是不是工具调用在中间阶段就失败了或者调用了一个访问权限不允许的内部接口再看检索或工具召回的内容质量——如果丢给模型的业务数据本身就是错的那后面的整个推理过程都是“垃圾进、垃圾出”最后再看模型生成策略——如果输入数据和工具返回都正常模型还是答不对才考虑调整 Prompt 或者换更强的模型。数据源质量对 Agent 落地的影响远比我们想象的还大。Agent 一个关键变化是“从生成信息到操纵信息”它可能去调用企业的订单系统、库存系统如果这些数据接口很陈旧或有脏数据那模型再聪明也无力回天。现场有人提了个很冲的观点Agent 工程其实是在倒逼你把企业内部数据质量和 API 稳定性做到前所未有的高度我非常认同。6. 对开源 Agent 生态的观察社区在解决什么问题还有哪些空白6.1 开源框架的共识与差异这次沙龙有着较强的开源属性讨论必然会落到“用开源框架还是自研”上。我的观察是现在主流开源 Agent 框架的共识已经越来越明显了——都支持“模型无关”、都内置工具调用协议、都提供状态持久化接口。差异则体现在各自对“编排方式”的抽象层度不一样有的框架偏向“显式图”把 Agent 流程定义成节点和边适合流程确定性要求高的场景有的框架偏向“隐式编排”你只给 Agent 一堆工具它靠自己规划调用顺序适合探索性强的场景还有的是“角色扮演 协作文本”路线用多份人格化系统 Prompt 模拟一个团队开会讨论适合头脑风暴型任务但生产稳定性也是三类里相对最难保证的。我的建议是技术团队不要盲从框架先回到自己业务流程的几个本质特征我的流程是否需要人工审批卡点失败后是否需要精确到某个节点重跑是否需要人工随时切换执行路径这些需求如果都非常明确你应该选显式图能力强的框架如果需求是“输入很开放、路径不确定”适合选隐式编排并在其中叠加落地护栏步数上限、权限、观测埋点。6.2 开源项目选型的三条经验看一个开源 Agent 项目能不能用于生产我一般会先从三件事入手看维护活跃度最近半年是否有新版本 release、Issues 是不是有人回复。Agent 生态更新极快停更几个月的项目很多 API 可能就对接不上当前主流模型了尽量选还在持续迭代的项目看可扩展点项目是否允许你自定义工具、自定义状态存储后端、自定义模型接入。如果一个框架把所有能力都写死内部想改成公司内部服务会相当痛苦看社区案例是否有企业真实案例、生产环境经验分享。纯热度高但没有生产用户的项目往往停留在“技术尝鲜”阶段。另外在许可协议上也要留意。如果是公司内部商业化用途尽量别碰传染性太强的 License避免后续上架应用时被动。如果只是自己做学习研究则无所谓多数宽松协议都OK。6.3 学习路线从能跑通 Demo 到能设计系统写到最后给想系统入坑 Agent 开发的读者画一条更稳的路线手动实现一遍“模型循环 工具调用”不用框架先理解底层机制。这一关过了你就不会再对 Agent 有什么神秘感开始用成熟的 Agent 框架刻意去读它的核心源码特别关注状态管理、错误恢复、工具调用协议这三个模块的实现把一个现有业务场景比如“工单自动分类 智能回复”做成端到端 Demo加入人工审批节点模拟真实流程为目标系统设计评估集建立类似 CI/CD 的“Agent 回归测试”流程最后再考虑多 Agent 协作模式——先单后多、先显式后隐式、先简单任务再复杂编排是一条相对平滑的上手路径。我个人在这些年折腾 Agent 项目的最大体会是模型能力的天花板现在已经很高了工程化能力反而成了拉开差距的地方。谁能把不可预测的大模型行为装进可观测、可回滚、可评估的生产流程里谁才真正拥有把 Agent 变成产品的能力。沙龙结束的时候天已经暗下来。场馆里还有不少人在围着讲师交流自己项目遇到的设计难题。我整理完这些笔记后最大的感想是Agent 开发越来越像一门“工程学科”了它正在脱离提示词调优和 Demo 炫技的阶段走到真正的软件工程体系里去。你能越早用对待分布式系统的谨慎来对待 Agent你的路就会走得越稳。 多Agent协作与生产级工程实践：从架构选型到落地避坑
广州站这场沙龙是我今年以来参加过“信息密度”最高的一场 Agent 技术活动。坦白说早两年听 Agent 相关的分享总有一种“Demo 很惊艳、落地很遥远”的悬空感但这次完全不一样——从多 Agent 协作的框架选型到生产环境里的状态管理、可观测性、权限隔离再到现场直接跑通的工程链路几乎每个议题都在回答同一个问题Agent 到底要怎么做才能从一个“会聊天的原型”变成一个敢让业务数据流经过它的系统。这篇文章算是我的现场笔记加会后复盘。我没有按嘉宾演讲顺序平铺直叙而是把当天反复出现的几条主线拎出来多 Agent 协作的模式与边界、生产级工程实践里的关键环节、现场演示的代码还原过程以及我个人踩坑后总结的排查清单。如果你正准备把一个 AI Agent 项目推向线上或者想了解多 Agent 架构该怎么选型这篇文章应该能让你少走不少弯路。1. 现场氛围与主题主线从“能跑”到“敢跑”1.1 这两年最大的变化大家开始聊“失败率”和“成本”了现场有个细节让我印象很深好几场分享的开头都没有放炫酷的对话录屏而是直接贴了一张线上环境的监控大盘。上面有请求量、Token 消耗、工具调用成功率、Agent 单次任务平均步数、重试分布。放在两年前这类指标在 Agent 分享里几乎看不到——那时候大家更愿意展示“它多聪明”而不是“它多可控”。这说明 Agent 开发这件事正在经历一次比较明显的范式转移早期阶段大家关注的是“大模型能不能理解我的指令”于是 Prompt 工程、思维链、ReAct 循环成了主角到了现在这个阶段模型能力已经不是最大瓶颈反而是工程问题——多个 Agent 之间怎么协作、任务状态放在哪里、工具调用失败后怎么恢复、用户隐私和权限边界怎么划——这些以往容易被忽略的部分变成了决定项目能不能上线的关键。这次广州站的议程也明显围绕这条主线展开。多 Agent 协作不是单纯讲“怎么让两个 Agent 对话”而是给出了可落地的架构模式谁是决策者、谁是执行者、消息走什么协议、并发怎么控制、单个任务卡住时怎么处理。生产级工程实践也不是喊口号而是细化到状态存储选型、可观测性埋点、评估集建设这些非常具体的事项。1.2 适合哪些人参考如果你是下面这几类人这篇回顾的参考价值会比较高已经在用 LangChain、LlamaIndex 或自己封装的大模型接口做原型验证正准备往生产环境迁移的开发者负责企业级 AI 平台、Agent 编排层、RAG 系统架构的技术负责人刚接触 Agent 开发想了解多 Agent 协作和传统分布式系统之间异同的后端工程师对开源项目选型感兴趣想知道哪些模块适合自研、哪些模块该拥抱社区方案的产品技术人员。我个人建议带着两个问题去读第一多 Agent 架构里的“多”到底是为了解决什么问题还是为了追热点第二生产级实践里有哪些环节是模型能力无法替代的。想清楚这两个问题很多技术选型你就不会纠结了。2. 多 Agent 协作的架构拆解模式、边界与适用场景2.1 单 Agent 不够用先搞清楚缺的到底是什么活动现场聊到一个很高的频次问题业务还没跑通是否有必要直接上多 Agent我听到的比较一致的回答是不要为了“多”而“多”。单 Agent 无法满足业务需求通常不是模型能力不够而是职责太杂导致 Prompt 失控。举个例子一个客服机器人如果既要负责意图识别、又要查订单、又要处理售后安抚、又要生成工单那你塞给它的指令会变得极其复杂。每个工具的调用说明、每次回复的语气要求、每类异常的处理方式全部堆在一个上下文窗口里模型被互相矛盾的指令干扰的概率会急剧上升输出的稳定性自然就差。多 Agent 架构的核心价值是把“一个大而全的智能体”拆成“多个小而专的智能体”每个 Agent 只负责一个边界清晰的子任务。这种拆分能带来三个直接好处Prompt 长度显著降低模型注意力更集中指令遵循率会提升单个 Agent 的工具集更小被误调用的概率下降可以针对不同 Agent 配置不同的模型便宜的模型处理分类任务更强的模型处理复杂推理成本控制更灵活。但请注意多 Agent 也意味着更高的消息传递开销、更复杂的失败链路和更难排查的问题。这是一个典型的“用工程复杂度换业务可控性”的取舍不是免费的午餐。2.2 三种主流协作模式Supervisor、Pipeline 与 Debate现场把当前常见的多 Agent 协作模式归纳成了三类我用比较通俗的方式复述一下。第一种是 Supervisor监督者/主从模式。这种模式下有一个“老板”角色负责拆解任务、调用下游的 Worker Agent、收集结果、判断是否需要返工。Worker 之间一般不做横向通信所有交互都要经过 Supervisor。它最像传统企业里的项目经理角色。这种模式适合什么场景任务边界清晰、可以自上而下拆分的场景比如“我要写一份行业分析报告”Supervisor 可以先拆出信息检索、数据分析、图表生成、文字润色几个环节然后按依赖顺序派发。它的优势是流程可控、每个子任务的产出可以被单独验证非常适合流程型任务。第二种是 Pipeline流水线模式。这个更好理解就是任务严格按阶段流动前一个 Agent 的输出是后一个 Agent 的输入。它适合处理有强依赖关系的阶段化工作流比如“客户咨询工单处理”先由分类 Agent 判断工单类型再由质检 Agent 核查合规风险最后由回复 Agent 拟稿每一步的输出不回头。需要提醒的是Pipeline 模式最怕中间环节出错。如果上游 Agent 输出了一个结构不完整的结果下游 Agent 很容易“顺着错误的格式继续编下去”。所以在流水线模式的每个阶段之间加一层结构校验输出必须符合 JSON Schema 或必须包含指定字段是现场工程分享里反复强调的实践。第三种是 Debate辩论/评审模式。多个 Agent 拿到同一个任务后分别产出结果再由一个评审 Agent 或规则引擎挑选最优解。这种模式适合开放性较强、没有唯一标准答案的任务比如代码审查、文案方案选优。它的缺点是成本会翻倍因为同一任务被好几个 Agent 各执行了一遍。生产环境里要做取舍不是所有主流程都值得用。我在项目里常用的是“Supervisor Pipeline 混合”主流程用 Pipeline 保证顺序稳定关键决策节点插入 Supervisor 做动态路由这样可以兼顾流程可控和灵活决策。沙龙上也有一位讲师给出了类似的观点他称之为“主流程确定化决策节点智能化”这个思路非常值得借鉴。2.3 多 Agent 协作的工程红线别让“协作”变成“混乱”现场有一个观点我听得很认同多 Agent 架构里的通信协议和数据格式是最容易被低估的部分。很多人一开始只定义“每个 Agent 的 Prompt”却忘了定义“Agent 和 Agent 之间传什么、传成什么样、传不过去怎么办”。如果你决定上多 Agent下面这几个问题必须在设计阶段明确回答消息协议长什么样是纯 JSON 还是结构化对象字段怎么命名有没有版本号上下文怎么共享全部塞进同一个上下文窗口还是通过外部存储按需读取结果怎么校验下游 Agent 如何判断上游给的结果是“可用的”而不是“模型幻觉产生的”失败如何传递某个 Agent 任务失败了是重试、降级还是终止并通知用户是否允许回环Agent 之间互相调用来调用去会不会出现死循环现场有人提出了一个很形象的比喻多 Agent 协作本质上是一个“分布式系统”只是每个节点不是普通服务而是带着不可预测性的模型实例。既然是分布式系统那分布式领域里那些“臭名昭著”的问题——状态不一致、消息丢失、死循环、超时无响应——一个都不会少甚至会被模型的随机性放大。关于协作边界我自己的体会是尽量让 Agent 之间的交互呈现“树状”不要出现“网状”。树状结构可以让你很清楚地知道“当前这个结果是由哪条路径产生的”出了问题能隔离、能回溯。网状结构听起来很智能但每次任务都有几十种可能的路径组合一旦出错排查看不到头。3. 生产级工程实践决定 Agent 能不能上线的关键环节3.1 状态管理Agent 不是无状态的接口而是有状态的任务流这是当天讨论最热烈的话题之一。很多从原型过渡到生产的团队第一次翻车往往不是在模型响应质量上而是状态管理没做好。过去我们写传统后端接口习惯“无状态设计”——请求进来、处理完、返回结果服务本身不保存任何状态。但 Agent 任务是典型的“长时运行、多步决策”流程一个任务可能包含“检索资料 → 生成草稿 → 调用内部 API 核对数据 → 修改输出 → 提交审核”五个环节这个过程可能要持续几分钟甚至更久。在这几分钟里如果服务重启了、Pod 被重新调度了、网络闪断了任务状态还在吗如果用户关掉了页面后台任务是否需要继续跑如果 Agent 在第五步失败是回到第四步还是从头再来这些问题的答案统统指向一个基础设施组件任务状态的持久化存储。现场的建议比较一致不要自己用内存里的全局变量硬扛要看你们团队的运维习惯选一个成熟方案。最常见的是把状态放进 Redis通过键存储任务 ID每个节点的状态快照用 Hash 数据结构存复杂任务则放进关系型数据库单表存储的多列、JSON 字段、创建时间、更新时间、每一步的输入输出有迹可循分布式场景下可以再用消息队列解耦。我自己的项目痛定思痛后的选择是把“主流程状态”放进了 PostgreSQL。原因很简单它的行级锁和事务能力可以帮我处理很多并发一致性问题而且我习惯性地把每一次工具调用的入参和出参都存进去。这样就算 Agent 最终给了一个错误答案我还能把历史回溯出来看看是哪一步开始错的。但是注意并不是把状态存数据库就万事大吉了真正复杂的是“恢复策略”。一个中断的任务恢复时是从 Agent 的“最后一步”续跑还是把整个 Agent 会话重新构建一遍这里没有标准答案完全取决于你每个步骤是不是幂等的。如果你的步骤被设计成“调用一次和调用一百次效果一样”的幂等操作那重放就是安全的如果某些步骤会产生副作用比如已经扣了款、已经发了短信那你就需要给每个步骤定义清晰的“幂等键”用来判断这个动作之前是否已经执行过。3.2 可观测性与评估体系没有度量就没有优化现场有一位做平台工程的嘉宾分享了一组数据让我触动很深他们团队在半年内迭代了几十个 Agent 版本但真正推动版本迭代的并不是“更多人提出新需求”而是“基线评估集”里的回归测试暴露的问题。换句话说Agent 能力的提升本质上靠的是一套能自动运行、能自动比对结果的评估流水线。我把这套思路拆成两层一层是“过程可观测”另一层是“结果可评估”。过程可观测指的是每一轮 Agent 运行时的完整轨迹都可追踪。大模型输出的都是 Token如果运行过程没有系统化地记录下来出了问题你根本无法判断是“用户意图理解错了”“检索召回的内容不对”“工具参数构造有误”还是“模型在最后一步撒谎了”。目前比较流行的做法是在 Agent 框架的关键节点加上分布式追踪埋点每轮循环记录下输入消息、当前使用的 Agent 角色、调用了哪个工具、工具传参是什么、工具返回是什么、模型原始输出完整内容、最终定向用户的那条消息内容。这些日志不仅用于排查更深层的价值是构建你的“案例库”——每一次线上真实运行的成功或失败案例都可以沉淀下来成为后续评估集的素材。结果可评估则是建一套“测评问题集 自动判定”的体系。这听起来是在做“测试”但和传统测试的区别是Agent 的输出是开放的你没法用断言直接比对字符串。现在的通用做法是引入“裁判模型”用另一个大模型来给 Agent 的输出质量打分或者按规则检查“是否包含核心要素”。做法可以是准备 3 类测试数据覆盖主流程的正确路径、容易出错的边界输入、不该放行的风险输入用离线任务批量跑 Agent输出结果存文件用“带评分规则的裁判模型”批量给结果打分同时把低分案例人工复核每次 Prompt 或 Agent 代码有变动就跑一遍全量回归分数对比低于基线就不允许合并。评估集听起来很“重”但它是把 Agent 从“玄学”变成“工程”的必经之路。没有评估集你就没法回答一个最基本的问题“你这次改动到底是变好了还是变差了”。3.3 权限、安全与合规Agent 越强大边界越要清晰把 Agent 接到生产业务上权限模型注定是绕不开的硬骨头。如果说传统 API 的权限控制是“一个用户调用一个接口”那么 Agent 场景的权限控制就是“一个任务通过一组可能变化路径的工具调用按钮完成”。比如一个 HR 机器人可以读取员工信息的接口但不同的提问者能访问的字段范围应该是不一样的一个普通员工查自己的信息没问题但去查全公司薪酬那就是越权。生产级方案里建议不要把权限判断逻辑塞进大模型的 Prompt 里让它“自觉遵守”因为 Prompt 随时可能被诱导或遗忘。比较稳妥的做法是在“工具调用层”做强制拦截也就是在代码层面严格控制每个 Agent 能调用哪类工具以及在工具执行前检查凭证参数是否合法。如果想做更细粒度的管控可以在 Agent 的工具执行层封装一层“策略代理”在请求工具前先从用户上下文里提取角色和权限标签再和工具自身预设的“允许调用者身份”白名单比对。凡是权限不匹配的调用直接在代码层拦截掉给出明确的“无权限”反馈。这种逻辑完全可以不经过大模型判断单纯靠代码实现可靠性高很多。除了权限还有内容安全。如果 Agent 会面向外部用户提供对话服务建议在 Agent 的输出侧再接一层独立的“内容过滤审核模块”不要完全信任模型自己的“安全指令”。因为生产系统要的是确定性的安全底线不是概率性的可解释。3.4 成本与性能优化一次任务该花多少钱必须心里有数生产落地还有一个非常现实的妈妈问题成本。我在会场随机问了几位开发者大家单次复杂 Agent 任务的 Token 消耗普遍在几千到几万之间。如果企业每天有几十万次调用一个月 Token 账单会让你谨慎起来。现场分享里关于成本控制的几个思路我觉得很实在尽量用较小的模型处理分类路由、信息抽取等简单任务把大模型留给真正需要复杂推理的节点。多 Agent 架构天然支持这件事你可以给不同角色的 Agent配置不同档位的模型。设置工具调用次数上限和任务时间上限防止 Agent 在一个问题上陷入死循环。通常我会在 Agent 循环里加一个“最大步数”参数比如最多 8 步。在模型上下文里做“信息裁剪”只把与当前目标相关的历史简报传给模型而不是把所有历史 Agent 会话一股脑塞进去。这需要你在设计状态时同步结构化的“记忆”摘要缓存到向量库或用本地内存滚动窗口。对高频工具调用结果做 Cache缓存比如两个不同会话查询同一个订单号工具返回结果可以短期复用没有必要让 Agent 每次重复调一次接口。模型推理的缓存是很有效的手段。很多框架已经支持对话级缓存也就是同一段 Prompt 前缀重复出现时直接命中缓存按输入 Token 缓存计费成本能下降一些。对于 Agent 系统来说你的 System Prompt 通常是固定长前缀天然适合这类缓存。你在工程化设计时尽量把“动态变化的信息”放在消息尾部把固定模板放前面。这是成本优化中一个几乎零成本、强烈推荐的做法。4. 现场工程 Demo 还原搭一个最小可用的多 Agent 协作骨架4.1 为什么用代码骨架来理解架构最有效现场最受欢迎的一个环节是讲师直接打开编辑器用一份不那么复杂的代码演示“Supervisor 调度两个 Worker Agent”跑通一个完整任务。虽然这个 Demo 只用了一两百行但它很清晰地展示了几个生产级关键点Agent 的循环不是“一次调用模型就结束”而是“多轮预测 工具调用”的组合Supervisor 如何根据用户的复杂请求做动态任务拆解每一步的工具调用结果如何实时回填到下一次模型请求的上下文里。我在会后把这个骨架复现了一下去掉了他们项目里的商业依赖只保留纯 Python 和大模型 API做了一个小版本让没到现场的朋友也能顺着代码走一遍。4.2 环境准备与依赖选型这一段我用的假设是你已经有可用的模型 API Key。如果你是在本地实验推荐用国产 DeepSeek 或智谱这类对开发者友好的供应商接口如果你不打算调外部 API也可以用本地部署的 Qwen 或 Llama 系列模型通过 OpenAI 兼容接口来跑。关键在于理解流程不必刻意追求模型最大。为了让下面示例开箱即用我做了这样的简化直接用 openai SDK 配置 base_url 来兼容不同的大模型供应方定义了一个轻量的工具函数调用机制没有引入重量级框架Supervisor 和 Worker 都由同一个Agent类来生产只靠不同 System Prompt 区分角色安装依赖只需pip install openai如果你要用 Redis 存储状态就再加pip install redis示例里我先用字典存运行状态你们换到数据库就是封装一个函数的问题。4.3 核心代码MyTool 与最小 Agent 循环首先定义两个模拟工具一个用来“查天气”一个用来“算运费”。注意我这里故意让工具的说明文本带参数描述这样设计的目的是让模型知道什么场景下该调用哪个工具。import json from openai import OpenAI client OpenAI( api_keyyour-api-key, base_urlhttps://your-model-provider/v1 ) TOOLS { get_weather: { description: 查询指定城市的天气情况。, parameters: {city: string} }, calc_shipping: { description: 根据重量千克计算快递运费。, parameters: {weight_kg: number} } } def execute_tool(name: str, args: dict): if name get_weather: city args.get(city, ) return {city: city, weather: 晴, temp: 26} if name calc_shipping: w float(args.get(weight_kg, 1)) # 模拟计费规则 fee 8 max(0, w - 1) * 2.5 return {weight_kg: w, shipping_fee: round(fee, 2)} return {error: unknown tool}接着实现 Agent 循环。这个循环的逻辑跟很多主流 Agent 框架的底层机制是同一个思路把系统提示词、历史消息、工具定义还给模型模型决定是直接回复还是发起工具调用直到模型输出最终回复或达到步数上限。def run_agent(system_prompt: str, user_message: str, tools, max_steps8): messages [ {role: system, content: system_prompt}, {role: user, content: user_message} ] for step in range(max_steps): try: resp client.chat.completions.create( modelyour-model-name, messagesmessages, tools[ { type: function, function: { name: name, description: meta[description], parameters: { type: object, properties: meta[parameters], required: list(meta[parameters].keys()) } } } for name, meta in tools.items() ] ) except Exception as e: return f模型调用异常: {e} msg resp.choices[0].message if not msg.tool_calls: # 模型不要求调用工具说明它已生成最终回复 return msg.content or # 模型要求调用工具把工具返回结果追加到消息序列中继续下一轮 messages.append({ role: assistant, content: msg.content, tool_calls: [ {id: tc.id, type: function, function: tc.function} for tc in msg.tool_calls ] }) for tc in msg.tool_calls: func_name tc.function.name try: args json.loads(tc.function.arguments or {}) except json.JSONDecodeError: args {} result execute_tool(func_name, args) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse) }) return 已超出最大执行步数任务终止。这就是 Agent 的最简循环。一般框架做的事本质上与此相同如果你非要自己造轮子这个骨架就是最核心的循环基础只是要做超时、并发限流、日志追踪等更多优化。4.4 Supervisor Agent 调用 Worker 的实现演示的重头戏是 Supervisor 动态拆分任务再分别让“天气 Worker”和“运费 Worker”完成最后汇总。为了展示“动态拆解”我给 Supervisor 的提示词里明确写了“你要判断用户问题是哪类任务必须调用对应的 worker”。让同一套工具机制变成“动态分派 Worker”的办法很直接把其他 Agent 当作上层 Agent 的“工具”。比如我可以把run_agent(worker_system, task)包装成worker_execute(task)这个函数放进 TOOLS 里。此时 Supervisor 调用工具会触发 Worker 的完整 Agent 循环。WEATHER_WORKER_SYSTEM ( 你是一个专门的天气助手。请使用 get_weather 工具查询天气。 只需要回答查询的实际天气数据不要自行编造。 ) SHIPPING_WORKER_SYSTEM ( 你是一个专门计算快递运费的助手。请使用 calc_shipping 工具进行计算。 给出最终运费金额保留两位小数。 ) SUPERVISOR_SYSTEM ( 你是一个任务调度助手。你需要判断用户请求的类型。\n 如果用户需要天气信息调用 task_weather 工具并填入用户的城市。\n 如果用户需要计算运费调用 task_shipping 工具并填入重量。\n 如果有多个需求请分别调用。最终把子任务结果整理成一段完整回复。 ) TOOLS_SUPERVISOR { task_weather: { description: 调用天气 Worker 获取某个城市的天气。, parameters: {city: string} }, task_shipping: { description: 调用运费 Worker 计算重量为多少千克的快递费。, parameters: {weight_kg: number} }, } def execute_supervisor_tool(name: str, args: dict): if name task_weather: city args.get(city, ) return json.loads(run_agent(WEATHER_WORKER_SYSTEM, f请查询{city}的天气, TOOLS)) if name task_shipping: w args.get(weight_kg, 1) return json.loads(run_agent(SHIPPING_WORKER_SYSTEM, f请计算导重量 {w} 千克的运费, TOOLS)) return {error: unknown tool}运行测试user_ask 北京今天天气怎么样另外我有一个3.5千克的包裹要寄运费大概多少 result run_agent(SUPERVISOR_SYSTEM, user_ask, TOOLS_SUPERVISOR, max_steps6) print(result)可以看到Supervisor 在收到混合任务后依次发起两个 Worker 调用分别拿到工具跑出来的结果最终拼出一段完整、自然的中文回复。这个骨架虽然玩具味很浓但“上层调度 下层执行”的信号链路和很多生产级编排器在核心调度层面本质一样。你在实际项目中引入框架时看到AgentExecutor、Router、SubAgent这些 API 不必慌它们都在解决同样的问题。4.5 从骨架到生产还差哪几步现场圆桌环节有个提问“如果我照着这个骨架写能不能直接上线”答案是“还差得远但方向已经对了”。这段距离概括起来至少有四步第一步把内存中的消息序列换成可持久化的会话存储Redis / PG / 对象存储让服务重启不丢失进程第二步给每一步加 trace_id 和日志上下文集成到监控系统保证每个结果可追溯第三步把工具调用包一层权限校验 SDK让不同用户的凭证隔离交由代码执行前判断第四步建一套回放测试机制有了线上日志之后把高频失败案例沉淀成回归用例做到“跑一次回归就知道新改动有没有破坏旧功能”。如果有团队人力也可以直接在这些环节使用开源框架已实现的部分。生产级的关键往往并不在“自己写一个多 Agent”而是“自己的 Agent 在多层失败发生时不至于变成黑盒”。5. 常见问题与排查技巧实录现场 QA 里的高频坑5.1 工具调用循环卡死或无限重试这是被问到最多的问题。用户会在聊天框里发一句“查一下杭州天气”结果 Agent 却在工具调用循环里反复请求怎么都出不来最终文本。出现这种问题最常见的原因有三个模型返回了 tool_calls但你的代码没有正确将“工具返回结果”追加到 messages 里或者 tool_call_id 不匹配模型每轮都看不到自己上次调用的结果只能一遍遍重新发起同样请求工具执行抛了异常你捕获之后返回了一个普通字符串而不是工具消息格式模型无法解析这种异常格式的输出内容工具返回内容是空的或者说格式混乱模型的指令遵循能力下降而开始乱猜导致一次一次换参数重进循环。我的排查方法很简单第一翻每步的 trace 日志确认“工具结果有没有成功回填”第二给循环加步数上限防止它无限消耗 Token。这两条是基础中的基础建议刚起步的开发者先做好。如果你的业务确实依赖特别多的工具更应该考虑把工具定义拆成小组让每个 Agent 只面对小决策空间降低格式化输出的出错率。5.2 多个 Agent 之间状态同步错乱多 Agent 场景里状态同步问题尤其隐蔽。现场有位开发者的案例特别典型他们在项目里让两个 Worker Agent 同时处理不同城市的天气结果两个 Worker 共用了同一个上下文变量导致最终结果把城市 A 的天气安到了城市 B 头上。这个问题本质上是“Agent 的对话记忆串了”。解决思路有两个方向一是严格隔离每个 Worker 运行时使用独立的 OpenAI 消息列表永远不要把不同任务的中间状态拼接在一起二是引入外部可检索记忆把每个子任务的结果存成带 key 的对象上层在做结果合并时要显式检查 key 对不上的结果宁可报错也不允许乱合并。我从这个案例里得到的教训很深刻Agent 的“记忆”是一个需要显式设计的状态容器不是你想当然的“上下文自然流动”。模型是概率生成器它不会自动维护变量边界你必须用工程手段帮它把边界画清楚。5.3 新版本 Prompt 改完线上效果反而变差这也是多 Agent 时代很容易让人崩溃的问题明明 Prompt 措辞更清楚了示例也加上了结果真实任务的成功率不升反降。现场有位讲师给的解释很有意思加 Prompt 和加代码一样每加一句话都会影响整个指令空间的分布甚至会导致原本正确路径的优先级下降。建议团队养成两个习惯重大 Prompt 调整不直接全量上线而是先用离线评估集跑分对比新旧两版的基线通过率在测试集之外单独保留一批“历史难例”。每次改动都确保这批难例仍然能通过防止“修复一个 bug 引入另一个 bug”。这里我再补充一个小技巧当你要给某个 Agent 的 System Prompt 增加限制时例如“禁止输出额外内容”与其反复用自然语言强调不如设计严格的结构约束——要求输出必须是一个 JSON 块且该 JSON 的字段类型有固定 schema。结构性约束往往比纯文字约束更有效果。5.4 线上效果不好排查该从哪端开始很多团队一看到 Agent 回答错误第一反应就是“改写 Prompt”。但生产的经验告诉我们先别急着动 Prompt 按下面的链路来定位先看这次任务完整链路有没有异常——是不是工具调用在中间阶段就失败了或者调用了一个访问权限不允许的内部接口再看检索或工具召回的内容质量——如果丢给模型的业务数据本身就是错的那后面的整个推理过程都是“垃圾进、垃圾出”最后再看模型生成策略——如果输入数据和工具返回都正常模型还是答不对才考虑调整 Prompt 或者换更强的模型。数据源质量对 Agent 落地的影响远比我们想象的还大。Agent 一个关键变化是“从生成信息到操纵信息”它可能去调用企业的订单系统、库存系统如果这些数据接口很陈旧或有脏数据那模型再聪明也无力回天。现场有人提了个很冲的观点Agent 工程其实是在倒逼你把企业内部数据质量和 API 稳定性做到前所未有的高度我非常认同。6. 对开源 Agent 生态的观察社区在解决什么问题还有哪些空白6.1 开源框架的共识与差异这次沙龙有着较强的开源属性讨论必然会落到“用开源框架还是自研”上。我的观察是现在主流开源 Agent 框架的共识已经越来越明显了——都支持“模型无关”、都内置工具调用协议、都提供状态持久化接口。差异则体现在各自对“编排方式”的抽象层度不一样有的框架偏向“显式图”把 Agent 流程定义成节点和边适合流程确定性要求高的场景有的框架偏向“隐式编排”你只给 Agent 一堆工具它靠自己规划调用顺序适合探索性强的场景还有的是“角色扮演 协作文本”路线用多份人格化系统 Prompt 模拟一个团队开会讨论适合头脑风暴型任务但生产稳定性也是三类里相对最难保证的。我的建议是技术团队不要盲从框架先回到自己业务流程的几个本质特征我的流程是否需要人工审批卡点失败后是否需要精确到某个节点重跑是否需要人工随时切换执行路径这些需求如果都非常明确你应该选显式图能力强的框架如果需求是“输入很开放、路径不确定”适合选隐式编排并在其中叠加落地护栏步数上限、权限、观测埋点。6.2 开源项目选型的三条经验看一个开源 Agent 项目能不能用于生产我一般会先从三件事入手看维护活跃度最近半年是否有新版本 release、Issues 是不是有人回复。Agent 生态更新极快停更几个月的项目很多 API 可能就对接不上当前主流模型了尽量选还在持续迭代的项目看可扩展点项目是否允许你自定义工具、自定义状态存储后端、自定义模型接入。如果一个框架把所有能力都写死内部想改成公司内部服务会相当痛苦看社区案例是否有企业真实案例、生产环境经验分享。纯热度高但没有生产用户的项目往往停留在“技术尝鲜”阶段。另外在许可协议上也要留意。如果是公司内部商业化用途尽量别碰传染性太强的 License避免后续上架应用时被动。如果只是自己做学习研究则无所谓多数宽松协议都OK。6.3 学习路线从能跑通 Demo 到能设计系统写到最后给想系统入坑 Agent 开发的读者画一条更稳的路线手动实现一遍“模型循环 工具调用”不用框架先理解底层机制。这一关过了你就不会再对 Agent 有什么神秘感开始用成熟的 Agent 框架刻意去读它的核心源码特别关注状态管理、错误恢复、工具调用协议这三个模块的实现把一个现有业务场景比如“工单自动分类 智能回复”做成端到端 Demo加入人工审批节点模拟真实流程为目标系统设计评估集建立类似 CI/CD 的“Agent 回归测试”流程最后再考虑多 Agent 协作模式——先单后多、先显式后隐式、先简单任务再复杂编排是一条相对平滑的上手路径。我个人在这些年折腾 Agent 项目的最大体会是模型能力的天花板现在已经很高了工程化能力反而成了拉开差距的地方。谁能把不可预测的大模型行为装进可观测、可回滚、可评估的生产流程里谁才真正拥有把 Agent 变成产品的能力。沙龙结束的时候天已经暗下来。场馆里还有不少人在围着讲师交流自己项目遇到的设计难题。我整理完这些笔记后最大的感想是Agent 开发越来越像一门“工程学科”了它正在脱离提示词调优和 Demo 炫技的阶段走到真正的软件工程体系里去。你能越早用对待分布式系统的谨慎来对待 Agent你的路就会走得越稳。