从原理到代码，拆解AutoGen框架开发实践

（一）引言

之前我们实现了ReAct、Plan-and-Solve和Reflection智能体的核心工作流。这个过程让我们对智能体的内在执行逻辑有所了解。 这些代码可以很好的完成特定任务，但是如果要用它们来构建多个、不同类型且逻辑复杂的智能体应用，很快就会遇到瓶颈。

归根结底在于当任务量和复杂度上来之后，代码量和业务逻辑复杂度骤增，简单的工作流不足以满足需求，而且缺乏一个统一的标准，当涉及到不同的复杂任务时不能按照一套标准和规范来执行。

因此我们需要智能体框架 。一个框架的本质，是一套经过验证的规范 。它将所有智能体共有的、重复性的工作进行抽象和封装，让我们在构建新的智能体时，能够专注于其独特的业务逻辑，而非通用的底层实现。

相比于直接编写独立的智能体脚本，使用框架的价值主要体现在以下几个方面：

• 提升代码的复用率与开发效率：一个好的框架会提供一个通用的 Agent 基类或者执行器，它封装了智能体运行的核心循环
• 实现核心组件的解耦和可扩展性：一个健壮的智能体系统应该由多个松散的模块组成。模型层 ：负责与LLM交互，可以替换不同的模型；工具层 ：提供标准化的工具定义、注册和执行接口；记忆层：处理短期和长期记忆，可以根据需求切换不同的记忆策略。
• 状态管理机制：在真实的、长时间的智能体应用中，状态管理需要处理上下文窗口限制、历史信息持久化、多轮对话状态跟踪等问题。一个框架可以提供一套强大而通用的状态管理机制，开发者无需每次都重新处理这些复杂问题。
• 简化可观测性和调试过程：当智能体的行为变得复杂时，理解其决策过程变得至关重要。一个精心设计的框架可以内置强大的可观测性能力。例如，通过引入事件回调机制可以在智能体生命周期的关键节点自动触发日志记录或者数据上报，从而轻松地追踪和调试智能体的完整运行轨迹，这远比在代码中手动添加print语句要高效和系统化。

（二）AutoGen的核心机制

智能体框架的生态正在快速发展，如果说 LangChain 和 LlamaIndex 定义了第一代通用LLM应用框架的范式，那么新一代的框架更加注重解决特定领域的深层挑战，尤其是多智能体协作 和复杂工作流控制。

本文主要聚焦于AutoGen框架。AutoGen的核心思想是通过对话实现协作。它将智能体系统抽象为一个由多个可对话智能体组成的群聊。开发者可以定义不同角色，并设定它们之间的交互规则。任务的解决过程就是这些智能体在群聊中通过自动化消息传递，不断对话、协作、迭代直至目的达成的过程。

我们以 0.7.4 版本为例，它标志着框架在底层设计上的一次根本性革新。这次更新并非简单的功能叠加，而是对整体框架的重新思考，旨在提升框架的模块化、并发性能和开发者体验。

1. 框架结构演进

新架构最显著的特点就是引入了清晰的分层 和异步优先的设计理念。

• 分层设计： Core 作为框架的底层基础，封装了与语言模型交互、消息传递等核心功能。它的存在保证了框架的稳定性和未来扩展性； Agentchat 构建于 Core 之上，提供了用于开发对话式智能体应用的高级接口，简化了多智能体应用的开发流程。
• 异步优先：新架构转向异步编程（ async/await ）。在多智能体协作场景中，网络请求是主要的耗时操作。异步模式允许系统中在等待一个智能体响应时处理其他任务，从而避免线程阻塞，显著提升了并发处理能力和系统资源的利用效率。

2. 群聊协作模式

当任务需要多个智能体协作时，就需要一个机制来协调对话流程。在早期版本中， GroupChatManager 承担了这一个职责。而在新架构中，引入了更灵活的 Team 群聊概念。

• 轮循群聊：它会让参与的智能体按照预定义的顺序依次发言。这种模式非常适用于流程固定的任务。

首先创建一个轮询群聊实例，将所有参与协作的智能体加入其中；当一个任务开始时，群聊会按照预设顺序依次激活相应的智能体；被选中的智能体根据当前的上下文进行响应；群聊将新的回复加入对话历史，并激活下一个智能体；持续进行直到达到最大对话轮次或者满足预设的终止条件。

（三）AutoGen的工程实现

1. 需求分析

我们将构建一个模拟的软件开发团队，该团队由多个具有不同专业技能的智能体组成，它们将协作完成一个真实的软件开发任务。

