Conceptos del Agents SDK: handoffs, herramientas y guardrails

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.