深度解析Swarm Agent ：OpenAI 开源的多智能体协作框架

想象一下，你正在构建一个复杂的 AI 系统，它需要多个智能体协同工作才能完成任务。例如，一个智能客服系统，需要多个 AI Agent 分别负责处理用户的不同需求，如订单查询、退货处理、投诉处理等。这些 Agent 如同球队中的不同球员，各司其职，又相互配合。如何高效地协调这些 Agent 的行为，使它们能够协同工作，如同 一支训练有素的 AI 梦之队， 共同完成任务呢？

传统的编排方法通常需要编写大量的代码，并且难以扩展和维护。为了解决这个问题，OpenAI 推出了 Swarm 框架，一个旨在简化多智能体编排的革新性工具，让开发者能够轻松构建多智能体应用，像指挥家一样轻松驾驭多智能体协作。

• • Swarm 是 OpenAI 推出的用于多智能体编排的轻量级框架，如同一位指挥家，协调多个 AI Agent 协同完成复杂任务。

• • 它专注于代理协调和执行，并通过代理和交接两种基本抽象来实现。

• • Swarm 允许代理调用 Python 函数，并支持通过函数返回值更新上下文变量和进行代理交接。

• • Swarm 框架提供了高度的灵活性和可定制性，适用于各种多智能体应用场景。

Swarm 框架概述

Swarm 是一个实验性的教育框架，旨在探索人机交互式、轻量级的多智能体编排。 它专注于代理协调和执行，并通过代理和交接两种基本抽象来实现。

Swarm 的优势

相较于传统的编排方法，Swarm 框架具有以下优势：

• • 轻量级：Swarm 框架基于 Chat Completions API 构建，几乎完全在客户端运行，调用之间不存储状态，如同一位敏捷的教练，不会给队员增加额外的负担。

• • 可扩展性：Swarm 框架的设计易于扩展，可以处理大量独立的功能和指令，这些功能和指令难以编码到单个提示中，就像一支规模可随意扩展的队伍，可以应对各种挑战。

• • 高度可定制化：Swarm 框架允许开发者自定义代理的行为和功能，以及代理之间的交互方式，从而实现高度可定制化的解决方案，如同一位经验丰富的教练，可以根据队员的特点制定不同的战术。

Swarm 框架核心概念

Swarm 框架的核心是代理（Agent）和交接（Handoff），并通过例程（Routines）来定义 Agent 的行为模式。

代理 (Agent)

代理是 Swarm 框架中的基本单元，它封装了一组指令和工具，并可以选择将对话移交给另一个代理。 代理可以被看作是一个独立的实体，负责执行特定的任务，如同 AI 梦之队中的一位球员，拥有独特的技能和职责。它们可以通过以下方式完成任务：

• • 获取信息：代理可以调用函数或 API 来获取所需的信息，如同球员通过观察和沟通了解场上情况。

• • 处理数据：代理可以对获取到的信息进行处理，例如分析、转换、存储等，如同球员根据场上情况做出判断和决策。

• • 与其他代理通信：代理可以通过发送消息或调用函数来与其他代理进行通信，以协同完成任务，如同球员之间相互传球和配合。

交接 (Handoff)

交接是指代理之间转移执行控制权的过程。 当一个代理完成其任务后，它可以将控制权移交给另一个代理，以便继续执行任务，如同一位球员完成自己的任务后，将球传给另一位更适合处理当前情况的球员。交接机制使得代理之间可以协同工作，共同完成复杂的任务，例如：

• • 用户咨询：一个代理可以收集用户信息，然后将控制权移交给另一个代理来提供具体的解决方案，如同客服团队中，一位 Agent 负责初步了解用户问题，然后将问题转交给更专业的 Agent 处理。

• • 订单处理：一个代理可以接收订单，然后将控制权移交给另一个代理来处理支付和物流，如同电商平台中，一位 Agent 负责接收订单，然后将订单信息传递给负责支付和物流的 Agent。

例程 (Routines)

例程是一组预定义的步骤，用于指导代理完成特定任务。 例程可以包含条件判断、循环等逻辑结构，使得代理能够根据不同的情况执行不同的操作，如同 AI 梦之队中的战术手册，指导球员在不同情况下采取不同的行动。

Swarm 核心代码解析

Swarm 的核心代码主要集中在 swarm/swarm/core.py 和 swarm/swarm/repl/repl.py 两个文件中。

