[Swarm] Swarm框架 | AI智能体

docs：Swarm框架

Swarm是用于构建多智能体系统的框架，由语言模型驱动。

其运作模式如同指挥家(Swarm)协调专业乐手(智能体)，这些乐手使用特定的演奏技法(功能)进行互动。

它负责管理对话流程、执行这些技能、通过共享乐谱(上下文变量)传递信息、允许智能体交接指挥权(智能体交接)，并提供交互摘要(响应)，可结构化复杂技能的执行结果(执行结果)。

可视化概览

章节结构

1. Swarm框架
2. 智能体
3. 上下文变量
4. 功能
5. 执行结果
6. 智能体交接
7. 响应

第1章：Swarm

欢迎来到swarm！

在首章中，我们将介绍框架的核心组件：Swarm类。

想象构建基于大语言模型（如ChatGPT）的应用如同指挥交响乐团。我们需要协调不同乐手（智能体）使用不同乐器（工具或功能），而指挥家的作用就是将这一切组织起来。

在swarm项目中，Swarm类正是这个指挥家。

什么是Swarm？

Swarm是管理用户、智能体与AI模型之间交互循环的核心控制器。

它接收初始指令和对话历史，决定当前哪个智能体处于激活状态，解析AI下一步意图（如生成响应或使用功能），执行必要操作，并判定对话何时终止。

简言之，当我们需要启动或延续与AI系统的交互时，直接对话对象就是Swarm。

基础使用

让我们通过简单示例了解Swarm的基本用法：提出单一问题并获取AI响应。

首先创建Swarm实例。我们可以提供OpenAI客户端（或兼容客户端），若未提供则自动通过环境变量（如OPENAI_API_KEY）创建：

from swarm import Swarm, Agent

# 创建Swarm实例
# 若已配置API密钥将自动使用
client = Swarm()

接着需要初始智能体。后续章节将深入讲解，目前只需理解智能体代表AI的角色身份，可具备特定能力（如使用功能）。本例使用基础智能体即可：

# 创建基础智能体（详见第2章）
agent = Agent()

然后定义对话起点消息列表，格式与多数AI模型的消息历史兼容：

# 定义初始用户消息
messages = [{"role": "user", "content": "你好，最近怎么样？"}]

通过Swarm的run方法启动对话：

# 使用Swarm运行对话
response = client.run(agent=agent, messages=messages)

# 打印AI响应
print(response.messages[-1]['content'])

执行流程：

1. 创建Swarm
2. 创建基础智能体
3. 提供初始用户消息
4. 指示Swarm以该智能体和消息启动对话
5. Swarm将消息发送至AI模型（使用指定智能体的配置）
6. AI模型生成响应
7. Swarm接收响应并封装为响应对象
8. run方法返回该响应对象
9. 可访问交互细节，包括AI的最终消息

输出示例：

我很好，谢谢！今天有什么可以帮您的吗？

该简单示例展示了Swarm作为对话流程管理中心的基础能力。

运行机制（单轮对话解析）

以下是run方法内部处理逻辑的可视化呈现：

对于工具调用这部分，前文专栏传送：MCP Servers

swarm/core.py中的核心代码简化说明：

Swarm类定义：

# File: swarm/core.py

