AutoGen 这名字圈内搞 AI Agent 的朋友应该不陌生了。如果你还没接触过我尽量用一句话说清楚它是微软开源的一个多 Agent 对话框架核心思路不是让你写死一套调用流程而是让多个各司其职的 Agent 通过“对话”的方式协作完成复杂任务。说白了传统程序是代码调用函数AutoGen 里是 Agent 之间互相发消息、讨论、协商、最终把活干完。我最近半年一直在帮企业客户落地这类项目最大的感受是AutoGen 官方文档里的例子虽然跑得通但离“企业能用”还有很长一段距离。真正上生产环境你几乎不可能直接拿默认的 AssistantAgent 去怼业务必须做大量的自定义改造——从提示词、工具注册、记忆机制到安全审计每一层都得按企业自己的需求去定制。这篇博文我就围绕“自定义代理”和“协作网络”这两个核心点把我实际踩过的坑、验证过的方案、以及背后为什么要这么设计的逻辑完整地梳理一遍。不管你是刚开始接触 Agent 开发还是已经在用 AutoGen 做原型这篇文章都值得你花十分钟看完。1. 为什么企业级 Agent 项目需要对 AutoGen 做“自定义”改造1.1 先搞清 AutoGen 的 Agent 协作模型到底是什么AutoGen 底层抽象出来一个非常核心的类叫ConversableAgent中文可以理解成“可对话代理”。你见到的所有 Agent不管是助理、用户代理还是各种自定义角色本质上都是这个类的子类或实例。它最牛的地方在于Agent 之间可以通过自然语言对话来协调工作而不是靠硬编码的调用关系。举个例子官方库里有两种开箱即用的 AgentAssistantAgent扮演“智囊”角色使用 LLM 生成回复负责分析问题、提出方案、生成代码。UserProxyAgent扮演“执行者”角色可以模拟人类去执行代码、调用工具也可以把控制权交还给真正的人类用户。这两个 Agent 一旦组队就能形成经典的双 Agent 协作模式。UserProxyAgent 把任务抛给 AssistantAgentAssistantAgent 负责思考并给出行动建议UserProxyAgent 去执行执行结果再反馈给 AssistantAgent如此循环直到任务收敛。这套模型的精妙之处在于协作的“流程编排”是隐式的是通过对话动态涌现出来的而不是预先写死 if-else 分支。这就给处理开放性问题提供了极大的灵活性。不过灵活也意味着失控的风险更大。默认的 AssistantAgent 是个通用助手它在真实企业场景里会遇到大量水土不服的问题。1.2 默认 Agent 为什么不能直接上生产我刚接触 AutoGen 的时候也犯过天真以为把业务提示词塞进 System Prompt 就能交付了。直到被客户现场打脸才发现默认 Agent 在企业场景下有这么几个硬伤第一默认 Agent 没有企业身份和边界意识。它对“哪些事归自己管、哪些事必须上报、哪些数据能碰、哪些数据绝对不能碰”完全没有概念。你问它一个跨部门的问题它大概率会一本正经地越权回答而不是告诉你该找哪个流程。第二默认的回复循环没有收敛保障。两个 Agent 如果上下文里没有一个明确的“终止条件”它们可以围绕着同一个问题来回拉扯几十轮Token 烧掉一大截问题还悬而未决。企业可不是实验室每一分钱都要算到成本里。第三默认 Agent 没有记忆。上下文窗口一旦超出限制它就“失忆”了。企业场景里的任务往往有状态、有上下文、有历史工单需要追溯一个无状态 Agent 根本没法支撑。第四默认 Agent 缺少审计痕迹。出了问题你怎么跟老板交代这个决策是哪个 Agent 在什么上下文里做出的工具调用输出了什么如果不做自定义改写这些全都没有。所以把 AutoGen 用到企业里第一步就是抛弃“开箱即用”的幻想老老实实地做自定义代理开发。这不是因为框架不行恰恰是因为框架把底层交互能力给你留好了上层的业务逻辑、安全边界、记忆能力和终止策略才需要你下功夫。2. 自定义代理与协作网络的架构设计思路2.1 按业务角色划分 Agent而不是按功能划分我见过很多初学者的做法先按功能拆 Agent比如“写代码的 Agent”“写文档的 Agent”“查数据库的 Agent”。这种拆法听起来合理实际落地时边界非常模糊Agent 之间职责重叠协作起来互相扯皮。我更推荐的方式是按业务流程中的角色来拆。一个 Agent 对应一个清晰的角色这个角色有明确的目标、有专属的工具箱、有明确的输出契约。角色拆清楚了协作网络的分工自然就清晰了。拿我最近做的一个企业 IT 工单处理场景举例我拆了四个角色需求解析 Agent负责接住用户原始诉求可能是自然语言也可能是截图描述把它解析成结构化任务提取出关键字段设备类型、故障现象、紧急程度、影响范围。知识库检索 Agent专门负责在企业内部知识库、历史工单库、设备台账里检索相关信息为后续决策提供依据。执行 Agent负责真正动手解决问题比如远程执行一个诊断脚本、下发一条配置指令、或者调用 CMDB 接口查询资产信息。质检 Agent负责检查执行结果是否真的解决了问题判断标准是否达成如果不达标则打回重做。每个角色配一个自定义 Agent每个 Agent 的 System Prompt 里写死角色定位、职责边界、语气规范、输出格式要求。这样做的好处有三点一是每个 Agent 的上下文窗口不会被无关信息污染专注度更高二是出问题的时候能精确定位到是哪个环节掉了链子三是后续做扩展的时候新增一个角色不影响其他 Agent 的既有逻辑。2.2 对话拓扑一对一、GroupChat 还是嵌套对话角色定下来之后下一步要考虑这些 Agent 之间怎么对话。AutoGen 支持三种主流协作拓扑各有各的适用场景拓扑结构实现方式适用场景优点缺点一对一对话两个 Agent 直接收发消息任务边界清晰两个角色来回配合即可完成简单可控易于追踪处理复杂任务能力有限GroupChat 群聊多个 Agent 进入一个群由 Manager 调度发言顺序任务需要多个角色轮番参与、多轮讨论灵活度高能承载复杂协作容易出现废话轮次或循环需要调参嵌套对话一个 Agent 内部再启动一个子对话群父任务需要拆分成子任务独立处理分层清晰符合金字塔原理实现复杂度高调试难度大企业在第一个版本里我建议先从 GroupChat 开始因为它最贴合真实工作中的“开会协作”模式。Manager群聊管理员在里面扮演的就是“会议主持人”的角色。GroupChat 里最关键的参数叫speaker_selection_method它决定了下一轮让谁发言。我实测下来的建议是如果各个 Agent 角色边界清晰、系统提示词写得好用默认的auto模式问题不大但如果你的场景里频繁出现 Agent 抢话或者没人接话的情况就改成round_robin按固定顺序轮流发言牺牲一点灵活性换稳定性。另外还有一个max_round参数这玩意就是个安全网我建议无论如何都要设一个防止 Agent 们讨论到天荒地老。2.3 用 Function Calling 把企业系统接进 Agent 网络一个只能在对话里“纸上谈兵”的 Agent 对企业没什么价值真正的价值在于让它具备“行动力”。AutoGen 的 Agent 可以通过注册函数来获得调用外部系统能力这就是热词里常说的 “Function Calling” 或“工具调用”。我的一些客户私下里管这批注册函数叫 Agent 的“技能包”Skill。在设计技能包时我的原则是单一职责、幂等优先、参数显式化。单一职责一个函数只做一件事。比如“查询工单状态”和“创建工单”必须拆成两个函数不要图省事合成一个“处理工单”。幂等优先同一个参数调用两次结果应该一致不能重复创建资源。这对防止 Agent 误操作至关重要。参数显式化函数入参尽量是扁平化的基本类型不要传一个大的 JSON 对象让 Agent 自己猜。Agent 对复杂嵌套结构的理解能力远不如对显式字段的理解能力。你把这些技能包绑定到对应的 Agent 上然后这个 Agent 就从一个“纯聊天的嘴”变成了“能干活的手”。企业里的自定义代理很大一部分自定义工作就集中在这一层。3. 从零实现打造一个企业 IT 工单处理的 Agent 协作网络概念讲再多不如跑一个真实的例子。这一节我会把上面说的思路落地成代码用 AutoGen 搭建一个简化版的企业 IT 工单自动处理协作网络。这个例子包含了需求解析、知识库查询、执行解决、结果质检四个环节足够覆盖绝大多数企业场景的套路。3.1 环境准备与基础配置第一步安装依赖库。AutoGen 官方包名是pyautogen建议用 Python 3.9 以上的版本。pip install pyautogen接下来是配置 LLM。AutoGen 本身是模型无关的只要你的模型厂商提供 OpenAI 兼容的接口就能接入。我在这套示例里用了 OpenAI 兼容配置你实际部署时可以根据企业现有的模型资源来填。import autogen # 定义 LLM 配置 # 注意这里用的是 OpenAI 兼容接口示例企业内部部署的模型也可以 llm_config { config_list: [ { model: your-model-name, api_key: your-api-key, base_url: https://your-endpoint.example.com/v1, } ], temperature: 0.1, # 企业场景我倾向低温减少幻觉 timeout: 300, # Agent 一次完整调用最长等待时间 }这里的temperature我特意说一下。很多人习惯默认 0.7 或者 1.0这在创意场景没问题但在企业工单处理这种偏确定性、偏严谨的场景里我强烈建议降到 0.1 左右。低温输出更稳定更少自由发挥这对后续解析 Agent 输出结果非常关键。3.2 自定义两个核心 Agent需求解析员与执行工程师整个协作网络里有几个 Agent 是骨架级别的。第一个是“需求解析 Agent”它不负责动手只负责把工单内容理解透并输出结构化信息。dispatcher autogen.AssistantAgent( name需求解析员, system_message( 你是企业 IT 工单系统的需求解析员。你的唯一职责是理解用户的工单内容 提取出以下字段设备编号、故障类型、故障描述、紧急程度。 如果信息不完整你必须明确列出缺失项不得自行猜测。 你只输出 JSON 格式的结构化结果不要输出任何多余的解释。 ), llm_configllm_config, )注意这里的system_message我从一开始就给它划定了非常明确的边界“只输出 JSON”这就为下游 Agent 省去了大量解析自然语言的痛苦。很多 Agent 项目死在“输出格式不稳定”上根子就是系统指令里没有强制约定输出协议。第二个是“执行 Agent”它负责调用工具库里的函数真正去操作工单系统。executor autogen.AssistantAgent( name执行工程师, system_message( 你是企业 IT 工单系统的执行工程师。你负责根据需求解析员提供的结构化任务信息 依次调用工具函数完成工单处理。每次工具调用后你必须检查返回结果 如果结果中 status 字段为 success则总结执行情况如果为 failed 则分析原因并尝试换一种工具或参数重试最多重试 2 次。 你不得修改任何与当前工单无关的数据。 ), llm_configllm_config, )这里你可能会疑惑为什么不用UserProxyAgent来当执行者因为我希望执行环节也由 LLM 来主导决策而不是把执行权交给一个“模拟人类操作”的代理。在企业场景里纯自动化的执行链路更可控也更好审计。如果你希望关键步骤必须有人工确认那确实应该考虑UserProxyAgent的human_input_mode参数这个我后面会展开讲。3.3 注册企业工具让 Agent 真正具备“行动力”执行工程师不能空说白话它得能调用真实的企业系统接口。这里我用两个模拟函数来演示实际项目里你只需要把这些函数改成对真实 REST API 或 RPC 的调用即可。def query_asset(device_id: str) - dict: 根据设备编号查询资产台账信息。 返回设备的基础配置、保修状态、所属部门等信息。 # 实际项目中这里应调用 CMDB 查询接口 asset_table { DVC-001: {name: 笔记本, model: ThinkPad X1, warranty: in, dept: 市场部}, DVC-002: {name: 台式机, model: OptiPlex 7090, warranty: expired, dept: 财务部}, } return asset_table.get(device_id, {error: 设备编号不存在}) def create_ticket(device_id: str, fault_type: str, description: str, urgency: str) - dict: 在工单系统中创建一条新的维修工单。 # 实际项目中这里应调用工单系统的创建接口 ticket_id fTCK-{hash(device_id fault_type urgency) % 10000} return { ticket_id: ticket_id, device_id: device_id, status: created, message: f工单创建成功编号 {ticket_id}, }把这两个函数注册给执行 Agent这一步是 AutoGen 里比较魔幻的操作注册之后Agent 在决定“下一步该做什么”的时候会自己尝试去匹配函数参数并调用。executor.register_for_llm( namequery_asset, description根据设备编号查询资产台账信息返回设备配置与维保状态。, funcquery_asset, ) executor.register_for_llm( namecreate_ticket, description在工单系统中创建维修工单返回工单编号。, funccreate_ticket, )这里我要提醒一个新手必踩的坑函数描述必须写清楚“什么时候用、传什么参数、返回什么”。LLM 对函数的理解完全靠你给的description描述写得含糊它就会瞎猜。比如你写“查询设备信息”它就不知道是查资产信息还是查故障信息参数匹配也容易出错。我通常会在描述里把适用场景、参数约束、返回值含义都写全。注册完之后还有一个关键动作允许 Agent 真正去执行这些函数。AutoGen 里AssistantAgent默认只是“建议”调用函数真正执行要到UserProxyAgent或把执行权交出去。这里我用一个小技巧把executor同时注册为可执行函数的主体。3.4 用 GroupChat 把多个 Agent 编排成协作网络单靠两个 Agent 还不够我把需求解析员、知识库检索员这里简化略过、执行工程师、质检员组了个群用 GroupChat 进行统一调度。quality_checker autogen.AssistantAgent( name质检员, system_message( 你是质检员。你负责检查执行工程师的工单处理结果。 你要核对工单编号是否存在、执行结果是否为 success、紧急程度是否标注正确。 只有所有检查项通过才输出 APPROVED否则输出 REJECTED 并附带原因。 ), llm_configllm_config, )然后组建群聊和管理者groupchat autogen.GroupChat( agents[dispatcher, executor, quality_checker], messages[], max_round20, speaker_selection_methodauto, ) manager autogen.GroupChatManager( groupchatgroupchat, llm_configllm_config, name工单调度员, )max_round20是我给这场“会议”设的上限。企业场景里我不是很放心让它们无限聊下去20 轮足够完成一次标准的工单处理流程了要是 20 轮还没收敛基本说明设计有问题不如直接停下来报警。启动整个网络也很简单user_proxy autogen.UserProxyAgent( name工单发起人, human_input_modeTERMINATE, max_consecutive_auto_reply2, is_termination_msglambda x: APPROVED in x.get(content, ), ) result user_proxy.initiate_chat( manager, message设备 DVC-001 开机蓝屏紧急程度高需要尽快处理。, )这里有个细节需要解释一下is_termination_msg我设置的是“只要对话里出现 APPROVED 就终止”。这相当于给整个 Agent 协作网络设了一个明确的“会议结束信号”。如果没有这个信号质检员说完 APPROVED 之后其他 Agent 可能还会继续寒暄几句白白浪费 Token。跑完这段代码你会看到控制台里几个 Agent 就像几个同事在讨论一样你一言我一语最终输出了一个工单编号和一份简洁的处理说明。这个框架的魅力在此刻就体现得淋漓尽致。4. 企业级 Agent 的记忆、状态与持久化4.1 上下文窗口不等于记忆很多初学 Agent 开发的人有一个错觉只要模型上下文窗口够大Agent 就不需要记忆机制。这个观点在 Demo 阶段成立到企业生产环境就绷不住了。原因有二。第一上下文窗口再大也是有限的而企业业务数据是持续增长的你不可能把一个项目半年的工单历史、知识文档全部塞进上下文。第二成本是线性的Token 量越大每次调用的延迟和费用就越高。你需要的是“记忆”是把历史信息浓缩成结构化的知识而不是把原始日志原封不动回放。我在做 AutoGen 项目时对记忆的处理分成三层短期记忆利用 Agent 自身上下文窗口保留本轮对话内的重要信息。中期记忆通过对话摘要实现。AutoGen 有SummarizableAgent的雏形思路实际中我通常在每轮对话结束后额外调用一次 LLM 把关键决策点抽取出来存进一个结构化的 JSON 里。长期记忆把摘要、实体关系、决策记录写进向量数据库在下一次任务启动时检索注入上下文。4.2 用向量库做长期记忆的实践举个例子执行工程师处理过一批“设备蓝屏”的工单它总结了这类故障多半是显卡驱动问题。如果没有长期记忆下次再来一个“设备花屏”的工单它还得重新摸索一遍。如果有了向量库它一检索就能发现“蓝屏/花屏/驱动异常”这些关键词在历史上有关联直接复用上一次的解决策略效率会高很多。我常用的做法是在每次工单处理结束后由质检员写一段结构化摘要交给一个“记忆写入函数”来向量化并存入向量库。下次任何 Agent 在处理新工单时“记忆检索函数”会根据当前任务描述做相似度匹配把最相关的前三条记忆注入到对应 Agent 的上下文里。这个做法的核心收益是Agent 在同一类问题上会越用越聪明这种“经验积累”能力恰恰是企业愿意为 Agent 付费的重要原因。4.3 任务状态持久化工单编号、审批状态怎么跨会话保存还有一个非常务实的点Agent 协作网络不能只活在内存里。工单创建了、审批到一半、系统重启了这些业务状态必须落地到数据库。我在实际项目中踩过一个很痛的大坑早期版本我把工单状态直接放在 GroupChat 的 messages 列表里以为只要会话不关就没问题。结果有一次业务方对系统做发布升级所有运行中的 Agent 会话全部中断正在处理的十几张工单状态全部丢失被业务部门骂得狗血淋头。所以请记住一条铁律对话上下文是易失的业务状态必须持久化。Agent 每次工具调用的结果只要涉及订单号、工单号、审批ID这类业务主键一定要同步写进业务数据库。GroupChat 里的消息记录可以视为推导过程日志而不能作为业务系统的数据源。这个认知对做企业级 Agent 的人来说怎么强调都不为过。5. 企业落地必须面对的四个问题安全、监控、成本与性能5.1 权限与安全Agent 不能脱离管控企业在引入 Agent 时最关心的问题永远是安全。一个能调用工具的 Agent如果权限控制不好比一个普通软件 Bug 危险得多。我的安全设计原则是这样的Agent 能调用的工具必须显式授权Agent 能接触的数据必须最小化授权Agent 的每一个高风险动作必须有人工确认。在 AutoGen 里这体现在注册函数时就要区分“只读函数”和“写函数”。查询类函数可以直接交给 Agent 自动调用而创建工单、发送通知、修改配置这类写操作建议挂到UserProxyAgent的human_input_modeALWAYS上强制人工确认。系统提示词里要明确告诉 Agent哪些字段属于敏感数据比如员工薪资信息在任何情况下都不得写入系统日志。模型输出要做过滤。LLM 有可能在生成结果时“自由发挥”带出不该说的内容建议在 Agent 外层挂一个敏感信息过滤服务对输出做一轮正则语义双层扫描。5.2 可观测性与审计你怎么证明 Agent 做了正确的事企业上线一个系统不只是看功能好不好用更要看出了问题能不能追溯。Agent 的黑盒特性会让审计变得异常困难所以从第一天起就要把可观测性设计进去。我要求每个项目至少保留三类日志对话轨迹日志记录所有 Agent 之间的完整消息记录包括时间戳、发言 Agent、内容摘要。AutoGen 的groupchat.messages可以完整导出我通常每结束一个任务就落一份 JSON 存档。工具调用日志记录哪个 Agent、在什么上下文里、调用了哪个函数、传了什么参数、返回了什么结果。这一步对排查 Agent 的“不当行为”至关重要。决策与成本日志记录每次 LLM 调用的 Token 消耗、响应耗时、模型版本。有了这三类日志你才能在出问题的时候向领导和客户解释清楚这个 Agent 当时“看到了什么、想了什么、做了什么”。5.3 Token 成本与响应性能怎么平衡企业项目绕不开成本。很多人在 Demo 阶段不在乎 Token因为数据量小等上了生产一天上万次调用成本就显形了。我的成本控制三板斧控制上下文长度、优化模型选型、设置并发限制。起来很简单做起来有讲究。上下文长度方面我每次检索注入给 Agent 的内容控制在 2K Token 以内只给结论和必要的数据不给原始大文本。模型选型方面不是所有 Agent 都需要 GPT-4 级别的模型。像需求解析员这种只做信息抽取的用一个中档模型完全够像质检员这种需要综合判断的再用高档模型。为了平衡使用成本并发限制也要提前规划好避免某个任务畸形消耗大量并发资源导致成本失控。给你算一笔账假设一次完整工单处理任务平均消耗 8K Token一天处理 500 个工单就是 4M Token。如果用比较贵的模型按输入输出综合价估一天可能去到数百元如果其中一半角色切到便宜模型成本能降 40% 以上。这个账在企业采购决策里比你写多漂亮的架构文档都管用。6. 实操中高频踩坑点与排查建议6.1 GroupChat 死循环与低效发言这是我被问得最多的问题几个 Agent 聊着聊着就陷入了重复发言的死循环或者某个 Agent 频繁刷屏说些“你说得对我同意”之类的废话。排查思路先看max_round如果每次都触顶说明流程没有收敛。检查is_termination_msg是否设置正确。再检查speaker_selection_method。如果auto模式下某个话痨 Agent 总被选中可以考虑限制它的发言次数或者干脆轮询。最后检查 System Prompt 里的“职责边界”。如果两个 Agent 职责重叠它们会互相客气属于典型的角色定义不清晰。6.2 Function Calling 参数错乱LLM 在调用函数时偶尔会生成不存在的参数名或者把参数类型传错。比如你定义device_id: str它给你传了一个{id: ...}这样的嵌套结构。解决办法函数签名尽量用简单的字符串和数字不要用复杂对象在注册函数时给 description 里加上参数示例同时在函数内部做好参数校验不合法直接返回错误信息让 Agent 自己去感知并重试。千万不要假设 LLM 一定会乖乖按你的 schema 传参。6.3 长会话上下文膨胀GroupChat 跑久了messages 列表会越来越长。一次性全部塞给 LLM轻则延迟变大重则直接超出窗口报错。解决思路是给 GroupChat 配一个“摘要机制”。我的做法是每跑完一个阶段就调用一次独立的 LLM 把此前的对话压缩成 200 字左右的摘要然后清空原始消息后续的对话基于摘要继续。这在大任务拆分中尤其好用。6.4 多 Agent 并发时的资源竞争当你的系统同时跑多个工单任务时多个 GroupChat 会并发调用相同的工具函数。如果你没做好幂等控制就可能出现重复建单、重复扣减库存的问题。所以在工具层设计上我强烈建议所有写操作都要带一个业务唯一键比如调用方传入request_id服务端做幂等判断。这是企业级应用的基本功在 Agent 场景里更是不能偷懒。6.5 快速排查表现象可能原因处理建议对话无限循环缺少终止信号或职责边界模糊设置 is_termination_msg检查角色定位Agent 总不回话模型上下文过长或温度过低压缩上文适度调整 temperature函数调用报错参数不合法或描述不清晰简化签名校验入参补全描述输出格式不稳定System Prompt 约束不足强制输出协议必要时用代码解析兜底工具直接被跳过Agent 认为不需要工具或函数未注册检查注册方法在提示词中强调工具可用产出结果与预期不符检索记忆被噪声干扰优化记忆检索的相似度阈值和排序逻辑写在最后老生常谈的经验回到开头的话题AutoGen 这类 Agent 框架其实不缺“能跑起来”的教程缺的是“能在企业里站得住脚”的工程化经验。我带过好几个项目最大的体会是最花时间的不是写 Agent 代码而是把业务流程梳理清楚把每个 Agent 的边界定义清楚把安全与审计机制设计妥当。如果只能给你留三个问题去衡量你自己的 Agent 设计是否合格那就是这个 Agent 的目标是什么它能调用什么工具什么情况下它必须停下来找人类这三个问题想透了你的自定义代理协作网络就不会跑偏。至于框架本身的 API 细节翻翻官方文档就能解决但架构思维和工程意识才是真正值钱的部分。
AutoGen 自定义代理与协作网络：企业级多 Agent 落地实战指南
AutoGen 这名字圈内搞 AI Agent 的朋友应该不陌生了。如果你还没接触过我尽量用一句话说清楚它是微软开源的一个多 Agent 对话框架核心思路不是让你写死一套调用流程而是让多个各司其职的 Agent 通过“对话”的方式协作完成复杂任务。说白了传统程序是代码调用函数AutoGen 里是 Agent 之间互相发消息、讨论、协商、最终把活干完。我最近半年一直在帮企业客户落地这类项目最大的感受是AutoGen 官方文档里的例子虽然跑得通但离“企业能用”还有很长一段距离。真正上生产环境你几乎不可能直接拿默认的 AssistantAgent 去怼业务必须做大量的自定义改造——从提示词、工具注册、记忆机制到安全审计每一层都得按企业自己的需求去定制。这篇博文我就围绕“自定义代理”和“协作网络”这两个核心点把我实际踩过的坑、验证过的方案、以及背后为什么要这么设计的逻辑完整地梳理一遍。不管你是刚开始接触 Agent 开发还是已经在用 AutoGen 做原型这篇文章都值得你花十分钟看完。1. 为什么企业级 Agent 项目需要对 AutoGen 做“自定义”改造1.1 先搞清 AutoGen 的 Agent 协作模型到底是什么AutoGen 底层抽象出来一个非常核心的类叫ConversableAgent中文可以理解成“可对话代理”。你见到的所有 Agent不管是助理、用户代理还是各种自定义角色本质上都是这个类的子类或实例。它最牛的地方在于Agent 之间可以通过自然语言对话来协调工作而不是靠硬编码的调用关系。举个例子官方库里有两种开箱即用的 AgentAssistantAgent扮演“智囊”角色使用 LLM 生成回复负责分析问题、提出方案、生成代码。UserProxyAgent扮演“执行者”角色可以模拟人类去执行代码、调用工具也可以把控制权交还给真正的人类用户。这两个 Agent 一旦组队就能形成经典的双 Agent 协作模式。UserProxyAgent 把任务抛给 AssistantAgentAssistantAgent 负责思考并给出行动建议UserProxyAgent 去执行执行结果再反馈给 AssistantAgent如此循环直到任务收敛。这套模型的精妙之处在于协作的“流程编排”是隐式的是通过对话动态涌现出来的而不是预先写死 if-else 分支。这就给处理开放性问题提供了极大的灵活性。不过灵活也意味着失控的风险更大。默认的 AssistantAgent 是个通用助手它在真实企业场景里会遇到大量水土不服的问题。1.2 默认 Agent 为什么不能直接上生产我刚接触 AutoGen 的时候也犯过天真以为把业务提示词塞进 System Prompt 就能交付了。直到被客户现场打脸才发现默认 Agent 在企业场景下有这么几个硬伤第一默认 Agent 没有企业身份和边界意识。它对“哪些事归自己管、哪些事必须上报、哪些数据能碰、哪些数据绝对不能碰”完全没有概念。你问它一个跨部门的问题它大概率会一本正经地越权回答而不是告诉你该找哪个流程。第二默认的回复循环没有收敛保障。两个 Agent 如果上下文里没有一个明确的“终止条件”它们可以围绕着同一个问题来回拉扯几十轮Token 烧掉一大截问题还悬而未决。企业可不是实验室每一分钱都要算到成本里。第三默认 Agent 没有记忆。上下文窗口一旦超出限制它就“失忆”了。企业场景里的任务往往有状态、有上下文、有历史工单需要追溯一个无状态 Agent 根本没法支撑。第四默认 Agent 缺少审计痕迹。出了问题你怎么跟老板交代这个决策是哪个 Agent 在什么上下文里做出的工具调用输出了什么如果不做自定义改写这些全都没有。所以把 AutoGen 用到企业里第一步就是抛弃“开箱即用”的幻想老老实实地做自定义代理开发。这不是因为框架不行恰恰是因为框架把底层交互能力给你留好了上层的业务逻辑、安全边界、记忆能力和终止策略才需要你下功夫。2. 自定义代理与协作网络的架构设计思路2.1 按业务角色划分 Agent而不是按功能划分我见过很多初学者的做法先按功能拆 Agent比如“写代码的 Agent”“写文档的 Agent”“查数据库的 Agent”。这种拆法听起来合理实际落地时边界非常模糊Agent 之间职责重叠协作起来互相扯皮。我更推荐的方式是按业务流程中的角色来拆。一个 Agent 对应一个清晰的角色这个角色有明确的目标、有专属的工具箱、有明确的输出契约。角色拆清楚了协作网络的分工自然就清晰了。拿我最近做的一个企业 IT 工单处理场景举例我拆了四个角色需求解析 Agent负责接住用户原始诉求可能是自然语言也可能是截图描述把它解析成结构化任务提取出关键字段设备类型、故障现象、紧急程度、影响范围。知识库检索 Agent专门负责在企业内部知识库、历史工单库、设备台账里检索相关信息为后续决策提供依据。执行 Agent负责真正动手解决问题比如远程执行一个诊断脚本、下发一条配置指令、或者调用 CMDB 接口查询资产信息。质检 Agent负责检查执行结果是否真的解决了问题判断标准是否达成如果不达标则打回重做。每个角色配一个自定义 Agent每个 Agent 的 System Prompt 里写死角色定位、职责边界、语气规范、输出格式要求。这样做的好处有三点一是每个 Agent 的上下文窗口不会被无关信息污染专注度更高二是出问题的时候能精确定位到是哪个环节掉了链子三是后续做扩展的时候新增一个角色不影响其他 Agent 的既有逻辑。2.2 对话拓扑一对一、GroupChat 还是嵌套对话角色定下来之后下一步要考虑这些 Agent 之间怎么对话。AutoGen 支持三种主流协作拓扑各有各的适用场景拓扑结构实现方式适用场景优点缺点一对一对话两个 Agent 直接收发消息任务边界清晰两个角色来回配合即可完成简单可控易于追踪处理复杂任务能力有限GroupChat 群聊多个 Agent 进入一个群由 Manager 调度发言顺序任务需要多个角色轮番参与、多轮讨论灵活度高能承载复杂协作容易出现废话轮次或循环需要调参嵌套对话一个 Agent 内部再启动一个子对话群父任务需要拆分成子任务独立处理分层清晰符合金字塔原理实现复杂度高调试难度大企业在第一个版本里我建议先从 GroupChat 开始因为它最贴合真实工作中的“开会协作”模式。Manager群聊管理员在里面扮演的就是“会议主持人”的角色。GroupChat 里最关键的参数叫speaker_selection_method它决定了下一轮让谁发言。我实测下来的建议是如果各个 Agent 角色边界清晰、系统提示词写得好用默认的auto模式问题不大但如果你的场景里频繁出现 Agent 抢话或者没人接话的情况就改成round_robin按固定顺序轮流发言牺牲一点灵活性换稳定性。另外还有一个max_round参数这玩意就是个安全网我建议无论如何都要设一个防止 Agent 们讨论到天荒地老。2.3 用 Function Calling 把企业系统接进 Agent 网络一个只能在对话里“纸上谈兵”的 Agent 对企业没什么价值真正的价值在于让它具备“行动力”。AutoGen 的 Agent 可以通过注册函数来获得调用外部系统能力这就是热词里常说的 “Function Calling” 或“工具调用”。我的一些客户私下里管这批注册函数叫 Agent 的“技能包”Skill。在设计技能包时我的原则是单一职责、幂等优先、参数显式化。单一职责一个函数只做一件事。比如“查询工单状态”和“创建工单”必须拆成两个函数不要图省事合成一个“处理工单”。幂等优先同一个参数调用两次结果应该一致不能重复创建资源。这对防止 Agent 误操作至关重要。参数显式化函数入参尽量是扁平化的基本类型不要传一个大的 JSON 对象让 Agent 自己猜。Agent 对复杂嵌套结构的理解能力远不如对显式字段的理解能力。你把这些技能包绑定到对应的 Agent 上然后这个 Agent 就从一个“纯聊天的嘴”变成了“能干活的手”。企业里的自定义代理很大一部分自定义工作就集中在这一层。3. 从零实现打造一个企业 IT 工单处理的 Agent 协作网络概念讲再多不如跑一个真实的例子。这一节我会把上面说的思路落地成代码用 AutoGen 搭建一个简化版的企业 IT 工单自动处理协作网络。这个例子包含了需求解析、知识库查询、执行解决、结果质检四个环节足够覆盖绝大多数企业场景的套路。3.1 环境准备与基础配置第一步安装依赖库。AutoGen 官方包名是pyautogen建议用 Python 3.9 以上的版本。pip install pyautogen接下来是配置 LLM。AutoGen 本身是模型无关的只要你的模型厂商提供 OpenAI 兼容的接口就能接入。我在这套示例里用了 OpenAI 兼容配置你实际部署时可以根据企业现有的模型资源来填。import autogen # 定义 LLM 配置 # 注意这里用的是 OpenAI 兼容接口示例企业内部部署的模型也可以 llm_config { config_list: [ { model: your-model-name, api_key: your-api-key, base_url: https://your-endpoint.example.com/v1, } ], temperature: 0.1, # 企业场景我倾向低温减少幻觉 timeout: 300, # Agent 一次完整调用最长等待时间 }这里的temperature我特意说一下。很多人习惯默认 0.7 或者 1.0这在创意场景没问题但在企业工单处理这种偏确定性、偏严谨的场景里我强烈建议降到 0.1 左右。低温输出更稳定更少自由发挥这对后续解析 Agent 输出结果非常关键。3.2 自定义两个核心 Agent需求解析员与执行工程师整个协作网络里有几个 Agent 是骨架级别的。第一个是“需求解析 Agent”它不负责动手只负责把工单内容理解透并输出结构化信息。dispatcher autogen.AssistantAgent( name需求解析员, system_message( 你是企业 IT 工单系统的需求解析员。你的唯一职责是理解用户的工单内容 提取出以下字段设备编号、故障类型、故障描述、紧急程度。 如果信息不完整你必须明确列出缺失项不得自行猜测。 你只输出 JSON 格式的结构化结果不要输出任何多余的解释。 ), llm_configllm_config, )注意这里的system_message我从一开始就给它划定了非常明确的边界“只输出 JSON”这就为下游 Agent 省去了大量解析自然语言的痛苦。很多 Agent 项目死在“输出格式不稳定”上根子就是系统指令里没有强制约定输出协议。第二个是“执行 Agent”它负责调用工具库里的函数真正去操作工单系统。executor autogen.AssistantAgent( name执行工程师, system_message( 你是企业 IT 工单系统的执行工程师。你负责根据需求解析员提供的结构化任务信息 依次调用工具函数完成工单处理。每次工具调用后你必须检查返回结果 如果结果中 status 字段为 success则总结执行情况如果为 failed 则分析原因并尝试换一种工具或参数重试最多重试 2 次。 你不得修改任何与当前工单无关的数据。 ), llm_configllm_config, )这里你可能会疑惑为什么不用UserProxyAgent来当执行者因为我希望执行环节也由 LLM 来主导决策而不是把执行权交给一个“模拟人类操作”的代理。在企业场景里纯自动化的执行链路更可控也更好审计。如果你希望关键步骤必须有人工确认那确实应该考虑UserProxyAgent的human_input_mode参数这个我后面会展开讲。3.3 注册企业工具让 Agent 真正具备“行动力”执行工程师不能空说白话它得能调用真实的企业系统接口。这里我用两个模拟函数来演示实际项目里你只需要把这些函数改成对真实 REST API 或 RPC 的调用即可。def query_asset(device_id: str) - dict: 根据设备编号查询资产台账信息。 返回设备的基础配置、保修状态、所属部门等信息。 # 实际项目中这里应调用 CMDB 查询接口 asset_table { DVC-001: {name: 笔记本, model: ThinkPad X1, warranty: in, dept: 市场部}, DVC-002: {name: 台式机, model: OptiPlex 7090, warranty: expired, dept: 财务部}, } return asset_table.get(device_id, {error: 设备编号不存在}) def create_ticket(device_id: str, fault_type: str, description: str, urgency: str) - dict: 在工单系统中创建一条新的维修工单。 # 实际项目中这里应调用工单系统的创建接口 ticket_id fTCK-{hash(device_id fault_type urgency) % 10000} return { ticket_id: ticket_id, device_id: device_id, status: created, message: f工单创建成功编号 {ticket_id}, }把这两个函数注册给执行 Agent这一步是 AutoGen 里比较魔幻的操作注册之后Agent 在决定“下一步该做什么”的时候会自己尝试去匹配函数参数并调用。executor.register_for_llm( namequery_asset, description根据设备编号查询资产台账信息返回设备配置与维保状态。, funcquery_asset, ) executor.register_for_llm( namecreate_ticket, description在工单系统中创建维修工单返回工单编号。, funccreate_ticket, )这里我要提醒一个新手必踩的坑函数描述必须写清楚“什么时候用、传什么参数、返回什么”。LLM 对函数的理解完全靠你给的description描述写得含糊它就会瞎猜。比如你写“查询设备信息”它就不知道是查资产信息还是查故障信息参数匹配也容易出错。我通常会在描述里把适用场景、参数约束、返回值含义都写全。注册完之后还有一个关键动作允许 Agent 真正去执行这些函数。AutoGen 里AssistantAgent默认只是“建议”调用函数真正执行要到UserProxyAgent或把执行权交出去。这里我用一个小技巧把executor同时注册为可执行函数的主体。3.4 用 GroupChat 把多个 Agent 编排成协作网络单靠两个 Agent 还不够我把需求解析员、知识库检索员这里简化略过、执行工程师、质检员组了个群用 GroupChat 进行统一调度。quality_checker autogen.AssistantAgent( name质检员, system_message( 你是质检员。你负责检查执行工程师的工单处理结果。 你要核对工单编号是否存在、执行结果是否为 success、紧急程度是否标注正确。 只有所有检查项通过才输出 APPROVED否则输出 REJECTED 并附带原因。 ), llm_configllm_config, )然后组建群聊和管理者groupchat autogen.GroupChat( agents[dispatcher, executor, quality_checker], messages[], max_round20, speaker_selection_methodauto, ) manager autogen.GroupChatManager( groupchatgroupchat, llm_configllm_config, name工单调度员, )max_round20是我给这场“会议”设的上限。企业场景里我不是很放心让它们无限聊下去20 轮足够完成一次标准的工单处理流程了要是 20 轮还没收敛基本说明设计有问题不如直接停下来报警。启动整个网络也很简单user_proxy autogen.UserProxyAgent( name工单发起人, human_input_modeTERMINATE, max_consecutive_auto_reply2, is_termination_msglambda x: APPROVED in x.get(content, ), ) result user_proxy.initiate_chat( manager, message设备 DVC-001 开机蓝屏紧急程度高需要尽快处理。, )这里有个细节需要解释一下is_termination_msg我设置的是“只要对话里出现 APPROVED 就终止”。这相当于给整个 Agent 协作网络设了一个明确的“会议结束信号”。如果没有这个信号质检员说完 APPROVED 之后其他 Agent 可能还会继续寒暄几句白白浪费 Token。跑完这段代码你会看到控制台里几个 Agent 就像几个同事在讨论一样你一言我一语最终输出了一个工单编号和一份简洁的处理说明。这个框架的魅力在此刻就体现得淋漓尽致。4. 企业级 Agent 的记忆、状态与持久化4.1 上下文窗口不等于记忆很多初学 Agent 开发的人有一个错觉只要模型上下文窗口够大Agent 就不需要记忆机制。这个观点在 Demo 阶段成立到企业生产环境就绷不住了。原因有二。第一上下文窗口再大也是有限的而企业业务数据是持续增长的你不可能把一个项目半年的工单历史、知识文档全部塞进上下文。第二成本是线性的Token 量越大每次调用的延迟和费用就越高。你需要的是“记忆”是把历史信息浓缩成结构化的知识而不是把原始日志原封不动回放。我在做 AutoGen 项目时对记忆的处理分成三层短期记忆利用 Agent 自身上下文窗口保留本轮对话内的重要信息。中期记忆通过对话摘要实现。AutoGen 有SummarizableAgent的雏形思路实际中我通常在每轮对话结束后额外调用一次 LLM 把关键决策点抽取出来存进一个结构化的 JSON 里。长期记忆把摘要、实体关系、决策记录写进向量数据库在下一次任务启动时检索注入上下文。4.2 用向量库做长期记忆的实践举个例子执行工程师处理过一批“设备蓝屏”的工单它总结了这类故障多半是显卡驱动问题。如果没有长期记忆下次再来一个“设备花屏”的工单它还得重新摸索一遍。如果有了向量库它一检索就能发现“蓝屏/花屏/驱动异常”这些关键词在历史上有关联直接复用上一次的解决策略效率会高很多。我常用的做法是在每次工单处理结束后由质检员写一段结构化摘要交给一个“记忆写入函数”来向量化并存入向量库。下次任何 Agent 在处理新工单时“记忆检索函数”会根据当前任务描述做相似度匹配把最相关的前三条记忆注入到对应 Agent 的上下文里。这个做法的核心收益是Agent 在同一类问题上会越用越聪明这种“经验积累”能力恰恰是企业愿意为 Agent 付费的重要原因。4.3 任务状态持久化工单编号、审批状态怎么跨会话保存还有一个非常务实的点Agent 协作网络不能只活在内存里。工单创建了、审批到一半、系统重启了这些业务状态必须落地到数据库。我在实际项目中踩过一个很痛的大坑早期版本我把工单状态直接放在 GroupChat 的 messages 列表里以为只要会话不关就没问题。结果有一次业务方对系统做发布升级所有运行中的 Agent 会话全部中断正在处理的十几张工单状态全部丢失被业务部门骂得狗血淋头。所以请记住一条铁律对话上下文是易失的业务状态必须持久化。Agent 每次工具调用的结果只要涉及订单号、工单号、审批ID这类业务主键一定要同步写进业务数据库。GroupChat 里的消息记录可以视为推导过程日志而不能作为业务系统的数据源。这个认知对做企业级 Agent 的人来说怎么强调都不为过。5. 企业落地必须面对的四个问题安全、监控、成本与性能5.1 权限与安全Agent 不能脱离管控企业在引入 Agent 时最关心的问题永远是安全。一个能调用工具的 Agent如果权限控制不好比一个普通软件 Bug 危险得多。我的安全设计原则是这样的Agent 能调用的工具必须显式授权Agent 能接触的数据必须最小化授权Agent 的每一个高风险动作必须有人工确认。在 AutoGen 里这体现在注册函数时就要区分“只读函数”和“写函数”。查询类函数可以直接交给 Agent 自动调用而创建工单、发送通知、修改配置这类写操作建议挂到UserProxyAgent的human_input_modeALWAYS上强制人工确认。系统提示词里要明确告诉 Agent哪些字段属于敏感数据比如员工薪资信息在任何情况下都不得写入系统日志。模型输出要做过滤。LLM 有可能在生成结果时“自由发挥”带出不该说的内容建议在 Agent 外层挂一个敏感信息过滤服务对输出做一轮正则语义双层扫描。5.2 可观测性与审计你怎么证明 Agent 做了正确的事企业上线一个系统不只是看功能好不好用更要看出了问题能不能追溯。Agent 的黑盒特性会让审计变得异常困难所以从第一天起就要把可观测性设计进去。我要求每个项目至少保留三类日志对话轨迹日志记录所有 Agent 之间的完整消息记录包括时间戳、发言 Agent、内容摘要。AutoGen 的groupchat.messages可以完整导出我通常每结束一个任务就落一份 JSON 存档。工具调用日志记录哪个 Agent、在什么上下文里、调用了哪个函数、传了什么参数、返回了什么结果。这一步对排查 Agent 的“不当行为”至关重要。决策与成本日志记录每次 LLM 调用的 Token 消耗、响应耗时、模型版本。有了这三类日志你才能在出问题的时候向领导和客户解释清楚这个 Agent 当时“看到了什么、想了什么、做了什么”。5.3 Token 成本与响应性能怎么平衡企业项目绕不开成本。很多人在 Demo 阶段不在乎 Token因为数据量小等上了生产一天上万次调用成本就显形了。我的成本控制三板斧控制上下文长度、优化模型选型、设置并发限制。起来很简单做起来有讲究。上下文长度方面我每次检索注入给 Agent 的内容控制在 2K Token 以内只给结论和必要的数据不给原始大文本。模型选型方面不是所有 Agent 都需要 GPT-4 级别的模型。像需求解析员这种只做信息抽取的用一个中档模型完全够像质检员这种需要综合判断的再用高档模型。为了平衡使用成本并发限制也要提前规划好避免某个任务畸形消耗大量并发资源导致成本失控。给你算一笔账假设一次完整工单处理任务平均消耗 8K Token一天处理 500 个工单就是 4M Token。如果用比较贵的模型按输入输出综合价估一天可能去到数百元如果其中一半角色切到便宜模型成本能降 40% 以上。这个账在企业采购决策里比你写多漂亮的架构文档都管用。6. 实操中高频踩坑点与排查建议6.1 GroupChat 死循环与低效发言这是我被问得最多的问题几个 Agent 聊着聊着就陷入了重复发言的死循环或者某个 Agent 频繁刷屏说些“你说得对我同意”之类的废话。排查思路先看max_round如果每次都触顶说明流程没有收敛。检查is_termination_msg是否设置正确。再检查speaker_selection_method。如果auto模式下某个话痨 Agent 总被选中可以考虑限制它的发言次数或者干脆轮询。最后检查 System Prompt 里的“职责边界”。如果两个 Agent 职责重叠它们会互相客气属于典型的角色定义不清晰。6.2 Function Calling 参数错乱LLM 在调用函数时偶尔会生成不存在的参数名或者把参数类型传错。比如你定义device_id: str它给你传了一个{id: ...}这样的嵌套结构。解决办法函数签名尽量用简单的字符串和数字不要用复杂对象在注册函数时给 description 里加上参数示例同时在函数内部做好参数校验不合法直接返回错误信息让 Agent 自己去感知并重试。千万不要假设 LLM 一定会乖乖按你的 schema 传参。6.3 长会话上下文膨胀GroupChat 跑久了messages 列表会越来越长。一次性全部塞给 LLM轻则延迟变大重则直接超出窗口报错。解决思路是给 GroupChat 配一个“摘要机制”。我的做法是每跑完一个阶段就调用一次独立的 LLM 把此前的对话压缩成 200 字左右的摘要然后清空原始消息后续的对话基于摘要继续。这在大任务拆分中尤其好用。6.4 多 Agent 并发时的资源竞争当你的系统同时跑多个工单任务时多个 GroupChat 会并发调用相同的工具函数。如果你没做好幂等控制就可能出现重复建单、重复扣减库存的问题。所以在工具层设计上我强烈建议所有写操作都要带一个业务唯一键比如调用方传入request_id服务端做幂等判断。这是企业级应用的基本功在 Agent 场景里更是不能偷懒。6.5 快速排查表现象可能原因处理建议对话无限循环缺少终止信号或职责边界模糊设置 is_termination_msg检查角色定位Agent 总不回话模型上下文过长或温度过低压缩上文适度调整 temperature函数调用报错参数不合法或描述不清晰简化签名校验入参补全描述输出格式不稳定System Prompt 约束不足强制输出协议必要时用代码解析兜底工具直接被跳过Agent 认为不需要工具或函数未注册检查注册方法在提示词中强调工具可用产出结果与预期不符检索记忆被噪声干扰优化记忆检索的相似度阈值和排序逻辑写在最后老生常谈的经验回到开头的话题AutoGen 这类 Agent 框架其实不缺“能跑起来”的教程缺的是“能在企业里站得住脚”的工程化经验。我带过好几个项目最大的体会是最花时间的不是写 Agent 代码而是把业务流程梳理清楚把每个 Agent 的边界定义清楚把安全与审计机制设计妥当。如果只能给你留三个问题去衡量你自己的 Agent 设计是否合格那就是这个 Agent 的目标是什么它能调用什么工具什么情况下它必须停下来找人类这三个问题想透了你的自定义代理协作网络就不会跑偏。至于框架本身的 API 细节翻翻官方文档就能解决但架构思维和工程意识才是真正值钱的部分。