我们的目标是完成一个可以实时显示比特币当前价格的Web应用。这个任务完整地覆盖了软件开发的典型环节：从需求分析、技术选型、编码实现到代码审查和最终测试。这使其成为检验AutoGen自动化协作流程的理想场所。

我们设计了四个职责分明的智能体角色：

• ProductManager产品经理：负责将用户的模糊需求转化为清晰、可执行的开发计划
• Engineer工程师：根据开发计划，负责编写具体的应用程序代码
• CodeReviewer代码审查员：负责审查工程师提交的代码，确保其质量、可读性和健壮性
• UserProxy用户代码：代表用户发起初始任务，并负责执行和验证最终交付的代码

2. AutoGen框架编码实现

（1）依赖库安装

创建虚拟并激活环境
python -m venv autogen_venv source autogen_venv/bin/activate

在终端输入
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

# requirements.txt
# AutoGen 软件开发团队案例依赖 (v0.7.4)
autogen-agentchat
autogen-ext[openai,azure]
openai>=1.0.0
streamlit>=1.28.0
requests>=2.31.0
pandas>=2.0.0
plotly>=5.15.0
asyncio
dotenv

（2）模型客户端配置

所有基于LLM的智能体都需要一个模型客户端来与语言模型进行交互。我们通过一个独立的函数来创建和配置模型客户端，并通过环境变量管理APIKey和服务地址。

from autogen_ext.models.openai import OpenAIChatCompletionClient

def create_openai_model_client():
	# 创建并配置LLM客户端
	return OpenAIChatCompletionClient(
		model=os.getenv("LLM_MODEL_ID", "deepseek-v4-flash"),
		api_key=os.getenv("LLM_API_KEY"),
		base_url=os.getenv("LLM_BASE_URL", "https://api.deepseek.com")
	)

（3）智能体角色定义

定义智能体的核心在于编写高质量的系统消息（System Message）。系统消息精确地规定了智能体的角色、职责、工作流程，甚至是与其他智能体交互的方式。在我们的软件开发团队里，我们为每一个角色都创建了一个独立的函数来封装其定义。

（i）产品经理

产品经理负责启动整个流程。它的系统消息不仅定义了其职责，还规范了其输出的结构，并包含了引导对话转向工程师的明确指令。

def create_product_manager(model_client):
    """创建产品经理智能体"""
    system_message = """你是一位经验丰富的产品经理，专门负责软件产品的需求分析和项目规划。

你的核心职责包括：
1. **需求分析**：深入理解用户需求，识别核心功能和边界条件
2. **技术规划**：基于需求制定清晰的技术实现路径
3. **风险评估**：识别潜在的技术风险和用户体验问题
4. **协调沟通**：与工程师和其他团队成员进行有效沟通

当接到开发任务时，请按以下结构进行分析：
1. 需求理解与分析
2. 功能模块划分
3. 技术选型建议
4. 实现优先级排序
5. 验收标准定义

请简洁明了地回应，并在分析完成后说"请工程师开始实现"。"""

    return AssistantAgent(
        name="ProductManager",
        model_client=model_client,
        system_message=system_message,
    )

（ii）工程师

工程师的系统消息聚焦于技术实现。它列举了工程师的技术专长，并规定了其在接收到任务后的具体行动步骤，同样也包含了引导流程转向代码审查员的指令。

def create_engineer(model_client):
    """创建软件工程师智能体"""
    system_message = """你是一位资深的软件工程师，擅长 Python 开发和 Web 应用构建。

你的技术专长包括：
1. **Python 编程**：熟练掌握 Python 语法和最佳实践
2. **Web 开发**：精通 Streamlit、Flask、Django 等框架
3. **API 集成**：有丰富的第三方 API 集成经验
4. **错误处理**：注重代码的健壮性和异常处理

当收到开发任务时，请：
1. 仔细分析技术需求
2. 选择合适的技术方案
3. 编写完整的代码实现
4. 添加必要的注释和说明
5. 考虑边界情况和异常处理

请提供完整的可运行代码，并在完成后说"请代码审查员检查"。"""

    return AssistantAgent(
        name="Engineer",
        model_client=model_client,
        system_message=system_message,
    )

（iii）代码审查员

代码审查员侧重审查代码的质量、安全性和规范性。它的系统消息详细列出了审查的重点和流程，保障了代码提交前的质量。