swarm/swarm/core.py：Swarm 框架核心逻辑

swarm/swarm/core.py 文件定义了 Swarm 框架的核心类和函数，包括 Swarm 类、Agent 类，以及一些辅助函数。

Swarm 类

Swarm 类是 Swarm 框架的主要入口点，它负责管理智能体、处理函数调用和更新上下文变量。

核心方法解析

• • get_chat_completion()：该方法负责向 OpenAI API 发送聊天完成请求，并返回 API 的响应。它接收当前活动的智能体、对话历史记录、上下文变量等参数，并将这些信息传递给 OpenAI API。

• • handle_function_result()：该方法负责处理函数调用的结果，将其转换为 Result 对象。 Result 对象包含函数的返回值、要转移到的目标 Agent（如果有），以及更新后的上下文变量。

• • handle_tool_calls()：该方法负责处理智能体发出的工具调用。它接收智能体发出的工具调用列表、智能体可以调用的函数列表、上下文变量等参数。该方法会遍历工具调用列表，找到对应的函数，执行函数，并将函数的执行结果和更新后的上下文变量返回。

• • run_and_stream()：该方法负责以流式方式运行 Swarm。它接收与 run 方法相同的参数，并返回一个生成器，该生成器会产生流式响应的各个部分。

• • run()：该方法负责运行 Swarm。它接收初始智能体、初始消息列表、上下文变量等参数，并根据参数启动 Swarm 的执行流程。该方法会循环执行以下步骤：获取智能体的响应，执行智能体调用的函数，更新上下文变量，以及根据需要进行智能体交接。

Agent 类

Agent 类代表 Swarm 中的智能体，它封装了智能体的名称、描述、指令、可调用函数列表等信息。 Agent 对象的 instructions 属性定义了该 Agent 的例程，即该 Agent 在处理任务时应遵循的步骤。

swarm/swarm/repl/repl.py：Swarm 交互式环境

swarm/swarm/repl/repl.py 文件定义了 Swarm 框架的 REPL（Read-Eval-Print Loop）界面，允许用户通过命令行与 Swarm 进行交互，体验 Swarm 的工作流程。

核心函数解析

• • process_and_print_streaming_response()：该函数负责处理流式响应，并将其打印到控制台。

• • pretty_print_messages()：该函数负责将消息列表以格式化的方式打印到控制台。

• • run_demo_loop()：该函数是 Swarm REPL 的主循环，它接收初始智能体、上下文变量等参数，并启动 REPL 界面。用户可以在 REPL 界面中输入消息，与智能体进行交互。在这个函数中，程序会根据用户的输入调用 run_full_turn 函数，该函数会根据当前 Agent 的例程和工具与用户进行交互，并在需要时执行交接操作，将控制权转移给其他 Agent。

Swarm Agent 核心函数示例：run_full_turn

run_full_turn 函数是 Swarm 框架的核心，它实现了代理的协调和执行，定义在swarm/swarm/repl/repl.py中：

def run_full_turn(agent, messages):

    current_agent = agent
    num_init_messages = len(messages)
    messages = messages.copy()

    while True:

        # 将 Python 函数转换为工具，并保存反向映射
        tool_schemas = [function_to_schema(tool) for tool in current_agent.tools]
        tools = {tool.__name__: tool for tool in current_agent.tools}

        # === 1. 获取 OpenAI 完成 ===
        response = client.chat.completions.create(
            model=agent.model,
            messages=[{"role": "system", "content": current_agent.instructions}]
            + messages,
            tools=tool_schemas or None,
        )
        message = response.choices[0].message
        messages.append(message)

        if message.content:  # 打印代理响应
            print(f"{current_agent.name}:", message.content)

        if not message.tool_calls:  # 如果已完成工具调用处理，则中断
            break

        # === 2. 处理工具调用 ===

        for tool_call in message.tool_calls:
            result = execute_tool_call(tool_call, tools, current_agent.name)

            if type(result) is Agent:  # 如果代理转移，更新当前代理
                current_agent = result
                result = (
                    f"Transfered to {current_agent.name}. Adopt persona immediately."
                )

            result_message = {
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": result,
            }
            messages.append(result_message)

    # ==== 3. 返回最后使用的代理和新消息 =====
    return Response(agent=current_agent, messages=messages[num_init_messages:])

