swarm

Enjambre (experimental, educativo)

Un marco educativo que explora la orquestación ergonómica y ligera de múltiples agentes.

Advertencia

Swarm es actualmente un marco de muestra experimental destinado a explorar interfaces ergonómicas para sistemas de múltiples agentes. No está destinado a ser utilizado en la producción y, por lo tanto, no tiene apoyo oficial. (¡Esto también significa que no revisaremos PR o problemas!)

El objetivo principal de Swarm es mostrar los patrones de transferencia y rutinas explorados en los agentes de orquestación: el libro de cocina de transferencia y rutinas. No se entiende como una biblioteca independiente, y es principalmente para fines educativos.

Instalar

Requiere Python 3.10+

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

o

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

Uso

 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?

Tabla de contenido

• Descripción general
• Ejemplos
• Documentación
  • Running enjambre
  • Agentes
  • Funciones
  • Transmisión
• Evaluaciones
• Tensiones

Descripción general

Swarm se centra en hacer que la coordinación y la ejecución del agente sean livianas, altamente controlables y fácilmente comprobables.

Logra esto a través de dos abstracciones primitivas: Agent y traseros . Un Agent abarca instructions y tools , y en cualquier momento puede elegir entregar una conversación a otro Agent .

Estas primitivas son lo suficientemente potentes como para expresar una rica dinámica entre herramientas y redes de agentes, lo que le permite construir soluciones escalables del mundo real mientras evita una curva de aprendizaje pronunciada.

Nota

Los agentes de enjambre no están relacionados con asistentes en la API de asistentes. Se nombran de manera similar por conveniencia, pero por lo demás no están completamente relacionados. El enjambre funciona completamente con la API de finalización de chat y, por lo tanto, es apátrate entre las llamadas.

Por qué enjambre

Swarm explora patrones que son livianos, escalables y altamente personalizables por diseño. Los enfoques similares a Swarm son los más adecuados para situaciones que tratan con una gran cantidad de capacidades e instrucciones independientes que son difíciles de codificar en un solo mensaje.

La API de Asistentes es una excelente opción para los desarrolladores que buscan hilos totalmente alojados y gestión y recuperación incorporadas de memoria. Sin embargo, Swarm es un recurso educativo para los desarrolladores curiosos para aprender sobre la orquestación de múltiples agentes. Swarm se ejecuta (casi) completamente en el cliente y, al igual que la API de finalización de chat, no almacena el estado entre las llamadas.

Ejemplos

¡Mira /examples para inspiración! Obtenga más información sobre cada uno en su lectura.

• basic : Ejemplos simples de fundamentos como configuración, llamadas de funciones, transferencias y variables de contexto
• triage_agent : ejemplo simple de configurar un paso de triaje básico para entregar al agente derecho
• weather_agent : ejemplo simple de llamadas de funciones
• airline : una configuración de múltiples agentes para manejar diferentes solicitudes de servicio al cliente en un contexto de la aerolínea.
• support_bot : un bot de servicio al cliente que incluye un agente de interfaz de usuario y un agente de centro de ayuda con varias herramientas
• personal_shopper : un agente de compras personal que puede ayudar a realizar pedidos de ventas y reembolsos

Documentación

Running enjambre

Comience instanciando a un cliente de enjambre (que internamente solo instancia a un cliente OpenAI ).

 from swarm import Swarm

client = Swarm ()

client.run()

La función run() de Swarm es análoga a la función chat.completions.create() en la API de finalización de chat: toma messages y devuelve messages y no guarda estado entre las llamadas. Es importante destacar que también maneja la ejecución de la función del agente, las transferencias, las referencias variables de contexto y puede tomar múltiples turnos antes de volver al usuario.

En su núcleo, Swarm's client.run() implementa el siguiente bucle:

1. Completar el agente actual
2. Ejecutar llamadas de herramienta y agregar resultados
3. Cambiar agente si es necesario
4. Actualizar variables de contexto, si es necesario
5. Si no hay nuevas llamadas de función, regrese

Argumentos

Argumento	Tipo	Descripción	Por defecto
agente	Agent	El agente (inicial) a llamar.	(requerido)
mensajes	List	Una lista de objetos de mensajes, idénticos a messages de finalización de chat	(requerido)
context_variables	dict	Un diccionario de variables de contexto adicionales, disponibles para funciones e instrucciones de agente	{}
Max_Turns	int	El número máximo de giros conversacionales permitidos	float("inf")
modelo_override	str	Una cadena opcional para anular el modelo que usa un agente	None
ejecutar_tools	bool	Si False , interrumpe la ejecución y devuelve inmediatamente el mensaje tool_calls cuando un agente intenta llamar a una función	True
arroyo	bool	Si es True , habilita las respuestas de transmisión	False
depurar	bool	Si es True , habilita el registro de depuración	False

Una vez que client.run() está finalizado (después de potencialmente múltiples llamadas a agentes y herramientas), devolverá una Response que contenga todo el estado actualizado relevante. Específicamente, los nuevos messages , el último Agent que se llamará y los context_variables más actualizados. Puede pasar estos valores (más los nuevos mensajes de usuario) en su próxima ejecución de client.run() para continuar la interacción donde lo dejó, al igual que chat.completions.create() . (La función run_demo_loop implementa un ejemplo de un bucle de ejecución completo en /swarm/repl/repl.py .)

