Phase 16 - Lesson 11

Handoffs e Rotinas — Orquestração sem Estado

O Swarm da OpenAI (outubro de 2024) destilou a orquestração multiagente em duas primitivas: rotinas (instruções + ferramentas como um prompt de sistema) e handoffs (uma ferramenta que retorna outro Agent). Sem máquina de estados, sem DSL de ramificação — o LLM faz o roteamento chamando a ferramenta de handoff correta. O OpenAI Agents SDK (março de 2025) é o sucessor de produção. O Swarm em si continua sendo a referência conceitual mais limpa — todo o seu código-fonte cabe em algumas centenas de linhas. O padrão viralizou porque a superfície da API é basicamente "agent = prompt + tools; handoff = function returning agent." Limitação: stateless, portanto a memória é problema do chamador.

Tipo: Learn + Build Linguagens: Python (stdlib) Pré-requisitos: Fase 16 · 04 (O Modelo de Primitivas Multiagente) Tempo: ~60 minutos

O Problema

Todo framework multiagente quer que você aprenda sua DSL: nós e arestas do LangGraph, crews e tarefas do CrewAI, GroupChat e gerenciadores do AutoGen. As DSLs são abstrações reais, mas fazem com que a coisa pareça mais pesada do que precisa ser.

O Swarm empurra na direção oposta: usar a capacidade de chamada de ferramenta que o modelo já possui. Handoffs tornam-se chamadas de ferramenta. O orquestrador é o agente que possui a conversa no momento. A máquina de estados está implícita nos prompts de sistema dos agentes.

O Conceito

Duas primitivas

Rotina. Um prompt de sistema que define o papel de um agente e suas ferramentas disponíveis. Pense nisso como um conjunto delimitado de instruções: "você é um agente de triagem; se o usuário perguntar sobre reembolsos, passe para o agente de reembolso."

Handoff. Uma ferramenta que o agente pode chamar que retorna um novo objeto Agent. O runtime do Swarm detecta o valor de retorno de Agent e troca o agente ativo para o próximo turno.

Essa é toda a abstração.

def transfer_to_refunds():
    return refund_agent  # Swarm sees Agent return → switch active agent

triage_agent = Agent(
    name="triage",
    instructions="Route the user to the right specialist.",
    functions=[transfer_to_refunds, transfer_to_sales, transfer_to_support],
)

O prompt de sistema do agente de triagem faz com que ele escolha o handoff correto com base na mensagem do usuário. A chamada de ferramenta do LLM faz o roteamento.

Por que viralizou

• API pequena. Apenas dois conceitos para aprender.
• Usa o que o modelo já faz. A chamada de ferramenta já é de nível de produção entre os provedores.
• Sem o fardo de uma máquina de estados. Você não descreve o grafo; os prompts dos agentes descrevem para quem eles passam a conversa.

A troca do stateless

O Swarm é explicitamente stateless entre execuções. O framework mantém um histórico de mensagens durante uma execução, mas não persiste nada. Memória, continuidade, tarefas de longa duração — tudo é problema do chamador.

Na produção (OpenAI Agents SDK, março de 2025), essa foi uma das principais coisas que mudou: o SDK adiciona gerenciamento de sessão integrado, guardas (guardrails) e rastreamento (tracing), mantendo a primitiva de handoff.

Quando o Swarm/handoffs se encaixam

• Padrões de triagem. O agente da linha de frente encaminha o usuário para um especialista.
• Handoffs baseados em habilidades. "Se a tarefa precisar de código, chame o programador; se precisar de pesquisa, chame o pesquisador."
• Conversas curtas e delimitadas. Suporte ao cliente, perguntas frequentes para ticket, fluxos de trabalho simples.

Quando o Swarm tem dificuldades