代码分析

• • Agent: 函数接收一个 agent 对象作为参数，代表当前活动的智能体。

• • Routines: 函数使用 current_agent.instructions 作为系统消息发送给 OpenAI API，这代表了当前 Agent 的例程。

• • Handoffs: 函数会检查工具调用的结果是否为 Agent 对象。如果是，则更新当前 Agent，实现 Agent 之间的交接。

• • 循环处理: 函数在一个循环中执行，直到没有新的工具调用为止，确保 Agent 可以连续执行多个步骤，并根据需要进行交接。

Swarm Agent 协作实例：个人购物助手

为了更直观地展示 Swarm 框架的应用，我们以个人购物助手为例进行分析。参考内容4中提供了一个个人购物助手的案例，该案例中包含了以下代理：

• • Triage Agent：负责对用户的请求进行分类，并将其转发给相应的代理，如同 AI 梦之队中的队长，负责根据用户的需求分配任务。例如，如果用户询问关于订单的问题，Triage Agent 会将请求转发给 Sales Agent；如果用户询问关于退款的问题，Triage Agent 会将请求转发给 Refunds Agent。

• • Sales Agent：负责处理与订单相关的请求，例如下单、查询订单状态等，如同 AI 梦之队中负责进攻的球员。

• • Refunds Agent：负责处理与退款相关的请求，例如申请退款、查询退款进度等，如同 AI 梦之队中负责防守的球员。

以下代码展示了 Refunds Agent 的定义以及主程序的入口：

# 定义 Refunds Agent
refunds_agent = Agent(
    name="Refunds Agent",
    description=f"""你是一个退款代理，负责处理退货后的所有退款相关操作。
你必须索要用户 ID 和商品 ID 才能发起退款。请在一条消息中同时询问 user_id 和 item_id。
如果用户要求你通知他们，你必须询问他们 preferred method of notification 是什么。 对于通知，你必须
在一则消息中同时询问他们 user_id 和 method。""",
    functions=[refund_item, notify_customer],  # 包含 refund_item 函数
)

# ... 其他代码 ...

# 在主程序中运行 demo loop
if __name__ == "__main__":
    run_demo_loop(triage_agent, debug=False)

这段代码展示了如何定义一个 Refunds Agent，并将其添加到 Swarm 框架中，如同将一位球员招募到 AI 梦之队中。Refunds Agent 包含了 refund_item 函数，可以处理用户的退款请求，如同球员拥有特定的技能。

案例分析

个人购物助手案例展示了 Swarm 框架如何协调多个代理协同工作，如同 AI 梦之队如何在比赛中相互配合。Triage Agent 负责对用户的请求进行分类，并将其转发给相应的代理，如同队长根据场上情况指挥队员。Sales Agent 和 Refunds Agent 分别负责处理与订单和退款相关的请求，如同球员在各自的位置上发挥作用。通过代理之间的协作，个人购物助手可以为用户提供全面的服务，如同 AI 梦之队通过团队合作赢得比赛。在这个案例中：

• • Agent： Triage Agent、Sales Agent 和 Refunds Agent 都是 Swarm 中的 Agent，它们分别负责不同的任务。

• • Routines：每个 Agent 的 instructions 属性定义了该 Agent 的例程，即该 Agent 在处理任务时应遵循的步骤。例如，Refunds Agent 的例程要求它在处理退款请求时，必须先询问用户的 ID 和商品 ID。

• • Handoffs：Triage Agent 通过调用 transfer_to_sales_agent 或 transfer_to_issues_and_repairs 函数将控制权转移给 Sales Agent 或 Refunds Agent。这些函数返回目标 Agent，run_full_turn 函数会根据返回值更新当前 Agent，实现 Agent 之间的交接。

总结

Swarm Agent 框架是一个用于多智能体编排的强大工具，它为构建多智能体应用提供了全新的思路和方法。通过代理、例程和交接机制，Swarm 框架实现了代理之间的协同工作，并提供了高度的灵活性和可定制性。相信随着 Swarm 框架的不断发展，它将在更多领域得到应用，并为多智能体系统的发展带来新的突破， 让构建和管理 AI 梦之队变得更加轻松。

相关链接

• • Orchestrating Agents: Handoffs & Routines: https://cookbook.openai.com/examples/orchestrating_agents

• • Swarm Github Repository: https://github.com/openai/swarm