Campos Response

Campo	Tipo	Descripción
mensajes	List	Una lista de objetos de mensaje generados durante la conversación. Muy similar a messages de finalización de chat, pero con un campo sender que indica de qué Agent se originó el mensaje.
agente	Agent	El último agente en manejar un mensaje.
context_variables	dict	Lo mismo que las variables de entrada, más cualquier cambio.

Agentes

Un Agent simplemente encapsula un conjunto de instructions con un conjunto de functions (más algunas configuraciones adicionales a continuación), y tiene la capacidad de entregar la ejecución a otro Agent .

Si bien es tentador personificar a un Agent como "alguien que hace X", también se puede usar para representar un flujo de trabajo o paso muy específico definido por un conjunto de instructions y functions (por ejemplo, un conjunto de pasos, una recuperación compleja, un solo paso de Transformación de datos, etc.). Esto permite que Agent se compongan en una red de "agentes", "flujos de trabajo" y "tareas", todas representadas por la misma primitiva.

Campos de Agent

Campo	Tipo	Descripción	Por defecto
nombre	str	El nombre del agente.	"Agent"
modelo	str	El modelo a ser utilizado por el agente.	"gpt-4o"
instrucciones	str o func() -> str	Las instrucciones para el agente pueden ser una cadena o una llamada que devuelve una cadena.	"You are a helpful agent."
funciones	List	Una lista de funciones que el agente puede llamar.	[]
Tool_Choice	str	La elección de la herramienta para el agente, si lo hay.	None

Instrucciones

instructions Agent se convierten directamente en la solicitud system de una conversación (como el primer mensaje). Solo las instructions del Agent activo estarán presentes en un momento dado (por ejemplo, si hay una transferencia Agent , el mensaje system cambiará, pero el historial de chat no lo hará).

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

Las instructions pueden ser un str regular o una función que devuelve un str . La función puede recibir opcionalmente un parámetro context_variables , que estará poblado por el context_variables pasado a 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?

Funciones

• Swarm Agent s puede llamar a las funciones de Python directamente.
• La función generalmente debe devolver un str (los valores se intentarán lanzar como str ).
• Si una función devuelve un Agent , la ejecución se transferirá a ese Agent .
• Si una función define un parámetro context_variables , estará poblada por el context_variables pasados ​​en 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 = [ greet ]
)

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

 Hola, John!

• Si una llamada de función Agent tiene un error (función faltante, argumento incorrecto, error) una respuesta de error se agregará al chat para que el Agent pueda recuperarse con gracia.
• Si el Agent llame a múltiples funciones, se ejecutarán en ese orden.

Transferencias y actualizaciones de variables de contexto

Un Agent puede transmitirse a otro Agent devolviéndolo en una function .

 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

También puede actualizar los context_variables devolviendo un objeto Result más completo. Esto también puede contener un value y un agent , en caso de que desee una sola función para devolver un valor, actualizar el agente y actualizar las variables de contexto (o cualquier subconjunto de los tres).

 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'}

Nota

Si un Agent llama a múltiples funciones para transmitir a un Agent , solo se utilizará la última función de transferencia.

Esquemas de funciones

Swarm convierte automáticamente las funciones en un esquema JSON que se pasa a tools de finalización de chat.

• Los documentos se convierten en la description de la función.
• Los parámetros sin valores predeterminados se establecen en required .
• Los sugerencias de tipo se asignan al type del parámetro (y predeterminado a string ).
• Las descripciones por parámetro no son compatibles explícitamente, pero deberían funcionar de manera similar si se acaba de agregar en el documento. (En el futuro, se puede agregar un análisis de argumentos de documentos).

 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" ]
      }
   }
} 

Transmisión

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

Utiliza los mismos eventos que la transmisión de API de finalización de chat. Consulte process_and_print_streaming_response en /swarm/repl/repl.py como ejemplo.

Se han agregado dos nuevos tipos de eventos:

• {"delim":"start"} y {"delim":"end"} , para indicar cada vez que un Agent maneja un solo mensaje (llamada de respuesta o función). Esto ayuda a identificar los interruptores entre Agent .
• {"response": Response} devolverá un objeto Response al final de una secuencia con la respuesta agregada (completa), por conveniencia.

Evaluaciones

Las evaluaciones son cruciales para cualquier proyecto, y alentamos a los desarrolladores a traer sus propios suites Eval para probar el rendimiento de sus enjambres. Como referencia, tenemos algunos ejemplos sobre cómo evaluar ejemplos de enjambre en la airline , weather_agent y triage_agent rápida. Vea los lectores para más detalles.

Tensiones

¡Usa el run_demo_loop para probar tu enjambre! Esto ejecutará una replica en su línea de comando. Admite la transmisión.

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

Contribuyentes centrales

• Ilan Bigio - Ibigio
• James Hills - Jhills20
• Shyamal Anadkat - Shyamal -Anadkat
• Charu Jaiswal - Charuj
• Colin Jarvis - Colin -Openai
• Katia Gil Guzman - Katia -Openai