我们来深入讲解 AutoGen 的核心 API 和功能。AutoGen 是一个由微软开发的强大框架，用于构建基于多智能体对话的 LLM 应用程序。

它的核心思想是：通过定义多个可以相互对话的 AI Agent（智能体），来自动化地完成复杂的任务。 你可以把它想象成一个由AI组成的“团队”，每个成员各司其职，通过协作解决问题。

---

一、核心概念

在深入 API 之前，先理解三个最核心的概念：

1. Agent（智能体）：所有角色的基类。一个 Agent 可以定义它的行为（如 LLM、人类、函数）、对话模式等。
2. ConversableAgent（可对话智能体）：最常用、最重要的类。绝大多数你定义的 Agent 都会继承自它。它具备了发起对话、接收消息、回复消息的能力。
3. GroupChat（群聊） & GroupChatManager（群聊管理器）：用于管理多个 Agent 之间的复杂对话，决定下一个讲话的是谁。

---

二、核心功能

AutoGen 的核心功能围绕这些概念展开：

核心功能	描述
多代理对话	创建多个具备不同角色、系统和能力的代理，让它们通过自然语言对话协作解决问题。
灵活的角色定义	为每个代理设定 system_message（系统提示词）来定义其角色、职责和个性（如专家、程序员、批评家）。
混合智能体模式	支持多种类型的代理混合协作：AI Agent（LLM驱动）、Human Agent（人类参与）、AssistantAgent（默认AI助手）、UserProxyAgent（代表用户执行代码/命令）。
自动代码执行与调试	UserProxyAgent 可以自动检测对话中的代码块（如 Python），执行它，并将结果返回给对话，实现“代码-反馈-修正”的自动化循环。
函数调用（Tool Use）	代理可以注册并自动调用外部工具函数（如调用 API、查询数据库、处理文件），极大地扩展了应用能力。
可定制对话流程	通过 GroupChat 和自定义的 speaker_selection_method，可以控制对话的流程和发言顺序（如轮流发言、由管理器选择）。
人类介入	在任何时候，人类都可以被@加入对话，提供反馈、做出决策或指导代理的方向。
对话历史持久化	自动记录完整的对话历史，便于分析、审计和复现结果。

---

三、核心 API 与函数

以下是最关键的几个类和它们的方法。

1. ConversableAgent 类（及其子类）

这是所有对话的基础。

• __init__ 构造函数：创建代理时的核心配置。

  agent = ConversableAgent(
      name="assistant",  # 代理名称，用于在对话中被@提及
      system_message="You are a helpful AI assistant.",  # 定义角色和能力的系统提示词
      llm_config={"config_list": config_list},  # 连接LLM的配置（如API密钥、模型名）
      human_input_mode="NEVER",  # 人类介入模式： "ALWAYS", "TERMINATE"（默认，在收到TERMINATE时询问）, "NEVER"
      code_execution_config=False,  # 代码执行配置。如果是UserProxyAgent，这里会是一个字典
      function_map=None,  # 注册给该代理的函数映射
      ...
  )
  

2. 预设的子类（简化创建过程）

• AssistantAgent

  • 功能：默认的“助手”角色，通常扮演回答问题、生成代码/计划的主要AI。
  • 特点：human_input_mode 默认为 “NEVER”，不会请求人类输入。
  • 示例：

    assistant = AssistantAgent(
        name="assistant",
        llm_config=llm_config,
        system_message="You are a helpful assistant."
    )
    

• UserProxyAgent

  • 功能：用户的代理。这是实现自动代码执行的关键。
  • 职责：代表用户与其他AI代理交互。它会自动检测AI回复中的代码块（\``python … ````），并执行它们，然后将结果返回对话。
  • 特点：human_input_mode 默认为 “TERMINATE”，在收到 “TERMINATE” 信号时会询问用户是否继续。
  • 示例：

    user_proxy = UserProxyAgent(
        name="user_proxy",
        human_input_mode="TERMINATE",
        code_execution_config={"work_dir": "coding", "use_docker": False},  # 配置代码执行环境
        max_consecutive_auto_reply=10,  # 最大自动回复次数，防止无限循环
    )
    

