企业官网建设流程全解析

先说结论：AutoGen是我在对比了LangGraph、CrewAI、以及自研编排之后，留在生产环境里时间最长的一个多Agent框架。原因很简单：它的理解成本低、行为可观察、模型选型自由，而且天生的“对话驱动”模式特别贴近真实团队的协作方式。但我也踩过不少坑，最典型的就是两个Agent放进GroupChat之后互相捧场，十分钟都停不下来。这篇文章就把AutoGen从框架选型、环境搭建、核心概念，到生产落地的完整链路一次说清楚，适合正在学Agent开发、或者准备把AutoGen接入后端系统的工程师参考。

1. 为什么我在众多Agent框架里先选了AutoGen

1.1 多Agent开发的真实痛点

当你只有一个大模型API，想做一个“会搜索、会算数、会生成报告”的助手时，最朴素的办法是写一堆if-else把工具调用串起来。但任务一旦变成“多个角色互相配合、上下文动态变化、中途要插入人工确认”，这种流水线就立刻崩了。

多Agent框架真正要解决的，不是“单次问答有多聪明”，而是“多轮对话中状态不乱、协作不僵、结果可收敛”。AutoGen的核心主张是对话驱动编程（conversation-driven programming），把协作关系建模成一组Agent之间的消息往来。

这里有个很贴切的类比：真实团队开会，要有主持人、有负责执行的、有负责挑刺的。谁发言、谁接话、什么时候散会，都需要规则，否则会议就会变成吵架现场。AutoGen就是给你一套默认的“会议规则模板”，你只需要把角色定义好，它负责把流程跑起来。

1.2 与主流Agent框架的定位差异

我做过一轮选型对比，主流的几个Agent框架其实各有脾气，不能一概而论。

我在实际中体会比较深的一点是：如果你需要的是“每一个步骤都必须经过评审、走固定泳道”，LangGraph这种状态机更合适；但如果你希望“几个AI角色像同事一样，聊着聊着把活干完”，AutoGen顺手得多。

另外，如果你平时维护若依、Spring Boot这类Java后端，我建议把它当作独立的Python智能体服务来部署，而不是尝试把Agent逻辑塞进Java业务代码里。AutoGen擅长编排LLM，Spring Boot擅长承载业务接口，两者通过API通信，各管一摊，反而最省心。

1.3 版本选择：0.2还是0.4

AutoGen在0.4版本做了一次大重构，底层从同步的ConversableAgent变成了异步事件驱动架构（autogen-core）。这件事对新人有很强的迷惑性：网上大量教程还是0.2的写法，直接照搬到0.4会报错。

我的建议是：新项目直接用0.4。因为0.4的事件流更清晰，支持跨进程和分布式，官方后续的维护重心也完全在0.4上。如果是已经在0.2上跑稳定的老项目，不建议立刻迁移，毕竟两个版本的核心API差异很大。

具体差异集中在三块：0.2里常用的是ConversableAgent、AssistantAgent、UserProxyAgent，通过initiate_chat启动对话；0.4改成了AssistantAgent、RoundRobinGroupChat、SelectorGroupChat等，要走run_stream消费事件流。安装包名也从pyautogen变成了autogen-agentchat加autogen-ext。如果拿旧教程的代码去跑0.4，estado通常在import阶段就崩了。

2. 十分钟跑通第一个AutoGen对话应用

2.1 环境准备与模型客户端配置

先用Python 3.10以上的版本，建议3.11或3.12，开一个干净的虚拟环境：

python -m venv .venv source .venv/bin/activate pip install -U autogen-agentchat autogen-ext[openai]

装完之后，核心的模型客户端是OpenAIChatCompletionClient。它不局限于OpenAI官方模型，很多国产大模型服务只要兼容OpenAI接口，配置base_url就能接上。我一般这么写：

import os from autogen_ext.models.openai import OpenAIChatCompletionClient model_client = OpenAIChatCompletionClient( model="gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"), )

