Phase 14 - Lesson 16

OpenAI Agents SDK: Handoffs, Guardrails, Tracing

OpenAI Agents SDK es el framework multiagente ligero construido sobre la Responses API. Cinco primitivas: Agent, Handoff, Guardrail, Session, Tracing. Los handoffs son herramientas llamadas transfer_to_<agent>. Los guardrails se activan en la entrada o en la salida. El tracing está activado por defecto.

Tipo: Aprender + Construir Idiomas: Python (stdlib) Prerrequisitos: Fase 14 · 01 (Loop de Agente), Fase 14 · 06 (Uso de Herramientas) Tiempo: ~75 minutos

Objetivos de Aprendizaje

• Nombrar las cinco primitivas del OpenAI Agents SDK.
• Explicar los handoffs: por qué se modelan como herramientas, qué formato de nombre ve el modelo y cómo se transfiere el contexto.
• Distinguir guardrails de entrada, guardrails de salida y guardrails de herramienta; explicar run_in_parallel vs modo de bloqueo.
• Implementar un runtime de la stdlib con handoffs + guardrails + rastreo en estilo span.

El Problema

Los agentes que no pueden delegar de manera limpia terminan metiendo todo en un solo prompt. Los agentes sin guardrails envían información de identificación personal (PII), salidas que violan las políticas o entran en bucles infinitos. El SDK de OpenAI codifica las tres primitivas que hacen que el trabajo multiagente sea manejable.

El Concepto

Cinco primitivas

1. Agent. LLM + instrucciones + herramientas + handoffs.
2. Handoff. Delegación a otro agente. Representado ante el modelo como una herramienta llamada transfer_to_<agent_name>.
3. Guardrail. Validación en la entrada (solo en el primer agente), en la salida (solo en el último agente) o en la invocación de la herramienta (por herramienta de función).
4. Session. Historial automático de conversación entre turnos.
5. Tracing. Spans integrados para generaciones de LLM, llamadas a herramientas, handoffs y guardrails.

Handoffs como herramientas

El modelo ve transfer_to_billing_agent en su lista de herramientas. Llamarla le indica al runtime que:

1. Copie el contexto de la conversación (o lo reduzca mediante la versión beta de nest_handoff_history).
2. Inicialice al agente de destino con sus instrucciones.
3. Continúe la ejecución con el agente de destino.

Este es el patrón de supervisor (Lección 13 / Lección 28) convertido en producto.

Guardrails

Tres variantes:

• Input guardrails. Se ejecutan en la entrada del primer agente. Rechazan solicitudes inseguras o fuera de alcance antes de cualquier llamada al LLM.
• Output guardrails. Se ejecutan en la salida del último agente. Capturan filtraciones de PII, violaciones de políticas y respuestas malformadas.
• Tool guardrails. Se ejecutan por herramienta de función. Validan argumentos, verifican permisos y auditan la ejecución.

Modos:

• Parallel (predeterminado). El LLM del guardrail se ejecuta junto al LLM principal. Menor latencia de cola. Si se activa, el trabajo del LLM principal se descarta (desperdicio de tokens).
• Blocking (run_in_parallel=False). El LLM del guardrail se ejecuta primero. Si se activa, no se desperdician tokens en la llamada principal.

Los tripwires lanzan InputGuardrailTripwireTriggered / OutputGuardrailTripwireTriggered.

Tracing

Activado por defecto. Cada generación de LLM, llamada a herramienta, handoff y guardrail emite un span. OPENAI_AGENTS_DISABLE_TRACING=1 desactiva esta opción. add_trace_processor(processor) distribuye los spans a tu propio backend junto al de OpenAI.

Sessions

La Session almacena el historial de conversación en un backend (SQLite, Redis, personalizado). Runner.run(agent, input, session=session) lo carga y lo añade automáticamente.

Dónde falla este patrón

• Handoff drift. El Agente A delega en el Agente B, el cual devuelve la delegación al Agente A. Añade un contador de saltos.
• Guardrail bypass. Los guardrails de herramienta solo se activan en herramientas de función; las herramientas integradas (lector de archivos, búsqueda web) necesitan una política independiente.
• Over-tracing. Contenido sensible en los spans. Combínalo con las reglas de captura de contenido de OTel GenAI (Lección 23): almacena de forma externa y referencia por ID.

Constrúyalo

El archivo code/main.py implementa la estructura del SDK en la stdlib:

• Agent, FunctionTool, Handoff (como una herramienta de función con semántica de transferencia).
• Runner con guardrails de entrada/saída/herramienta, despacho de handoffs y contador de saltos.
• Un emisor de spans simple para mostrar la estructura del trace.
• A triage agent that hands off to billing or support based on the user's query; guardrail trips on one input. (Wait, let me translate this line!) -> - Un agente de triaje que delega en facturación o soporte según la consulta del usuario; el guardrail se activa con una de las entradas.

Ejecútelo:

python3 code/main.py

El trace muestra dos handoffs exitosos, una activación de guardrail de entrada y un árbol de spans que refleja lo que emite el SDK real.

Úselo

• OpenAI Agents SDK para productos centrados en OpenAI.
• Claude Agent SDK (Lección 17) para productos centrados en Claude.
• LangGraph (Lección 13) cuando deseas un estado explícito y una reanudación duradera.
• Custom cuando necesitas control exacto (voz, multiproveedor, despliegues federados).

Envíelo a Producción

El archivo outputs/skill-agents-sdk-scaffold.md estructura una aplicación del Agents SDK con un agente de triaje, handoffs, guardrails de entrada/salida/herramienta, almacenamiento de sesión y un procesador de trace.

Ejercicios

1. Añada un contador de saltos para el handoff: rechace la transferencia después de N saltos. Rastreé el comportamiento.
2. Implemente nest_handoff_history como una opción: consolide los mensajes anteriores en un solo resumen antes de la transferencia.
3. Escriba un guardrail de salida bloqueante. Compare la latencia en los prompts que lo activarían frente a los que pasan.
4. Conecte add_trace_processor a un registrador JSON. ¿Qué estructura emite por span?
5. Lea la documentación del SDK. Migre su prototipo de la stdlib a openai-agents-python. ¿Qué modeló de forma incorrecta?

Términos Clave

Lecturas Adicionales

• OpenAI Agents SDK docs — primitivas, handoffs, guardrails, tracing
• Claude Agent SDK overview — contraparte al estilo Claude
• Anthropic, Building Effective Agents — cuándo recurrir en absoluto a los handoffs
• OpenTelemetry GenAI semantic conventions — el estándar al que se mapean los spans del Agents SDK