def create_code_reviewer(model_client):
    """创建代码审查员智能体"""
    system_message = """你是一位经验丰富的代码审查专家，专注于代码质量和最佳实践。

你的审查重点包括：
1. **代码质量**：检查代码的可读性、可维护性和性能
2. **安全性**：识别潜在的安全漏洞和风险点
3. **最佳实践**：确保代码遵循行业标准和最佳实践
4. **错误处理**：验证异常处理的完整性和合理性

审查流程：
1. 仔细阅读和理解代码逻辑
2. 检查代码规范和最佳实践
3. 识别潜在问题和改进点
4. 提供具体的修改建议
5. 评估代码的整体质量

请提供具体的审查意见，完成后说"代码审查完成，请用户代理测试"。"""

    return AssistantAgent(
        name="CodeReviewer",
        model_client=model_client,
        system_message=system_message,
    )

（iiii）用户代理

用户代理智能体不依赖LLM进行回复，而是作为用户在系统中的代理。它的 description 字段描述了其职责，除此之外，它还负责在任务最终完成后发出 TERMINATE 指令来结束整个协作过程。

def create_user_proxy():
    """创建用户代理智能体"""
    return UserProxyAgent(
        name="UserProxy",
        description="""用户代理，负责以下职责：
1. 代表用户提出开发需求
2. 执行最终的代码实现
3. 验证功能是否符合预期
4. 提供用户反馈和建议

完成测试后请回复 TERMINATE。""",
    )

（4）定义团队协作流程

以上通过四个独立的智能体角色定义函数，我们构建了一支功能完备的虚拟团队，也展示了通过系统消息构建提示词是设计高效多智能体应用的核心环节。

在本案例中，软件开发的流程是相对固定的，因此，轮询群聊是理想的选择。我们按照业务逻辑顺序，将四个智能体加入到参与者列表中。

from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import TextMentionTermination
    # 创建团队聊天
    team_chat = RoundRobinGroupChat(
        # 决定智能体发言的先后顺序
        participants=[
            product_manager,
            engineer, 
            code_reviewer,
            user_proxy
        ],
        # 控制协作流程何时结束
        termination_condition=termination,
        max_turns=20,  # 最大轮次
    )

（5）群聊启动和运行

AutoGen 0.7.4 采用异步架构，整个协作流程的启动和运行都在一个异步函数中完成，并最终通过 asyncio.run_software_development_team() 来执行。

async def run_software_development_team():
    """运行软件开发团队协作"""
    
    print("🔧 正在初始化模型客户端...")
    
    # 先使用标准的 OpenAI 客户端测试
    model_client = create_openai_model_client()
    
    print("👥 正在创建智能体团队...")
    
    # 创建智能体团队
    product_manager = create_product_manager(model_client)
    engineer = create_engineer(model_client)
    code_reviewer = create_code_reviewer(model_client)
    user_proxy = create_user_proxy()
    
    # 添加终止条件
    termination = TextMentionTermination("TERMINATE")
    
    # 创建团队聊天
    team_chat = RoundRobinGroupChat(
        participants=[
            product_manager,
            engineer, 
            code_reviewer,
            user_proxy
        ],
        termination_condition=termination,
        max_turns=20,  # 最大轮次
    )
    
    # 定义开发任务
    task = """我们需要开发一个比特币价格显示应用，具体要求如下：

核心功能：
- 实时显示比特币当前价格（USD）
- 显示24小时价格变化趋势（涨跌幅和涨跌额）
- 提供价格刷新功能

技术要求：
- 使用 Streamlit 框架创建 Web 应用
- 界面简洁美观，用户友好
- 添加适当的错误处理和加载状态

请团队协作完成这个任务，从需求分析到最终实现。"""
    
    # 执行团队协作
    print("🚀 启动 AutoGen 软件开发团队协作...")
    print("=" * 60)
    
    # 使用 Console 来显示对话过程
    result = await Console(team_chat.run_stream(task=task))
    
    print("\n" + "=" * 60)
    print("✅ 团队协作完成！")
    
    return result
if __name__ == "__main__":
    # 运行异步协作流程
    result = asyncio.run(run_software_development_team())

（6）AutoGen框架的完整实现

以Ubuntu22.04系统，Python3.10版本为例进行展示。

首先我们新建一个项目文件夹 autogen_demo 来存放我们的所有文件。

autogen_demo/

├── .env

├── llm_client.py

├── autogen_software_team.py

├── requirements.txt

└── README.md

llm_client.py

# llm_client.py
import os
from openai import OpenAI
from dotenv import load_dotenv # 从.env文件中导入环境变量
from typing import List, Dict

# 导入环境变量
load_dotenv()

