Framework educacional leve de orquestração multiagente desenvolvido pela OpenAI, focado na coordenação e execução de agentes.

OpenAI Swarm - Introdução Detalhada ao Framework de Orquestração Multi-Agente

Visão Geral do Projeto

OpenAI Swarm é um framework educacional para explorar a orquestração multi-agente leve e ergonômica. Este projeto, gerenciado pela equipe de soluções da OpenAI, visa fornecer aos desenvolvedores uma ferramenta simples, flexível e controlável para construir sistemas multi-agente.

Atualização Importante: O Swarm foi substituído pelo OpenAI Agents SDK, que é uma versão pronta para produção do Swarm. A equipe da OpenAI recomenda que todos os casos de uso de produção migrem para o Agents SDK.

Características Principais

1. Filosofia de Design

• Leve: Focado na simplicidade e facilidade de uso
• Altamente Controlável: Fornece mecanismos precisos de controle de agentes
• Fácil de Testar: Suporta processos simples de teste e depuração
• Orientado à Educação: Serve como um recurso educacional para aprender sobre orquestração multi-agente

2. Conceitos de Abstração Central

O Swarm implementa a coordenação de agentes através de duas abstrações centrais:

Agente

• Contém instruções e ferramentas
• Pode transferir a conversa para outro agente em qualquer ponto
• Suporta instruções dinâmicas e variáveis de contexto

Transferências (Handoffs)

• Mecanismo de transição perfeita entre agentes
• Suporta redes e fluxos de trabalho complexos de agentes
• Mantém a continuidade da conversa

Instalação e Uso Básico

Requisitos do Sistema

• Python 3.10+

Método de Instalação

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

Exemplo Básico

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

Exemplo de Saída:

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

Arquitetura Técnica

Mecanismo de Execução do Cliente

A função client.run() do Swarm implementa o seguinte ciclo:

1. Obtém a resposta completa do agente atual
2. Executa chamadas de ferramentas e adiciona os resultados
3. Troca de agente quando necessário
4. Atualiza as variáveis de contexto
5. Retorna o resultado se não houver novas chamadas de função

Configuração de Parâmetros

Parâmetro	Tipo	Descrição	Valor Padrão
agent	Agent	O agente (inicial) a ser chamado	(Obrigatório)
messages	List	Lista de objetos de mensagem	(Obrigatório)
context_variables	dict	Variáveis de contexto	{}
max_turns	int	Número máximo de turnos	float("inf")
model_override	str	Substituição do modelo	None
execute_tools	bool	Se deve executar ferramentas	True
stream	bool	Se deve habilitar a resposta em streaming	False
debug	bool	Se deve habilitar logs de depuração	False

Configuração do Agente

Campos da Classe Agent

Campo	Tipo	Descrição	Valor Padrão
name	str	Nome do agente	"Agent"
model	str	Modelo a ser usado	"gpt-4o"
instructions	str ou função	Instruções do agente	"You are a helpful agent."
functions	List	Lista de funções chamáveis	[]
tool_choice	str	Estratégia de escolha de ferramenta	None

Exemplo de Instruções Dinâmicas

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

Mecanismo de Chamada de Função

Chamada de Função Básica

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])

Transferência de Agente

sales_agent = Agent(name="Sales Agent")

def transfer_to_sales():
    return sales_agent

agent = Agent(functions=[transfer_to_sales])

Retorno de Resultados Complexos

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

Projetos de Exemplo

O Swarm fornece vários projetos de exemplo, mostrando diferentes cenários de aplicação:

1. basic - Exemplo Básico

Demonstra o uso básico de configuração, chamadas de função, transferências e variáveis de contexto

2. triage_agent - Agente de Triagem

Configuração simples de triagem, encaminhando solicitações para o agente apropriado

3. weather_agent - Agente de Clima

Mostra um exemplo simples de chamadas de função

4. airline - Atendimento ao Cliente de Companhia Aérea

Configuração multi-agente, lidando com diferentes tipos de solicitações de atendimento ao cliente de companhias aéreas

5. support_bot - Robô de Suporte

Inclui um agente de interface de usuário e um agente de central de ajuda com várias ferramentas

6. personal_shopper - Assistente de Compras Pessoal

Assistente de compras pessoal para ajudar no processamento de vendas e pedidos de reembolso

Processamento de Streaming

O Swarm suporta respostas em streaming, usando os mesmos eventos da API Chat Completions:

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

Novos tipos de eventos:

• {"delim":"start"} e {"delim":"end"} - Marcam o início e o fim do processamento de uma única mensagem pelo agente
• {"response": Response} - Retorna o objeto Response completo no final do stream

Teste e Avaliação

Teste de Desenvolvimento

Use run_demo_loop para testes de linha de comando:

from swarm.repl import run_demo_loop

run_demo_loop(agent, stream=True)

Sugestões de Avaliação

• O projeto incentiva os desenvolvedores a trazerem seus próprios conjuntos de avaliação
• Referências de avaliação são fornecidas nos exemplos airline, weather_agent e triage_agent
• Suporta métricas de teste de desempenho personalizadas

Diferenças de Outros Produtos OpenAI

Comparação com a API Assistants

• API Assistants: Fornece threads totalmente gerenciados e gerenciamento de memória integrado
• Swarm: Executa completamente no cliente, design sem estado, mais adequado para aprendizado e experimentação

Características Técnicas

• Construído com base na API Chat Completions
• Não salva o estado entre as chamadas
• Implementação de cliente leve
• Focado em fins educacionais e de aprendizado

Cenários de Aplicação

O Swarm é particularmente adequado para as seguintes situações:

• Cenários que exigem o processamento de um grande número de funções e instruções independentes
• Tarefas complexas difíceis de codificar em um único prompt
• Aprender conceitos de orquestração multi-agente
• Desenvolvimento rápido de protótipos e experimentação

Status do Projeto

Atenção: Embora o Swarm tenha sido substituído pelo OpenAI Agents SDK, ele ainda é um excelente recurso educacional para ajudar os desenvolvedores a entender os conceitos básicos e a implementação de sistemas multi-agente. Para ambientes de produção, recomenda-se migrar para o Agents SDK oficial.

Resumo

O OpenAI Swarm fornece um framework conciso e poderoso para o aprendizado e desenvolvimento de sistemas multi-agente. Através dos dois conceitos centrais de agentes e transferências, os desenvolvedores podem construir fluxos de trabalho de IA complexos, mantendo a legibilidade e a manutenção do código. Embora tenha sido substituído pelo novo SDK, sua filosofia de design e valor educacional permanecem importantes.