OpenAI Swarm多智能体系统框架介绍和使用-AI应用

1 简介

探索符合人体工程学、轻量级的多智能体编排的教育框架。

Swarm 目前是一个实验性示例框架，旨在探索多智能体系统的人体工程学界面。它不打算用于生产，因此没有官方支持。（这也意味着我们不会审查 PR 或问题！）

2 安装

需要 Python 3.10+

pip install git+ssh://git@github.com/openai/swarm.git

或者

pip install git+https://github.com/openai/swarm.git

3 用法

from swarm import Swarm, Agent

client = Swarm()

def transfer_to_agent_b():
    return agent_b


agent_a = Agent(
    name="Agent A",
    instructions="You are a helpful agent.",
    functions=[transfer_to_agent_b],
)

agent_b = Agent(
    name="Agent B",
    instructions="Only speak in Haikus.",
)

response = client.run(
    agent=agent_a,
    messages=[{"role": "user", "content": "I want to talk to agent B."}],
)

print(response.messages[-1]["content"])

Hope glimmers brightly,
New paths converge gracefully,
What can I assist?

4 概述

Swarm 专注于使代理协调和执行变得轻量、高度可控且易于测试。

它通过两个基本抽象实现这一点：Agent和handoffs。 一个Agent包含instructions和tools，并且可以在任何时候选择将对话移交给另一个Agent。

这些原语足够强大，可以表达工具和代理网络之间的丰富动态，使您能够构建可扩展的真实世界解决方案，同时避免陡峭的学习曲线。

注意：

Swarm 代理与 Assistants API 中的 Assistants 无关。为了方便起见，它们的名称相似，但除此之外完全无关。Swarm 完全由 Chat Completions API 提供支持，因此在调用之间是无状态的。

5 为什么选择 Swarm

Swarm 探索了轻量级、可扩展且设计高度可定制的模式。与 Swarm 类似的方法最适合处理大量独立功能和指令的情况，这些功能和指令很难编码成单个提示。

对于寻求完全托管线程和内置内存管理和检索的开发人员来说，Assistant API 是一个不错的选择。但是，对于想要了解多代理编排的开发人员来说，Swarm 是一个教育资源。Swarm (几乎) 完全在客户端上运行，并且与 Chat Completions API 非常相似，不会在调用之间存储状态。

6 示例

查看/examples以寻找灵感！在 README 中详细了解每个内容。

• basic：设置、函数调用、交接和上下文变量等基础知识的简单示例
• triage_agent：设置基本分类步骤以移交给正确代理的简单示例
• weather_agent：函数调用的简单示例
• airline：用于在航空公司环境中处理不同客户服务请求的多代理设置。
• support_bot：一个客户服务机器人，其中包括一个用户界面代理和一个带有多种工具的帮助中心代理
• personal_shopper：可协助销售和退款的个人购物代理

7 文档

8 运行 Swarm

首先实例化一个 Swarm 客户端（其内部仅实例化一个OpenAI客户端）。

from swarm import Swarm

client = Swarm()
client.run()

Swarm 的run()功能类似于chat.completions.create()Chat Completions API 中的功能——它接收messages并返回messages，并且在调用之间不保存任何状态。但重要的是，它还处理 Agent 函数执行、交接、上下文变量引用，并且可以在返回给用户之前进行多次轮换。

从本质上讲，Swarmclient.run()实现了以下循环：

1. 从当前代理获取完成
2. 执行工具调用并附加结果
3. 必要时更换经纪人
4. 如果需要，更新上下文变量
5. 如果没有新的函数调用，则返回

参数

一旦client.run()完成（可能在多次调用代理和工具之后），它将返回Response包含所有相关更新状态的。具体来说，新的messages、最后Agent调用的和最新的context_variables。您可以将这些值（加上新用户消息）传递到下一次执行中，client.run()以继续上次中断的交互 – 就像chat.completions.create()。（该run_demo_loop函数实现了一个完整执行循环的示例/swarm/repl/repl.py。）

Response字段

9 代理

一个Agent简单地将一组instructions与一组functions（加上下面的一些附加设置）封装起来，并且能够将执行交给另一个Agent。

虽然将 拟人化为Agent“做 X 的人”很诱人，但它也可用于表示由一组instructions和定义的非常具体的工作流或步骤functions（例如一组步骤、复杂的检索、单个数据转换步骤等）。这允许Agents 组成一个由“代理”、“工作流”和“任务”组成的网络，所有这些都由相同的原语表示。

10 Agent字段

指示

Agent instructions直接转换为system对话提示（作为第一条消息）。 在任何给定时间，只有instructions活动的Agent才会出现（例如，如果有切换Agent，system提示会改变，但聊天记录不会改变。）

agent = Agent(
   instructions="You are a helpful agent."
)

可以instructions是常规的str，也可以是返回的函数str。该函数可以选择性地接收一个context_variables参数，该参数将由context_variables传入的填充client.run()。