这里的api_key推荐走环境变量，不要硬编码在代码里。如果你接的是自建vLLM或者Ollama服务，把base_url指到对应地址即可。AutoGen本身对模型并不挑剔，但模型工具调用的能力越强，Agent跑起来越省心。模型选型上，我建议至少选一个在tool calling上表现稳定的型号，否则后面挂工具时会频繁出现参数幻觉。

2.2 最小化双Agent代码

跑通一个最小的多Agent应用，只需要两个AssistantAgent加一个RoundRobinGroupChat。下面这个例子里，一个Agent负责拆解步骤，另一个Agent负责给出实现方案：

import asyncio import os from autogen_agentchat.agents import AssistantAgent from autogen_agentchat.conditions import MaxMessageTermination from autogen_agentchat.teams import RoundRobinGroupChat from autogen_agentchat.ui import Console from autogen_ext.models.openai import OpenAIChatCompletionClient model_client = OpenAIChatCompletionClient( model="gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"), ) planner = AssistantAgent( name="planner", model_client=model_client, system_message="你负责把任务拆成三到五个可执行步骤，每次只输出步骤清单。", ) executor = AssistantAgent( name="executor", model_client=model_client, system_message="你根据步骤清单给出具体实现方案，如果清单不完整，请补充并说明。", ) termination = MaxMessageTermination(max_messages=6) team = RoundRobinGroupChat( [planner, executor], termination_condition=termination, ) async def main(): await Console( team.run_stream( task="设计一个简单的待办事项API，包含新增、查询、删除三个接口" ) ) if __name__ == "__main__": asyncio.run(main())

运行之后，你会看到两个Agent轮流出消息，到第六轮自动停。MaxMessageTermination(max_messages=6)就是“总发言上限”，它是最简单的兜底手段，保证不管聊得多嗨，到了次数就散会。

2.3 关键参数与运行流程说明

理解run_stream返回的事件流，是掌握AutoGen的关键。里面会依次出现TextMessage、ToolCallMessage、TaskResult这类事件对象，Console只不过是把它们打印成人类可读的对话记录。真实业务里，你完全不需要Console，而是自己遍历事件流，只挑自己关心的消息类型处理。

这里我要重点提一句system_message：它是定义一个Agent行为的最高性价比手段，比在对话里去纠正角色有效得多。我会习惯在system_message里把输出格式、边界条件一次写清楚，比如“你只输出审查意见，不要输出修改后的代码”。这套写法能让后面很多不可控行为变可控。

另一个必须想清楚的参数是termination_condition。不设终止条件的GroupChat，就是开会不设结束时间，两个模型能互相接话直到上下文爆炸。我通常的做法是组合使用：用MaxMessageTermination设一条硬上限，同时配合关键词终止条件。

3. 先搞懂AutoGen的三个核心：Agent角色、工具调用和群聊编排

3.1 AssistantAgent与UserProxyAgent的分工

在AutoGen的世界里，AssistantAgent就是“AI员工”，它背后绑定一个模型客户端，负责思考、回复、调用工具。UserProxyAgent则是“人类代理”，核心作用是引入人工输入：当模型说要执行某个危险操作时，它可以弹给用户确认；也可以接收你提前输入的指令，相当于把项目经理映射进系统里。

这个区分在做流程设计时很关键。如果流程里需要“人工审批”节点，就把UserProxyAgent放在那个位置，让模型在关键动作前停下来等人类确认。如果整个流程希望全自动跑完，就干脆别加UserProxyAgent，否则任务会卡在等待输入上，看起来像“死掉”了。

我在实际项目里更常用的组合是多个AssistantAgent各自扮演一个专家角色，让它们互相评审、互相补充，而不是总是依赖人工介入。人工参与留给最关键的决策点就好，比如“是否执行写库操作”“是否对外发送消息”，这类高风险的边界才值得人工把守。