class Swarm:
    def __init__(self, client=None):
        # 配置AI模型客户端
        if not client:
            # 默认使用OpenAI客户端
            client = OpenAI()
        self.client = client

    def run(
        self,
        agent: Agent,
        messages: List,
        # ... 其他参数 ...
    ) -> Response:
        # 用户调用的主方法
        active_agent = agent # 从指定智能体开始
        history = copy.deepcopy(messages) # 深拷贝初始消息
        init_len = len(messages) # 记录原始消息长度

        # 循环持续至达到最大轮次或AI终止交互
        while len(history) - init_len < max_turns and active_agent:

            # 获取AI补全（核心交互步骤）
            completion = self.get_chat_completion(
                agent=active_agent,
                history=history,
                # ... 其他参数 ...
            )
            message = completion.choices[0].message # 提取AI消息
            message.sender = active_agent.name # 添加智能体名称（内部使用）
            # 将AI消息加入对话历史
            history.append(json.loads(message.model_dump_json()))

            # 若AI未请求工具调用，终止当前循环
            # execute_tools默认为True，因此无tool_calls时直接跳出
            if not message.tool_calls or not execute_tools:
                debug_print(debug, "终止当前轮次。")
                break # 退出循环

            # ...（处理工具调用，后续章节详解）...

        # 返回最终响应对象
        return Response(
            messages=history[init_len:], # 仅返回本轮生成的消息
            agent=active_agent, # 返回最终活跃智能体
            context_variables=context_variables, # 返回更新的上下文变量
        )

get_chat_completion方法解析：

# File: swarm/core.py

    def get_chat_completion(
        self,
        agent: Agent,
        history: List,
        context_variables: dict,
        model_override: str,
        stream: bool,
        debug: bool,
    ) -> ChatCompletionMessage:
        # 通过智能体和上下文准备系统指令
        instructions = (
            agent.instructions(context_variables)
            if callable(agent.instructions)
            else agent.instructions
        )
        # 合并系统指令与历史消息
        messages = [{"role": "system", "content": instructions}] + history

        # 准备智能体可用工具（后续详解）
        tools = [function_to_json(f) for f in agent.functions]
        # ...（上下文变量隐藏逻辑）...

        # 配置OpenAI补全调用参数
        create_params = {
            "model": model_override or agent.model, # 使用智能体模型或覆盖值
            "messages": messages,
            "tools": tools or None, # 包含工具配置（若有）
            "tool_choice": agent.tool_choice,
            "stream": stream,
        }

        # 调用底层AI模型客户端
        return self.client.chat.completions.create(**create_params)

在简单文本响应场景中（无功能调用），run方法将AI消息加入历史记录后即退出循环，返回最终响应对象。

小结

本章我们认识到Swarm是AI智能体系统的指挥中枢。

• 作为主要交互接口，它接收初始智能体和消息历史，与AI模型通信，并返回响应对象封装结果。

• 虽然当前示例较为简单，但Swarm设计用于处理复杂场景，包括智能体使用功能及对话接力至其他智能体。

了解Swarm的对话管理机制后，让我们聚焦个体执行者：智能体！

第2章：智能体

第2章：智能体

在第1章中，我们认识了Swarm——这个管理多智能体系统对话流程与交互的指挥家。

现在，让我们将目光投向乐团中的个体演奏家：智能体(Agent)。

什么是智能体？

回想我们的乐团比喻。指挥家(Swarm)需要精通特定角色和乐器的演奏家。Agent正是这样的专业演奏家。

swarm中的每个Agent代表：

1. 角色或身份：AI的人格特征或职务描述（如乐于助人的助手、气象专家或客服机器人）
2. 指令集：定义AI行为规范的系统提示（如同乐谱指导演奏家如何演绎）
3. 技能(函数)：AI知晓的特定操作或工具（如查询天气或访问数据库的能力）

智能体是构建AI系统差异化能力的核心模块。

为什么需要智能体？

假设我们需要构建具备多种能力的应用：回答通用问题、查询股价、预订餐厅。

我们可以尝试将所有指令和技能塞进单个AI模型的巨型提示词中。但这会迅速导致混乱！AI可能发生指令混淆、工具误用等问题。

swarm的解决方案是创建独立的专业Agent：

• 用于聊天的"通用助手"智能体
• 具备股价查询技能的"股票市场"智能体
• 配备餐厅搜索与预订技能的"餐厅预订专家"智能体

Swarm将动态管理当前活跃的智能体，甚至在话题变更时实现智能体间的"接力交接"（详见第6章：智能体交接）。

创建首个智能体

在第1章中，我们使用了未配置的基础Agent：