def instructions(context_variables):
   user_name = context_variables["user_name"]
   return f"Help the user, {user_name}, do whatever they want."

agent = Agent(
   instructions=instructions
)
response = client.run(
   agent=agent,
   messages=[{"role":"user", "content": "Hi!"}],
   context_variables={"user_name":"John"}
)
print(response.messages[-1]["content"])

Hi John, how can I assist you today?

11 功能

• SwarmAgent可以直接调用python函数。
• 函数通常应该返回一个str（值将被尝试转换为一个str）。
• 如果函数返回Agent，则执行将转移到该函数Agent。
• 如果函数定义了context_variables参数，它将由context_variables传入的参数填充client.run()。

def greet(context_variables, language):
   user_name = context_variables["user_name"]
   greeting = "Hola" if language.lower() == "spanish" else "Hello"
   print(f"{greeting}, {user_name}!")
   return "Done"

agent = Agent(
   functions=[print_hello]
)

client.run(
   agent=agent,
   messages=[{"role": "user", "content": "Usa greet() por favor."}],
   context_variables={"user_name": "John"}
)

Hola, John!

• 如果Agent函数调用出现错误（缺少函数、错误参数、错误），错误响应将附加到聊天中，以便Agent可以正常恢复。
• 如果 调用了多个函数Agent，则它们将按顺序执行。

交接和更新上下文变量

一个人可以通过将其返回来Agent将其交给另一个人。Agentfunction

sales_agent = Agent(name="Sales Agent")

def transfer_to_sales():
   return sales_agent

agent = Agent(functions=[transfer_to_sales])

response = client.run(agent, [{"role":"user", "content":"Transfer me to sales."}])
print(response.agent.name)

Sales Agent

它还可以context_variables通过返回更完整的Result对象来更新。如果您希望单个函数返回值、更新代理并更新上下文变量（或三者中的任何子集），这还可以包含value和。agent

sales_agent = Agent(name="Sales Agent")

def talk_to_sales():
   print("Hello, World!")
   return Result(
       value="Done",
       agent=sales_agent,
       context_variables={"department": "sales"}
   )

agent = Agent(functions=[talk_to_sales])

response = client.run(
   agent=agent,
   messages=[{"role": "user", "content": "Transfer me to sales"}],
   context_variables={"user_name": "John"}
)
print(response.agent.name)
print(response.context_variables)

Sales Agent
{'department': 'sales', 'user_name': 'John'}

注意：

如果Agent调用多个函数来交给Agent，则只会使用最后一个交接函数。

功能模式

Swarm 自动将函数转换为传递到 Chat Completions 的 JSON 模式tools。

• 文档字符串被转换成函数description。
• 没有默认值的参数设置为required。
• 类型提示映射到参数type（默认为string）。
• 每个参数的描述尚未明确支持，但如果只是添加到文档字符串中，其作用应该类似。（将来可能会添加文档字符串参数解析。）

def greet(name, age: int, location: str = "New York"):
   """Greets the user. Make sure to get their name and age before calling.

   Args:
      name: Name of the user.
      age: Age of the user.
      location: Best place on earth.
   """
   print(f"Hello {name}, glad you are {age} in {location}!")

{
   "type": "function",
   "function": {
      "name": "greet",
      "description": "Greets the user. Make sure to get their name and age before calling.\n\nArgs:\n   name: Name of the user.\n   age: Age of the user.\n   location: Best place on earth.",
      "parameters": {
         "type": "object",
         "properties": {
            "name": {"type": "string"},
            "age": {"type": "integer"},
            "location": {"type": "string"}
         },
         "required": ["name", "age"]
      }
   }
}

12 流媒体

stream = client.run(agent, messages, stream=True)
for chunk in stream:
   print(chunk)

使用与Chat Completions API 流相同的事件。请参阅process_and_print_streaming_response作为/swarm/repl/repl.py示例。

添加了两种新事件类型：

• {"delim":"start"}和{"delim":"start"}，用于在 每次Agent处理单个消息（响应或函数调用）时发出信号。这有助于识别 之间的切换Agent。
• {"response": Response}为了方便起见，将Response在流末尾返回带有聚合（完整）响应的对象。

13 评估

评估对于任何项目都至关重要，我们鼓励开发人员自带评估套件来测试其集群的性能。作为参考，我们在 中提供了一些有关如何评估集群的示例airline，weather_agent以及triage_agent快速入门示例。有关更多详细信息，请参阅 README。

14 实用工具

使用run_demo_loop来测试您的 swarm！这将在您的命令行上运行 REPL。支持流式传输。

from swarm.repl import run_demo_loop
...
run_demo_loop(agent, stream=True)

15 核心贡献者

• Ilan Bigio – ibigio
• 詹姆斯·希尔斯 – jhills20
• Shyamal Anadkat – shyamal-anadkat
• Charu Jaiswal – charuj
• 科林·贾维斯 – colin-openai
• 卡蒂亚·吉尔·古兹曼 – katia-openai

翻译自：https://github.com/openai/swarm