3.2 用FunctionTool把函数挂给Agent

工具调用是AutoGen真正变强的地方。模型不会自己执行代码，它只是在对话里说“我要调用query_stock(000001)”，AutoGen收到这个意图后，在本地执行你注册的函数，再把返回值作为消息塞回对话，模型看到结果后再判断下一步。

一个典型的工具注册方式是这样：

from autogen_core.tools import FunctionTool def query_stock(code: str) -> str: # 这里可以替换成真实行情接口 return f"{code} 当日收盘价 12.50 元" stock_tool = FunctionTool( query_stock, description="查询股票收盘价，输入六位股票代码", ) agent = AssistantAgent( name="stock_agent", model_client=model_client, tools=[stock_tool], system_message="你是股票助手，需要先查行情再回答。", )

有两个细节直接决定工具会不会被模型正确使用：第一，函数签名必须写类型注解，函数名的语义要清晰，模型实际上是在通过“函数名+参数名+描述”猜调用意图；第二，返回值要尽量短，别把一个几十KB的JSON整个返回给模型，否则两轮就把上下文吃掉了。返回之前先做摘要，是成本最低的优化。

3.3 GroupChat的轮转、选择与条件终止

RoundRobinGroupChat是最朴素的会议主持人：按注册顺序轮流发言，公平但死板。SelectorGroupChat则升级了一步，会让一个“主持人模型”决定下一位发言人，更智能，但每次选择都额外消耗一次模型调用，也可能出现主持人选错人的情况。

终止条件方面，AutoGen提供了几类很实用的工具：MaxMessageTermination按消息条数兜底，TextMentionTermination等模型输出某个关键词，TokenUsageTermination按token预算终止。我推荐组合使用，比如“总消息数不超过12条，或者出现END关键词就结束”。这样既保证流程有终点，又给正常完成留下了出口。

4. 实战：代码审查+文档生成的双Agent工作流

4.1 场景设计

很多团队用AI写代码之后，最缺的是“把关”环节。所以我搭了一个双Agent场景：输入一段Python函数，审查Agent负责检查异常处理、可读性、参数边界，输出审查意见；文档Agent根据审查意见，生成一段面向调用方的使用文档。

这个场景的协作关系非常清晰：一个负责挑毛病，一个负责整理成果。它既能演示两个角色如何共享上下文，又能让你直观看到“中间产物”的价值——审查意见本身就是可观测的过程记录。

4.2 完整代码

下面是我实际跑通过的版本，注意终止条件用了MaxMessageTermination(max_messages=8)，防止流程停不下来：

import asyncio import os from autogen_agentchat.agents import AssistantAgent from autogen_agentchat.conditions import MaxMessageTermination from autogen_agentchat.teams import RoundRobinGroupChat from autogen_agentchat.ui import Console from autogen_ext.models.openai import OpenAIChatCompletionClient model_client = OpenAIChatCompletionClient( model="gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"), ) reviewer = AssistantAgent( name="reviewer", model_client=model_client, system_message=( "你是一名资深代码审查员。重点检查异常处理、安全性、可读性，" "逐条列出问题。每次只输出审查意见，不要输出修改后的代码。" ), ) writer = AssistantAgent( name="writer", model_client=model_client, system_message=( "你是一名技术文档工程师。根据审查意见，编写一段给调用方看的使用文档，" "包含参数说明、返回值、注意事项。" ), ) termination = MaxMessageTermination(max_messages=8) team = RoundRobinGroupChat([reviewer, writer], termination_condition=termination) async def main(): code = """ def divide(a, b): return a / b """ await Console( team.run_stream(task=f"请审查下面代码并输出使用文档：\n{code}") ) if __name__ == "__main__": asyncio.run(main())

运行结果里，你会看到reviewer先挑出一堆问题，比如“未处理分母为零的情况”“缺少类型注解”，随后writer基于这些意见生成使用文档。整个过程的每一步都有迹可循。

