Handoffs (delegación entre agentes)
Un handoff permite que un agente transfiera la conversación u objetivo a otro agente con instrucciones o herramientas distintas. Es útil cuando:
- Un agente "enrutador" clasifica la intención y deriva a un especialista.
- Separas políticas (por ejemplo cumplimiento) de ejecución (por ejemplo consultas técnicas).
En el SDK, los handoffs se configuran en la definición del agente (por ejemplo listando otros agentes o reglas de delegación según la versión que uses). El runner mantiene el contexto y encadena la ejecución hasta resolver la tarea.
Herramientas (tools)
Las tools son funciones o endpoints que el modelo puede invocar cuando el razonamiento lo requiere. Patrones habituales:
- Funciones Python registradas como tools (el SDK serializa esquema y resultados).
- Llamadas HTTP encapsuladas para sistemas legados.
Buenas prácticas:
- Nombres y descripciones explícitas para reducir alucinaciones de invocación.
- Validar entradas y limitar el alcance (principio de menor privilegio).
- Devolver textos o estructuras pequeñas al modelo para no saturar el contexto.
Guardrails
Los guardrails son comprobaciones antes o después de pasos críticos (por ejemplo antes de ejecutar una tool o antes de mostrar la respuesta al usuario). Sirven para:
- Bloquear contenido prohibido o fuera de política.
- Validar que la salida cumple formato o schema esperado.
Integrarlos en el flujo del agente reduce riesgos en producción frente a confiar solo en el prompt.
Tracing y depuración
El ecosistema del Agents SDK suele ofrecer tracing (trazas de ejecución) para inspeccionar:
- Mensajes y decisiones del modelo.
- Llamadas a herramientas y resultados.
- Transiciones entre agentes en handoffs.
Usa las trazas para ajustar instrucciones, acotar tools y reproducir errores.
Resumen
| Concepto | Rol | |----------|-----| | Agent | Identidad, instrucciones, modelo y tools del asistente. | | Runner | Ejecuta el bucle hasta un resultado final. | | Handoff | Delega en otro agente especializado. | | Tools | Acciones concretas fuera del modelo. | | Guardrails | Validación y cumplimiento en puntos clave. | | Tracing | Visibilidad del comportamiento en desarrollo y operación. |
Con estos bloques puedes diseñar agentes modulares y más fáciles de mantener que un único prompt monolítico.
El diagrama siguiente resume cómo se componen los bloques del SDK alrededor de un Runner: el Runner mantiene el contexto, aplica los guardrails en la entrada y la salida, ejecuta las tools solicitadas y, cuando procede, transfiere la conversación a un agente especializado mediante un handoff.
Los componentes Agent (identidad, instrucciones, modelo y tools), Runner (bucle hasta resultado final), handoffs (delegación en otro agente), guardrails (validación en los límites del flujo) y tracing (visibilidad) encajan como piezas independientes y reutilizables.
Alan Sastre
Ingeniero de Software y formador, CEO en CertiDevs
Ingeniero de software especializado en Full Stack y en Inteligencia Artificial. Como CEO de CertiDevs, OpenAI SDK es una de sus áreas de expertise. Con más de 15 años programando, 6K seguidores en LinkedIn y experiencia como formador, Alan se dedica a crear contenido educativo de calidad para desarrolladores de todos los niveles.
Más tutoriales de OpenAI SDK
Explora más contenido relacionado con OpenAI SDK y continúa aprendiendo con nuestros tutoriales gratuitos.
Aprendizajes de esta lección
Entender los handoffs como mecanismo de delegación entre agentes especializados. Registrar funciones Python como herramientas invocables por el modelo con nombres y descripciones explícitas. Aplicar guardrails antes y después de pasos críticos para validar contenido y formato. Usar tracing para inspeccionar mensajes, llamadas a herramientas y transiciones entre agentes. Diseñar agentes modulares combinando Agent, Runner, handoffs, tools y guardrails.