class HelloAgentsLLM:
	# 调用兼容OpenAI接口的服务, 使用默认的流式响应（将响应内容分为chunks逐个发送给客户端，而不是等待响应完毕一次性发送）
	def __init__(self, model: str = None, apiKey: str = None, baseUrl: str = None, timeout: int = None):
	
		# 初始化客户端，优先使用本地传入参数，否则加载环境变量参数
		self.model = model or os.getenv("LLM_MODEL_ID")
		apiKey = apiKey or os.getenv("LLM_API_KEY")
		baseUrl = baseUrl or os.getenv("LLM_BASE_URL")
		timeout = timeout or int(os.getenv("LLM_TIMEOUT", 60))
				
		if not all([self.model, apiKey, baseUrl]):
			raise ValueError("model ID and apiKey must be provided in .env file")
		self.client = OpenAI(api_key=apiKey, base_url=baseUrl, timeout=timeout)
		print("✅ 大模型配置成功")
		
	def think(self, messages: List[Dict[str, str]], temperature: float = 0) -> str:
		# 调用大模型进行思考，并返回思考结果
		print(f"🧠 正在调用 {self.model} 模型...")
		try:
			response = self.client.chat.completions.create(
				model=self.model,
				messages=messages,
				temperature=temperature,
				stream=True, # 开启流式响应
			)
			
			# 流式响应逻辑
			print("✅ 大语言模型响应成功:")
			collected_content = []
			for chunk in response: 
				content = chunk.choices[0].delta.content or "" # 从当前数据块提取刚产生的数据
				print(content, end="", flush=True)
				collected_content.append(content) # 将每次新产生的数据进行添加
			print() # 流式输出结束后换行
			return "".join(collected_content) # 将列表元素合成为完整字符串
		except Exception as e:
			print(f"❌ 调用LLM API时发生错误: {e}")
			return None

autogen_software_team.py

"""
AutoGen 软件开发团队协作案例
"""

import os
import asyncio
from typing import List, Dict, Any
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

# 先测试一个版本，使用 OpenAI 客户端
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent, UserProxyAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import TextMentionTermination
from autogen_agentchat.ui import Console

def create_openai_model_client():
    """创建 OpenAI 模型客户端用于测试"""
    return OpenAIChatCompletionClient(
        model=os.getenv("LLM_MODEL_ID", "gpt-4o"),
        api_key=os.getenv("LLM_API_KEY"),
        base_url=os.getenv("LLM_BASE_URL", "https://api.openai.com/v1")
    )

def create_product_manager(model_client):
    """创建产品经理智能体"""
    system_message = """你是一位经验丰富的产品经理，专门负责软件产品的需求分析和项目规划。

你的核心职责包括：
1. **需求分析**：深入理解用户需求，识别核心功能和边界条件
2. **技术规划**：基于需求制定清晰的技术实现路径
3. **风险评估**：识别潜在的技术风险和用户体验问题
4. **协调沟通**：与工程师和其他团队成员进行有效沟通

当接到开发任务时，请按以下结构进行分析：
1. 需求理解与分析
2. 功能模块划分
3. 技术选型建议
4. 实现优先级排序
5. 验收标准定义

请简洁明了地回应，并在分析完成后说"请工程师开始实现"。"""

    return AssistantAgent(
        name="ProductManager",
        model_client=model_client,
        system_message=system_message,
    )

def create_engineer(model_client):
    """创建软件工程师智能体"""
    system_message = """你是一位资深的软件工程师，擅长 Python 开发和 Web 应用构建。

你的技术专长包括：
1. **Python 编程**：熟练掌握 Python 语法和最佳实践
2. **Web 开发**：精通 Streamlit、Flask、Django 等框架
3. **API 集成**：有丰富的第三方 API 集成经验
4. **错误处理**：注重代码的健壮性和异常处理

当收到开发任务时，请：
1. 仔细分析技术需求
2. 选择合适的技术方案
3. 编写完整的代码实现
4. 添加必要的注释和说明
5. 考虑边界情况和异常处理

请提供完整的可运行代码，并在完成后说"请代码审查员检查"。"""

    return AssistantAgent(
        name="Engineer",
        model_client=model_client,
        system_message=system_message,
    )