4.3 为什么这样设计：角色分离的价值

如果让单个模型既审查又写文档，最常见的问题是它会用自己的模糊判断覆盖事实，比如把“未处理零除”这个严重问题轻描淡写地带过。两个角色分离之后，审查意见成了中间产物，你可以完整看到“它认为哪里有毛病”，如果最终结果不对，也能准确定位是审查环节错了，还是文档环节错了。这种可观测性是Multi-Agent设计里最值钱的部分。

从上下文管理的角度看，给两个Agent不同的system_message，其实是在做上下文隔离。reviewer的世界里没有“必须产出可用文档”的压力，它就能更专注地挑毛病；如果换成单人完成，注意力一定会被“既要找问题、又要写文档”拉扯开。

4.4 如何嵌进Java/Spring Boot后端

如果你平时维护的是若依或者Spring Boot，我的建议很明确：别执着于在Java代码里直接驱动AutoGen。把AutoGen工作流包装成一个独立的Python服务，对外提供HTTP接口或者走消息队列，Spring Boot只负责接收前端请求、写入任务表、轮询结果即可。

这样做的原因很简单：Agent的模型升级、工具调整、prompt修改都会很频繁，如果这些都耦合在Java业务代码里，每次改动都要经历一次Java发布流程，非常痛苦。独立成服务之后，Python侧可以随时热更新，Java侧只关心任务状态。任务量不大时，用FastAPI包一层就够了；任务量上来之后，再上Celery或者更重的队列。

5. 上下文与记忆管理：长对话不翻车的几个笨办法

5.1 上下文窗口是如何被吃掉的

多Agent每多一轮，所有历史消息都会在下一次模型调用时重新发送一遍。如果某个工具返回的是一个几十KB的JSON，几轮下来上下文就被挤占得差不多了。

这时候Agent会出现一个非常典型的状态：它把你最初的任务描述忘得一干二净，开始顺着最后一条消息自由发挥。很多人以为这是模型变笨了，其实不是，是信息窗口被历史消息填满了，早期的核心需求被挤出了注意力范围。上下文管理不到位，换再好的模型也白搭。

5.2 四个可落地的缓解手段

我实际用下来，有这么几个笨但有效的办法：

• 任务切片：把大任务拆成多个小GroupChat，上一个任务的输出作为下一个任务的输入。这是最朴素也最可靠的手段。
• 摘要替代：每个阶段结束后，让一个Agent把关键信息压缩成三百字以内的摘要，下一阶段只传摘要，不传完整历史。
• 外部记忆：把用户偏好、领域知识放到向量库或者Redis里，每个新会话开始时按需查回，拼进system_message。
• 换长上下文模型：这是最懒的办法，偶尔确实能救急，但治标不治本，而且成本会明显上升。

其中任务切片和摘要替代几乎是零成本改造，我会优先把这两件事做掉。只要Agent每次启动时面对的都是一个“精简干净”的任务包，它的表现稳定性会大幅提升。

5.3 记忆框架选型的个人建议

最近很多人问Agent记忆框架怎么选，我自己的结论是：先分清“工作记忆”和“长期记忆”。

工作记忆就是当前对话历史，AutoGen天然在管理，你不要画蛇添足。真正需要引入外部框架的，是长期记忆——比如用户的历史偏好、跨会话的结论、领域知识库。小项目完全没有必要一上来就上重型记忆框架，先用一个JSON文件或者Redis存结构化摘要就够了；等出现“多用户、高并发、需要个性化上下文”时，再考虑Mem0这类专门面向Agent的记忆框架。

选型时我只看三点：检索质量好不好、支不支持及时更新、数据存储合不合规。检索质量决定了记起来的东西有没有用；及时更新决定它会不会越用越偏；合规则是底线，尤其是涉及用户数据时，脱敏和权限控制必须提前设计好。