• Sessões longas com memória compartilhada. Os handoffs redefinem o estado da conversa para o prompt do novo agente mais o histórico. Sem estado persistente entre agentes sem memória gerenciada pelo chamador.
• Execução paralela. O handoff é individual — o agente ativo muda. O paralelismo exige que o chamador orquestre várias execuções do Swarm.
• Auditoria e replay. Execuções stateless são difíceis de reproduzir exatamente; a escolha de handoff do LLM não é determinística.

OpenAI Agents SDK (março de 2025)

O sucessor de produção adiciona:

• Estado de sessão. Thread persistente entre execuções.
• Guardrails. Ganchos de validação de entrada/saída.
• Tracing. Cada chamada de ferramenta e handoff é registrada.
• Filtros de handoff. Controlam qual contexto é transferido no handoff.

A primitiva de handoff sobrevive; a ergonomia de produção é adicionada ao redor dela.

Swarm vs GroupChat

Ambos usam roteamento direcionado por LLM, mas diferem em quem escolhe o próximo:

• GroupChat: um seletor (função ou LLM) escolhe o próximo interlocutor pelo lado de fora.
• Swarm: o agente atual escolhe seu sucessor chamando uma ferramenta de handoff.

Swarm é "o agente decide o que vem a seguir"; GroupChat is "o gerente decide o que vem a seguir." A decisão do Swarm vive na chamada de ferramenta do agente ativo; a do GroupChat vive no GroupChatManager.

Construa

code/main.py implementa o Swarm do zero: uma classe de dados Agent, um mecanismo de handoff (ferramenta retorna Agent) e um loop de execução que detecta trocas de agentes.

Demonstração: um agente de triagem encaminha para especialistas em reembolsos, vendas ou suporte. Cada especialista tem suas próprias ferramentas. O loop de execução imprime cada handoff.

Executar:

python3 code/main.py

Use

outputs/skill-handoff-designer.md projeta uma topologia de handoff para uma determinada tarefa: quais agentes existem, quais handoffs eles podem chamar, quais contextos são transferidos.

Envie

Checklist:

• Registro de handoff. Cada handoff grava um evento de rastreamento com from-agent, to-agent, snapshot do contexto.
• Regras de transferência de contexto. Decida o que é transferido no handoff: histórico completo (caro), últimas N mensagens ou um resumo.
• Guardrail no handoff. Um handoff para um especialista com diferentes permissões de ferramentas deve ser autenticado — caso contrário, injeção de prompt pode forçar handoffs indesejados.
• Detecção de loop. Dois agentes passando a conversa de um para o outro é uma falha comum; detecte com uma verificação simples de anel (ring check) dos últimos K.
• Agente de fallback. Se o alvo de um handoff não existir, use um padrão seguro.

Exercícios

1. Execute code/main.py, faça a triagem para o agente de reembolso. Confirme se o agente ativo do segundo turno é o reembolso.
2. Adicione uma regra de detecção de loop: se os mesmos dois agentes tiverem feito handoff 3 vezes seguidas, force a saída. Projete o fallback.
3. Leia a documentação do OpenAI Agents SDK sobre filtros de handoff. Implemente uma versão de "resumo no handoff": o agente de saída compacta o contexto em um resumo em tópicos antes do agente de entrada assumir o controle.
4. Compare o handoff do Swarm com um seletor do GroupChatManager. Qual padrão torna a injeção de prompt pior e por quê?
5. Leia o Swarm cookbook (https://developers.openai.com/cookbook/examples/orchestrating_agents). Identifique uma decisão de design explícita que o Swarm toma e que o OpenAI Agents SDK alterou ou manteve.

Termos-Chave

Leitura Adicional

• OpenAI cookbook — Orchestrating Agents: Routines and Handoffs — a articulação de referência
• OpenAI Swarm repo — implementação original, mantida como referência conceitual
• OpenAI Agents SDK docs — sucessor de produção com sessões e tracing
• Anthropic handoff-in-Claude notes — como subagentes do Claude Code usam um padrão semelhante a handoff via Task