3. 启动对话的核心方法：initiate_chat

这是让两个或多个代理开始对话的最核心函数。

• 语法：initiate_chat(recipient, message, clear_history=True, silent=False)

• 参数：

  • recipient：接收消息的代理对象。
  • message：对话的起始消息。
  • clear_history：是否在开始新对话前清除历史记录。
  • silent：是否安静模式（不打印对话信息到终端）。

• 工作流程：

  1. 代理 A 调用 a.initiate_chat(b, "Hello")。
  2. 代理 A 将 “Hello” 发送给代理 B。
  3. 代理 B 生成回复。
  4. 代理 B 将回复发回给代理 A。
  5. 这个过程会根据代理的配置（如 max_consecutive_auto_reply）持续进行，直到一方不再回复或触发终止条件。

4. 注册和使用函数（Function/Tool Calling）

这是构建复杂应用的关键。让 LLM 能够使用外部工具。

• 步骤 1: 定义函数

  def get_weather(location: str):
      """Get the current weather for a given location."""
      # 这里可以是调用真实API的代码
      return f"The weather in {location} is sunny and 25°C."
  

• 步骤 2: 注册函数
  在创建代理时，通过 function_map 参数注册，或使用 register_function 方法。

  from autogen import register_function
  
  weather_assistant = AssistantAgent(
      name="weather_assistant",
      llm_config={
          "config_list": config_list,
          "functions": [  # 向LLM描述这个函数
              {
                  "name": "get_weather",
                  "description": "Get the current weather for a location",
                  "parameters": {
                      "type": "object",
                      "properties": {
                          "location": {"type": "string", "description": "The city name"},
                      },
                      "required": ["location"],
                  }
              }
          ],
      }
  )
  
  # 注册函数映射，告诉代理哪个函数名对应哪个Python函数
  register_function(
      get_weather,
      caller=weather_assistant,  # 哪个代理可以调用
      executor=user_proxy,       # 哪个代理来执行（通常是UserProxyAgent）
  )
  

• 步骤 3: 使用
  当你向 weather_assistant 提问 “What’s the weather in Beijing?” 时，它会自动生成调用 get_weather 函数的 JSON 请求，user_proxy 会执行该函数并将结果返回，助手再根据结果生成最终回复。

5. GroupChat 和 GroupChatManager

用于管理超过两个代理的复杂会话。

• 创建群聊：

  from autogen import GroupChat, GroupChatManager
  
  groupchat = GroupChat(
      agents=[agent1, agent2, agent3, user_proxy],
      messages=[],
      max_round=12,  # 最大对话轮数
      speaker_selection_method="round_robin",  # 或 "auto"， 或自定义函数
  )
  manager = GroupChatManager(groupchat=groupchat, llm_config=llm_config)
  

• 启动群聊：

  user_proxy.initiate_chat(
      manager,
      message="大家好，我们来讨论一下这个问题..."
  )
  

  此时，GroupChatManager 会扮演主持人的角色，根据设定的规则（如轮流发言round_robin或由LLM自动选择auto）来决定下一个该由哪个代理发言。

---

总结与工作流示例

一个最经典的 AutoGen 工作流如下：

1. 初始化配置：设置 LLM（如 OpenAI GPT-4）。
2. 创建代理：创建一个 AssistantAgent（专家）和一个 UserProxyAgent（用户代理）。
3. 发起对话：user_proxy.initiate_chat(assistant, "请帮我写一个Python脚本来分析数据...")。
4. 自动协作：
   • Assistant 生成代码。
   • UserProxy 检测并执行代码。
   • UserProxy 将执行结果（成功输出或错误信息）发回给 Assistant。
   • Assistant 根据结果调试或生成下一步代码。
5. 循环：重复步骤 4，直到任务完成或达到轮数限制。
6. 终止：Assistant 发送 “TERMINATE” 信号，UserProxy 可能会询问用户是否满意。

通过组合这些核心功能和 API，你可以构建出极其强大和自动化的 AI 应用，从自动代码编写和数据分析到复杂的多专家决策系统。