6. 生产环境实测：死循环、工具幻觉、权限失控与效果评估

6.1 坑一：GroupChat死循环的完整排查链路

有一次我用两个Agent讨论API设计方案，跑了十分钟都没结束。我当时的排查顺序是这样的：

第一，打印每个event的类型和来源，结果发现最后六条消息都是同一个Agent在重复“非常有道理”。第二，检查终止条件，发现我只用了TextMentionTermination("END")，但两个Agent从头到尾都没有输出“END”。第三，检查模型侧的行为，发现上下文太长之后，模型开始机械重复历史回复。

定位下来，根本原因是终止条件设计得太单薄，只靠一个关键词来判断结束，而模型根本没有遵循这个约定。修复方式很简单：改成MaxMessageTermination(max_messages=12)加TextMentionTermination("END")的组合，同时在两个Agent的system_message里都明确写一句“讨论完成时，必须在一句话结尾输出END”。这样就算模型忘了输出关键词，消息数兜底也会把流程截停。

6.2 坑二：工具调用参数幻觉与错误传递

模型在调用工具时经常编造参数。比如我的函数只接受一个code: str，它却传了一个带括号的“000001(深市)”。如果不做任何防护，函数直接抛异常，整个会话就崩了。

我的习惯是：函数内部用try/except把所有错误包住，返回一个可读的字符串错误说明。这样模型会把错误当成普通消息读回去，然后自己修正重试。同时，在工具的description字段里把参数格式写死，比如“参数必须是六位数字字符串”，能显著降低幻觉概率。

这个思路同样适用于外部API调用：任何网络请求都可能超时、限流、返回异常结构，全部兜成字符串返回，才能让对话继续下去。一个会抛异常的工具函数，和一个只会返回错误信息的工具函数，在Agent场景里的表现完全是两回事。

6.3 坑三：代码执行权限失控

UserProxyAgent的code_execution_config可以执行模型生成的代码，这在沙箱环境里很方便，但放进生产环境风险极大：模型可能生成删除文件、读取敏感信息、安装任意依赖的代码。

我现在的原则是：生产环境里不给Agent直接执行任意代码的权限，把它想做的事全部封装成白名单工具。比如只允许调用query_stock、send_http_request这类特定函数。实在需要执行代码时，放进Docker容器里跑，文件系统设成只读，网络走白名单。

这是Agent落地中最容易被忽视的边界。很多人在预览环境里跑得欢，一上生产就出问题，原因往往是模型的自由度过大了。给Agent留多少自由，应该由业务风险决定，而不是由模型能力决定。

6.4 用DeepEval做一次Agent输出评估

评估Agent比评估模型难，因为Agent的输出没有唯一标准答案。我常用DeepEval采用LLM-as-Judge的方式做回归测试，核心思路是让另一个大模型当裁判，给本次回复打分。

from deepeval import assert_test from deepeval.test_case import LLMTestCase from deepeval.metrics import AnswerRelevancyMetric test_case = LLMTestCase( input="请审查divide函数并输出使用文档", actual_output=final_output, ) metric = AnswerRelevancyMetric(threshold=0.7) assert_test(test_case, [metric])

除了自动指标，我建议每个版本都保留一份人工回归清单：目标是否完成、工具调用是否合法、有没有幻觉事实、成本和延迟是否达标。自动化指标负责发现回归，人工清单负责确认原因，两者配合才能在Agent悄悄变差之前把它拦住。

最后分享一点个人体会：AutoGen本质上是一套编排脚手架，它的上限不取决于框架本身，而取决于你怎么封装工具、怎么写system_message、怎么设计终止条件，模型只是其中一个零件。我刚上手的时候总想一次把所有功能都堆上，结果就是死循环和费用失控。从最小双Agent开始，逐步加工具、加记忆、加人工审批，才是最稳的路。如果你正好在搭Agent服务，建议先把上面那个审查加文档的例子跑通，再往真实业务里扩展。