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

对于寻求完全托管线程和内置内存管理和检索的开发人员来说，Assistants API 是一个不错的选择。然而，Swarm 是一个教育资源，适合那些想了解多代理编排的开发人员。 Swarm（几乎）完全在客户端上运行，并且与聊天完成 API 非常相似，不存储调用之间的状态。

示例查看/examples灵感！在其自述文件中了解有关每一项的更多信息。

basic：基础知识的简单示例，例如设置、函数调用、切换和上下文变量

triage_agent：设置基本分类步骤以将其移交给正确的代理的简单示例

weather_agent：函数调用的简单例子

airline：多代理设置，用于在航空公司环境中处理不同的客户服务请求。

support_bot：客户服务机器人，包括用户界面代理和带有多种工具的帮助中心代

personal_shopper：可以帮助销售和退款的个人代购文档

奔跑的蜂群

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

from swarm import Swarm

client = Swarm()

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

Swarm 的核心client.run()实现了以下循环：

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

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

AnAgent简单地封装了一组instructions和 一组functions（加上下面的一些附加设置），并且具有将执行移交给另一个 的能力Agent。

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

Agent instructions直接转换为system对话的提示（作为第一条消息）。在任何给定时间，只会出现instructions活动的内容（例如，如果发生切换，提示将会更改，但聊天历史记录不会更改。）AgentAgentsystem

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?

• SwarmAgent可以直接调用python函数。
• 函数通常应返回 a str（值将尝试转换为 a str）。
• 如果函数返回 an 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对象来更新 。如果您希望单个函数返回值、更新代理并更新上下文变量（或三者的任何子集），它还可以包含 avalue和 an 。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'}

Swarm 自动将函数转换为 JSON 模式，并传递到 Chat Completions 中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"]
      }
   }
}

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

使用与聊天完成 API 流相同的事件。请process_and_print_streaming_response参阅/swarm/repl/repl.py示例。

添加了两种新的事件类型：

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

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

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