from swarm import Agent

# 创建基础智能体
agent = Agent()

这将创建使用默认配置的Agent：

• 名称：“Agent”
• 默认AI模型：“gpt-4o”（依赖库默认）
• 基础指令：“你是一个有用的智能体”
• 无特定技能

现在创建具有明确职能的智能体——天气预报员：

from swarm import Agent

weather_reporter_agent = Agent(
    name="气象播报员",
    instructions="你是一位友好的气象播报员。始终提供指定地点的实时天气与简要预报。若无法获取天气信息请明确说明。"
    # 我们将在后续章节添加功能（技能）！
)

该智能体专为天气任务设计，具有清晰的名称和角色定义。

在Swarm中使用智能体

在Swarm中使用定制智能体与第1章的简单示例类似：将智能体实例传递给Swarm.run()方法。

from swarm import Swarm, Agent

# 创建专用智能体
weather_reporter_agent = Agent(
    name="气象播报员",
    instructions="你是一位友好的气象播报员。始终提供指定地点的实时天气与简要预报。若无法获取天气信息请明确说明。"
)

# 创建Swarm实例
client = Swarm()

# 定义初始消息
messages = [{"role": "user", "content": "今天的天气如何？"}]

# 使用气象播报员智能体运行对话
response = client.run(agent=weather_reporter_agent, messages=messages)

# 打印AI响应
print(response.messages[-1]['content'])

运行时，Swarm会将用户消息与weather_reporter_agent的指令（“你是一位友好的气象播报员…”）组合发送至AI模型。

AI将基于合并输入生成符合角色设定的响应。

输出可能如下：

我可以为您提供天气信息，但需要知道具体位置！您想问哪个城市的天气？

注意AI响应如何体现智能体指令——因角色需要而主动询问位置信息。

智能体配置参数

Agent类支持以下关键参数配置：

对于初学者，建议优先掌握name、model和instructions的配置。

运行机制：Swarm如何运用智能体

回顾第1章的Swarm.run()方法，结合当前对Agent的理解：

当调用client.run(agent=my_agent, messages=...)时，Swarm使用my_agent对象配置AI模型调用。

具体来说，Swarm通过agent.instructions和agent.model参数准备AI请求：

该过程发生在Swarm的get_chat_completion方法中（run方法内部调用）：

# File: swarm/core.py (简化版)

class Swarm:
    # ... __init__ 方法 ...

    def get_chat_completion(
        self,
        agent: Agent, # 接收智能体对象
        history: List,
        # ... 其他参数 ...
    ):
        # 1. 获取智能体指令
        # 支持字符串或函数形式（后续详解）
        instructions = (
            agent.instructions(...)
            if callable(agent.instructions)
            else agent.instructions
        )

        # 2. 准备包含系统指令的AI消息
        messages = [{"role": "system", "content": instructions}] + history

        # 3. 获取智能体功能（后续详解）
        tools = [...] # 使用agent.functions

        # 4. 准备AI调用参数
        create_params = {
            "model": agent.model, # 使用智能体指定模型
            "messages": messages,
            "tools": tools or None,
            # ... 其他智能体配置 ...
        }

        # 5. 调用底层AI模型客户端
        return self.client.chat.completions.create(**create_params)

由此可见，Agent对象是Swarm进行AI调用的配置源。

这使得无需修改Swarm.run()核心逻辑，即可轻松切换具备不同角色、模型和能力的智能体。

(这种解耦合的设计，在操作系统中也很常见）

小结

我们认识到Agent是swarm系统中的专业AI角色。

每个智能体都有名称、指令（定义角色）和潜在技能（功能）。通过创建不同智能体，我们可以构建具备差异化功能的系统。

我们学习了基础智能体的创建方法，以及Swarm如何运用智能体配置（名称、模型、指令、功能）与AI模型交互。

下一章，我们将探索如何通过上下文变量实现智能体指令与函数调用的动态调整！

第3章：上下文变量