swarm

群（实验，教育）

一个教育框架，探索符合人体工程学，轻巧的多机构编排。

警告

Swarm目前是一个实验样本框架，旨在探索多代理系统的人体工程学接口。它不打算用于生产，因此没有官方支持。 （这也意味着我们不会审查PRS或问题！）

Swarm的主要目标是展示在编排代理商中探索的交接和例行图案：Handoffs＆Requines Cookbook。它并不是作为独立图书馆，主要是出于教育目的。

安装

需要Python 3.10+

pip install git+ssh://[email protected]/openai/swarm.git

或者

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

用法

 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?

目录

• 概述
• 例子
• 文档
  • 奔跑群
  • 代理商
  • 功能
  • 流
• 评估
• UTILS

概述

Swarm专注于使代理协调和执行轻巧，高度可控且易于测试。

它通过两个原始的抽象来实现这一目标： Agent和交接。 Agent包含instructions和tools ，并且可以随时选择将对话交给另一个Agent 。

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

笔记

群体代理与助手API中的助手无关。为了方便起见，它们的命名类似，但否则完全无关。 Swarm完全由聊天完成API提供动力，因此在呼叫之间无状态。

为什么要蜂拥而至

Swarm探索了轻巧，可扩展且高度可自定义的模式。类似于群的方法最适合处理大量独立功能和说明，这些功能和说明很难将其编码成一个提示。

助手API是寻求完全托管线程并内置内存管理和检索的开发人员的绝佳选择。但是，Swarm是一种教育资源，对于开发人员来说，好奇地了解多代理编排。 Swarm（几乎）完全在客户端上运行，就像聊天完成API一样，不会在呼叫之间存储状态。

例子

查看/examples以获取灵感！了解有关每个人中每个人的更多信息。

• basic ：基本原理的简单示例，例如设置，功能呼叫，交接和上下文变量
• triage_agent ：设置基本分类步骤的简单示例，将其交给正确的代理
• weather_agent ：功能调用的简单示例
• airline ：用于在航空公司环境下处理不同客户服务请求的多代理设置。
• support_bot ：一个包括用户界面代理和使用多个工具的帮助中心代理的客户服务机器人
• personal_shopper ：可以帮助销售和退款订单的个人购物代理

文档

奔跑群

首先实例化群客户端（仅在内部实例化OpenAI客户端）开始。

 from swarm import Swarm

client = Swarm ()

client.run()

swarm的run()函数类似于chat.completions.create()在聊天完成API中的功能 - 它接收messages并返回messages ，并且在呼叫之间没有保存状态。但是，重要的是，它还处理代理功能执行，交接，上下文变量引用，并且在返回用户之前可以进行多个转弯。

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

1. 从当前代理商那里完成
2. 执行工具调用并附加结果
3. 必要时开关代理
4. 更新上下文变量，如有必要
5. 如果没有新功能调用，请返回

争论

争论	类型	描述	默认
代理人	Agent	要调用的（初始）代理。	（必需的）
消息	List	消息对象的列表，与聊天完整messages相同	（必需的）
context_variables	dict	其他上下文变量的字典，可用于功能和代理说明	{}
max_turns	int	允许的最大对话回合数	float("inf")
model_override	str	可选字符串以覆盖代理使用的模型	None
execute_tools	bool	如果为False ，请中断执行并立即返回tool_calls消息，当代理试图调用函数时	True
溪流	bool	如果是True ，请启用流响应	False
调试	bool	如果为True ，请启用调试记录	False

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

Response字段

场地	类型	描述
消息	List	对话期间生成的消息对象的列表。与聊天完成messages非常相似，但是带有sender字段，指示该消息源自哪个Agent 。
代理人	Agent	处理消息的最后一个代理。
context_variables	dict	与输入变量相同，加上任何更改。

代理商

Agent只需将一组具有一组functions的instructions封装（以及下面的一些其他设置），并有能力将执行移交给另一个Agent 。

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

Agent字段

场地	类型	描述	默认
姓名	str	代理的名称。	"Agent"
模型	str	代理使用的模型。	"gpt-4o"
指示	str或func() -> str	代理的说明可以是字符串或可可返回字符串的说明。	"You are a helpful agent."
功能	List	代理可以调用​​的功能列表。	[]
tool_choice	str	代理商的工具选择（如果有）。	None

指示

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

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

instructions可以是常规str ，也可以是返回str函数。该函数可以选择接收context_variables参数，该参数将由传递到client.run() context_variables填充。

 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?

功能

• Swarm Agent S可以直接调用Python函数。
• 函数通常应返回str （将尝试以str形式施放值）。
• 如果函数返回Agent ，则执行将转移到该Agent 。
• 如果一个函数定义了context_variables参数，则将通过传递到client.run()上下文context_variables填充它。

 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 = [ greet ]
)

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

 Hola, John!

• 如果Agent函数调用有错误（丢失函数，错误的参数，错误），则将将错误响应附加到聊天中，以便Agent可以优雅地恢复。
• 如果Agent调用多个功能，则将按该顺序执行它们。

交接和更新上下文变量

Agent可以通过将其返回function中的另一个代理来移交给另一个Agent 。

 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

它还可以通过返回更完整的Result对象来更新context_variables 。如果您希望单个功能返回值，更新代理并更新上下文变量（或三个子集的任何子集），则可以包含一个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会自动将功能转换为JSON架构，该功能将传递到聊天完成tools中。

• DOCSTRINGS变成功能description 。
• 没有默认值的参数设置为required 。
• 类型提示映射到参数type （默认为string ）。
• 每参数描述不明确支持，但如果仅在DocString中添加，则应类似地工作。 （将来可能会添加DocString参数解析。）

 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.nnArgs: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流相同的事件。请参见/swarm/repl/repl.py中的process_and_print_streaming_response作为示例。

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

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

评估

评估对任何项目都至关重要，我们鼓励开发人员携带自己的评估套件来测试其群体的表现。作为参考，我们提供了一些示例，涉及如何在airline ， weather_agent和triage_agent Quickstart示例中评估群。有关更多详细信息，请参见READMES。

UTILS

使用run_demo_loop测试您的群！这将在您的命令行上运行一个重复。支持流。

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

核心贡献者

• Ilan Bigio -Ibigio
• 詹姆斯·希尔斯（James Hills）-Jhills20
• Shyamal Anadkat -Shyamal -Anadkat
• charu jaiswal- charuj
• Colin Jarvis -Colin -Openai
• Katia Gil Guzman -Katia -Openai