Phase 16 - Lesson 11

Handoffs y Routines — Orquestación sin Estado

Swarm de OpenAI (octubre de 2024) destiló la orquestación multiagente en dos primitivas: routines (instrucciones + herramientas como un prompt de sistema) y handoffs (una herramienta que devuelve otro Agent). Sin máquina de estados, sin DSL de ramificación: el LLM realiza el enrutamiento llamando a la herramienta de handoff correcta. OpenAI Agents SDK (marzo de 2025) es el sucesor de producción. Swarm en sí sigue siendo la referencia conceptual más limpa: todo su código fuente cabe en unas pocas cientos de líneas. El patrón se volvió viral porque la superficie de la API es básicamente "agent = prompt + tools; handoff = function returning agent." Limitación: stateless, por lo que la memoria es problema del llamador.

Tipo: Learn + Build Lenguajes: Python (stdlib) Prerrequisitos: Fase 16 · 04 (El Modelo de Primitivas Multiagente) Tiempo: ~60 minutos

El Problema

Cada framework multiagente quiere que aprendas su DSL: nodos y aristas de LangGraph, crews y tasks de CrewAI, GroupChat y managers de AutoGen. Las DSL son abstracciones reales, pero hacen que todo se sienta más pesado de lo que realmente es.

Swarm empuja en la dirección opuesta: usar la capacidad de llamada de herramientas (tool-calling) que el modelo ya tiene. Los handoffs se convierten en llamadas a herramientas. El orquestador es el agente que actualmente sostiene la conversación. La máquina de estados está implícita en los prompts de sistema de los agentes.

El Concepto

Dos primitivas

Routine. Un prompt de sistema que define el rol de un agente y sus herramientas disponibles. Piensa en esto como un conjunto delimitado de instrucciones: "eres un agente de triaje; si el usuario pregunta sobre reembolsos, transfiérelo al agente de reembolsos."

Handoff. Una herramienta que el agente puede llamar y que devuelve un nuevo objeto Agent. El runtime de Swarm detecta el valor de retorno de Agent y cambia el agente activo para el siguiente turno.

Esa es toda la abstracción.

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

El prompt de sistema del agente de triaje hace que elija el handoff correcto basándose en el mensaje del usuario. La llamada a la herramienta del LLM se encarga del enrutamiento.

Por qué es viral

• API pequeña. Solo dos conceptos que aprender.
• Usa lo que el modelo ya hace. La llamada a herramientas ya es de nivel de producción en todos los proveedores.
• Sin la carga de una máquina de estados. No describes el grafo; los prompts de los agentes describen a quién se transfiere el control.

El intercambio del stateless

Swarm es explícitamente stateless entre ejecuciones. El framework mantiene un historial de mensajes durante una ejecución, pero no persiste nada. La memoria, la continuidad y las tareas de larga duración son problema del llamador.

En producción (OpenAI Agents SDK, marzo de 2025) esta fue una de las principales cosas que cambió: el SDK añade gestión de sesiones integrada, guardas (guardrails) y rastreo (tracing) mientras mantiene la primitiva de handoff.

Cuándo encajan Swarm/handoffs

• Patrones de triaje. El agente de primera línea enruta al usuario a un especialista.
• Handoffs basados en habilidades. "Si la tarea necesita código, llama al programador; si necesita investigación, llama al investigador."
• Conversaciones cortas y delimitadas. Soporte al cliente, preguntas frecuentes a ticket, flujos de trabajo simples.

Cuándo tiene dificultades Swarm

• Sesiones largas con memoria compartida. Los handoffs restablecen el estado de la conversación al prompt del nuevo agente más el historial. No hay estado persistente entre agentes sin memoria gestionada por el llamador.
• Ejecución en paralelo. El enrutamiento (handoff) es de uno a la vez: el agente activo cambia. El paralelismo requiere que el llamador orqueste múltiples ejecuciones de Swarm.
• Auditoría y reproducción. Las ejecuciones stateless son difíciles de reproducir exactamente; la elección de handoff del LLM no es determinística.

OpenAI Agents SDK (marzo de 2025)

El sucesor de producción añade:

• Estado de sesión. Hilo persistente entre ejecuciones.
• Guardrails. Ganchos de validación de entrada/salida.
• Tracing. Se registra cada llamada a herramienta y handoff.
• Filtros de handoff. Controlan qué contexto se transfiere en los límites del handoff.

La primitiva de handoff sobrevive; la ergonomía de producción se añade a su alrededor.

Swarm vs GroupChat

Ambos utilizan enrutamiento impulsado por LLM, pero difieren en quién elige al siguiente:

• GroupChat: un selector (función o LLM) elige al siguiente orador desde fuera.
• Swarm: el agente actual elige a su sucesor llamando a una herramienta de handoff.

Swarm es "el agente decide qué sigue"; GroupChat es "el manager decide qué sigue." La decisión de Swarm reside en la llamada a la herramienta del agente activo; la de GroupChat reside en el GroupChatManager.

Constrúyelo

code/main.py implementa Swarm desde cero: una clase de datos Agent, un mecanismo de handoff (la herramienta devuelve Agent) y un bucle de ejecución que detecta cambios de agente.

Demo: un agente de triaje enruta a especialistas en reembolsos, ventas o soporte. Cada especialista tiene sus propias herramientas. El bucle de ejecución imprime cada handoff.

Ejecutar:

python3 code/main.py

Úsalo

outputs/skill-handoff-designer.md diseña una topología de handoff para una tarea dada: qué agentes existen, qué handoffs pueden llamar, qué contexto se transfiere.

Envíalo

Lista de verificación:

• Registro de handoff. Cada handoff escribe un evento de rastreo con from-agent, to-agent, captura de contexto.
• Reglas de transferencia de contexto. Decide qué se mueve en el handoff: historial completo (costoso), últimos N mensajes o un resumen.
• Guardrail en handoff. Un handoff a un especialista con permisos de herramientas diferentes debe ser autenticado; de lo contrario, la inyección de prompts puede forzar handoffs no deseados.
• Detección de bucles. Que dos agentes se pasen el control de un lado a otro es un fallo común; detéctalo con una comprobación simple de anillo (ring check) de los últimos K.
• Agente de respaldo. Si un destino de handoff no existe, recurre a un valor predeterminado seguro.

Ejercicios

1. Ejecuta code/main.py, realiza la triaje al agente de reembolsos. Confirma que el agente activo del segundo turno sea el de reembolsos.
2. Añade una regla de detección de bucles: si los mismos dos agentes han realizado un handoff 3 veces seguidas, fuerza la salida. Diseña el respaldo.
3. Lee la documentación de OpenAI Agents SDK sobre filtros de handoff. Implementa una versión de "resumen al transferir": el agente emisor comprime el contexto en un resumen con viñetas antes de que el agente receptor tome el control.
4. Compara el handoff de Swarm con un selector de GroupChatManager. ¿Qué patrón empeora la inyección de prompts y por qué?
5. Lee el Swarm cookbook (https://developers.openai.com/cookbook/examples/orchestrating_agents). Identifica una decisión de diseño explícita que toma Swarm y que OpenAI Agents SDK cambió o mantuvo.

Términos Clave

Lectura Adicional

• OpenAI cookbook — Orchestrating Agents: Routines and Handoffs — la articulación de referencia
• OpenAI Swarm repo — implementación original, mantida como referencia conceptual
• OpenAI Agents SDK docs — sucesor de producción con sesiones y tracing
• Anthropic handoff-in-Claude notes — cómo los subagentes de Claude Code usan un patrón tipo handoff a través de Task