def create_code_reviewer(model_client):
    """创建代码审查员智能体"""
    system_message = """你是一位经验丰富的代码审查专家，专注于代码质量和最佳实践。

你的审查重点包括：
1. **代码质量**：检查代码的可读性、可维护性和性能
2. **安全性**：识别潜在的安全漏洞和风险点
3. **最佳实践**：确保代码遵循行业标准和最佳实践
4. **错误处理**：验证异常处理的完整性和合理性

审查流程：
1. 仔细阅读和理解代码逻辑
2. 检查代码规范和最佳实践
3. 识别潜在问题和改进点
4. 提供具体的修改建议
5. 评估代码的整体质量

请提供具体的审查意见，完成后说"代码审查完成，请用户代理测试"。"""

    return AssistantAgent(
        name="CodeReviewer",
        model_client=model_client,
        system_message=system_message,
    )

def create_user_proxy():
    """创建用户代理智能体"""
    return UserProxyAgent(
        name="UserProxy",
        description="""用户代理，负责以下职责：
1. 代表用户提出开发需求
2. 执行最终的代码实现
3. 验证功能是否符合预期
4. 提供用户反馈和建议

完成测试后请回复 TERMINATE。""",
    )

async def run_software_development_team():
    """运行软件开发团队协作"""
    
    print("🔧 正在初始化模型客户端...")
    
    # 先使用标准的 OpenAI 客户端测试
    model_client = create_openai_model_client()
    
    print("👥 正在创建智能体团队...")
    
    # 创建智能体团队
    product_manager = create_product_manager(model_client)
    engineer = create_engineer(model_client)
    code_reviewer = create_code_reviewer(model_client)
    user_proxy = create_user_proxy()
    
    # 添加终止条件
    termination = TextMentionTermination("TERMINATE")
    
    # 创建团队聊天
    team_chat = RoundRobinGroupChat(
        participants=[
            product_manager,
            engineer, 
            code_reviewer,
            user_proxy
        ],
        termination_condition=termination,
        max_turns=20,  # 增加最大轮次
    )
    
    # 定义开发任务
    task = """我们需要开发一个比特币价格显示应用，具体要求如下：

核心功能：
- 实时显示比特币当前价格（USD）
- 显示24小时价格变化趋势（涨跌幅和涨跌额）
- 提供价格刷新功能

技术要求：
- 使用 Streamlit 框架创建 Web 应用
- 界面简洁美观，用户友好
- 添加适当的错误处理和加载状态

请团队协作完成这个任务，从需求分析到最终实现。"""
    
    # 执行团队协作
    print("🚀 启动 AutoGen 软件开发团队协作...")
    print("=" * 60)
    
    # 使用 Console 来显示对话过程
    result = await Console(team_chat.run_stream(task=task))
    
    print("\n" + "=" * 60)
    print("✅ 团队协作完成！")
    
    return result

# 主程序入口
if __name__ == "__main__":
    try:
        # 运行异步协作流程
        result = asyncio.run(run_software_development_team())
        
        print(f"\n📋 协作结果摘要：")
        print(f"- 参与智能体数量：4个")
        print(f"- 任务完成状态：{'成功' if result else '需要进一步处理'}")
        
    except ValueError as e:
        print(f"❌ 配置错误：{e}")
        print("请检查 .env 文件中的配置是否正确")
    except Exception as e:
        print(f"❌ 运行错误：{e}")
        import traceback
        traceback.print_exc()

3. 测试效果

首先写一个 test.py ，运行 python test.py 来测试一下调用 LLM API：

import os
from dotenv import load_dotenv
load_dotenv()

print(f"API Key: {os.getenv('LLM_API_KEY')[:10]}...")
print(f"Base URL: {os.getenv('LLM_BASE_URL')}")
print(f"Model: {os.getenv('LLM_MODEL_ID')}")

观察到以下输出说明LLM API调用成功：

然后运行 python autogen_software_team.py，观察到以下输出：

按照智能体给出的以下说明文档进行操作

执行 streamlit run btc_monitor.py 后打开以下网页

（四）AutoGen的特点和局限性

1. 特点

• 简化了复杂任务建模：无需为智能体团队设计复杂的状态机或者控制流逻辑，而是将一个完整的软件开发流程，自然地映射为不同角色之间的对话。
• 通过系统消息为每个智能体赋予高度专业化的角色：每个智能体专精某部分任务。
• 为"人类再环（Human-in-the-loop）"提供了天然的接口。UserProxyAgent 既可以作为任务的发起者，又可以是流程的监督者和最终的验收者。

2. 局限性

• 对话式调试困难：当智能体团队的工作结果未达到预期时，调试过程非常棘手。
• 可能产生偏离预期的回复：LLM的对话本质具有不确定性，可能会导致对话走向意外的分支，甚至陷入循环。