Guía práctica de OpenAI para construir agentes

• A medida que mejoran las capacidades de razonamiento, multimodalidad y uso de herramientas de los LLM, ha surgido una nueva categoría de sistemas: los agentes, que pueden ejecutar flujos de trabajo de forma autónoma en nombre del usuario
• Los agentes se componen de tres elementos centrales: modelo (LLM), herramientas (API/funciones externas) e instrucciones (guías), y pueden orquestarse como un solo agente o como un sistema multiagente
• La adopción de agentes es adecuada para flujos de trabajo que requieren toma de decisiones compleja, sistemas de reglas difíciles de mantener y procesamiento de datos no estructurados
• Los guardrails son mecanismos de defensa en múltiples capas que protegen la privacidad de los datos, la seguridad del contenido y la consistencia de marca, y son un elemento esencial para desplegar agentes
• Un enfoque iterativo que empieza con un solo agente y se expande gradualmente tras validarlo con usuarios reales es clave para un despliegue exitoso

---

Definición de agente

• Un agente es un sistema que realiza tareas de forma autónoma en nombre del usuario, procesando flujos de trabajo como resolver problemas de atención al cliente, reservar restaurantes, hacer commits de cambios de código o generar reportes
• Las aplicaciones que integran LLM pero no controlan la ejecución del flujo de trabajo (chatbots simples, LLM de un solo turno, clasificadores de sentimiento, etc.) no son agentes
• Características clave de un agente:
  • Usa un LLM para gestionar la ejecución del flujo de trabajo y tomar decisiones, reconoce cuándo el flujo ha terminado y, si hace falta, ajusta proactivamente su comportamiento
  • Si falla, detiene la ejecución y devuelve el control al usuario
  • Tiene acceso a diversas herramientas para interactuar con sistemas externos, y selecciona dinámicamente la herramienta adecuada según el estado actual del flujo de trabajo, siempre dentro de guardrails claros

Cuándo conviene construir agentes

• A diferencia de la automatización tradicional, los agentes son adecuados para flujos de trabajo donde los enfoques deterministas y basados en reglas llegan a su límite
• Ejemplo de análisis de fraude en pagos: mientras que un motor de reglas tradicional sigue un enfoque de checklist y marca transacciones según criterios predefinidos, un agente con LLM actúa como un investigador experto que evalúa el contexto, considera patrones sutiles e identifica actividad sospechosa incluso sin una violación clara de reglas
• Tres tipos de casos donde los agentes aportan valor:
  • Toma de decisiones compleja: flujos de trabajo que requieren juicios sutiles, excepciones y decisiones sensibles al contexto (por ejemplo, aprobar reembolsos en atención al cliente)
  • Reglas difíciles de mantener: sistemas con conjuntos de reglas extensos y complejos, donde actualizar cuesta mucho o es propenso a errores (por ejemplo, revisiones de seguridad de proveedores)
  • Escenarios con alta dependencia de datos no estructurados: interpretación de lenguaje natural, extracción de significado de documentos e interacción conversacional con usuarios (por ejemplo, procesamiento de reclamos de seguro de vivienda)
• Si estos criterios no se cumplen claramente, una solución determinista puede ser suficiente

Fundamentos del diseño de agentes

• Tres componentes centrales

  • Modelo (Model): el LLM que impulsa el razonamiento y la toma de decisiones del agente
  • Herramientas (Tools): funciones externas o API que el agente usa para actuar
  • Instrucciones (Instructions): guías explícitas y guardrails que definen cómo debe comportarse el agente

• Selección del modelo

  • No todas las tareas requieren el modelo más potente: búsquedas simples o clasificación de intención pueden resolverse con modelos pequeños y rápidos, mientras que tareas difíciles como decidir una aprobación de reembolso se benefician de modelos más potentes
  • En la etapa de prototipo, resulta efectivo establecer una línea base de desempeño con el modelo más potente y luego reemplazarlo por modelos más pequeños para verificar si los resultados siguen siendo aceptables
  • Principios para elegir modelo:
    • Configurar evaluaciones (evals) para establecer una línea base de desempeño
    • Enfocarse primero en alcanzar el objetivo de precisión con el mejor modelo
    • Reemplazar por modelos más pequeños donde sea posible para optimizar costo y latencia

• Definición de herramientas

  • Las herramientas amplían las capacidades del agente usando las API de la aplicación o sistema subyacente
  • En sistemas legacy sin API, es posible interactuar directamente con interfaces web y de aplicaciones usando un modelo de computer-use
  • Cada herramienta debe tener una definición estandarizada y permitir una relación flexible de muchos a muchos entre herramientas y agentes
  • Herramientas reutilizables, bien documentadas y probadas a fondo mejoran el descubrimiento, simplifican el versionado y evitan definiciones duplicadas
  • Tres tipos de herramientas que necesita un agente:
    • Datos (Data): recuperan contexto e información necesarios para ejecutar el flujo de trabajo (por ejemplo, consultar una base de datos de transacciones, sistemas CRM, leer PDF o hacer búsquedas web)
    • Acción (Action): interactúan con sistemas para agregar información a una base de datos, actualizar registros o enviar mensajes (por ejemplo, enviar email/SMS, actualizar registros en CRM o escalar un ticket de soporte a una persona)
    • Orquestación (Orchestration): el propio agente actúa como herramienta de otros agentes (por ejemplo, agente de reembolsos, de investigación o de redacción)

• Estructura de instrucciones

  • Las instrucciones de alta calidad son esenciales en cualquier app basada en LLM, pero en agentes son especialmente importantes
  • Instrucciones claras reducen la ambigüedad y mejoran la toma de decisiones del agente, lo que lleva a una ejecución más fluida del flujo de trabajo y a menos errores
  • Buenas prácticas para instrucciones de agentes:
    • Aprovechar documentación existente: usar procedimientos operativos actuales, guiones de soporte y documentos de política para crear rutinas amigables para LLM (en atención al cliente, las rutinas se mapean de forma aproximada a documentos individuales de la base de conocimiento)
    • Prompts de descomposición de tareas: ofrecer pasos más pequeños y claros a partir de recursos densos para minimizar la ambigüedad
    • Definición clara de acciones: especificar que cada paso de la rutina corresponda a una acción o salida concreta (por ejemplo, solicitar número de orden, recuperar detalles de la cuenta vía API)
    • Capturar edge cases: anticipar variaciones comunes, como usuarios que entregan información incompleta o hacen preguntas inesperadas, e incluir pasos condicionales o bifurcaciones para manejarlas
  • También es posible usar modelos avanzados como o1 u o3‑mini para generar instrucciones automáticamente a partir de documentación existente

Orquestación

• Sistemas de agente único

  • Un solo agente puede resolver muchas tareas agregando herramientas gradualmente, lo que facilita la gestión de la complejidad y simplifica la evaluación y el mantenimiento
  • Todo enfoque de orquestación necesita el concepto de 'run', normalmente implementado como un loop donde el agente opera hasta alcanzar una condición de término
  • Condiciones de término comunes: llamada a herramienta, salida estructurada específica, error o alcanzar el número máximo de turnos
  • En el Agents SDK, el agente se inicia con el método Agents.run() y el loop termina ante una llamada final a herramienta de salida o una respuesta del modelo sin llamada a herramienta
  • Estrategia de plantilla de prompt: en vez de múltiples prompts individuales, se usa un solo prompt base flexible que recibe variables de política para adaptarse a distintos contextos, simplificando mucho el mantenimiento y la evaluación

• Cuándo pasar a un sistema multiagente

  • La recomendación general es maximizar primero la capacidad de un solo agente
  • Aunque más agentes ofrecen una separación conceptual intuitiva, también añaden complejidad y sobrecarga, así que muchas veces basta con un solo agente con herramientas
  • Guías prácticas para dividir agentes:
    • Lógica compleja: si el prompt contiene muchas condicionales (ramas if-then-else) y la plantilla de prompt se vuelve difícil de escalar, conviene separar cada segmento lógico en un agente distinto
    • Sobrecarga de herramientas: el problema no es la cantidad de herramientas, sino su similitud o superposición; hay implementaciones que gestionan con éxito más de 15 herramientas claramente diferenciadas, mientras que otras tienen dificultades incluso con menos de 10 herramientas redundantes

• Patrón manager (usar agentes como herramientas)

  • Un LLM central, el "manager", orquesta una red de agentes especializados mediante llamadas a herramientas
  • El manager delega tareas al agente adecuado en el momento oportuno sin perder contexto ni control, y sintetiza los resultados en una interacción unificada
  • Es adecuado para flujos de trabajo donde un solo agente debe controlar la ejecución y tener acceso al usuario
  • Ejemplo: un agente de traducción llama como herramientas a agentes de español, francés e italiano

• Patrón descentralizado (handoff entre agentes)

  • Un agente transfiere la ejecución del flujo de trabajo a otro agente mediante una transición unidireccional de 'handoff'
  • En el Agents SDK, el handoff es un tipo de herramienta o función; al llamar a la función de handoff, se pasa el estado más reciente de la conversación y el nuevo agente comienza a ejecutarse de inmediato
  • Es ideal cuando no hace falta que un solo agente mantenga control central o haga la síntesis, y cada agente puede asumir la ejecución e interactuar directamente con el usuario
  • Ejemplo: un agente de triage evalúa la consulta del usuario y la enruta a soporte técnico, ventas o gestión de pedidos

• Grafos declarativos vs no declarativos

  • Algunos frameworks exigen definir por adelantado, de forma declarativa (declarative), todas las bifurcaciones, loops y condiciones como un grafo de nodos (agentes) y aristas (handoffs). Eso aporta claridad visual, pero se vuelve engorroso cuando el flujo de trabajo es dinámico y complejo, y además requiere aprender un lenguaje específico del dominio
  • El Agents SDK adopta un enfoque code-first, que permite expresar directamente la lógica del flujo con estructuras de programación familiares, habilitando una orquestación de agentes más dinámica y adaptable sin necesidad de predefinir todo el grafo

Guardrails

• Rol de los guardrails

  • Ayudan a gestionar riesgos de privacidad de datos (por ejemplo, prevenir la filtración del prompt del sistema) y riesgos reputacionales (por ejemplo, forzar comportamientos del modelo acordes con la marca)
  • Un solo guardrail no suele ser suficiente; para construir agentes más resilientes, hay que usar varios guardrails especializados en conjunto
  • Los guardrails son importantes, pero deben combinarse con protocolos sólidos de autenticación y autorización, controles de acceso estrictos y medidas estándar de seguridad de software

• Tipos de guardrails

  • Clasificador de relevancia (Relevance classifier): verifica si la respuesta del agente está dentro del alcance previsto y marca consultas fuera de tema (por ejemplo, “¿Cuál es la altura del Empire State Building?”)
  • Clasificador de seguridad (Safety classifier): detecta entradas inseguras, como jailbreaks o prompt injection destinados a explotar vulnerabilidades del sistema
  • Filtro de PII: evita la exposición innecesaria de información de identificación personal (PII) en la salida del modelo
  • Moderación (Moderation): marca entradas dañinas o inapropiadas, como discurso de odio, acoso o violencia
  • Salvaguardas de herramientas (Tool safeguards): asignan a cada herramienta una clasificación de riesgo bajo/medio/alto según si es de solo lectura o escritura, su reversibilidad, los permisos de cuenta requeridos y el impacto financiero; luego activan acciones automáticas como pausar la revisión de guardrails o escalar a una persona antes de ejecutar funciones de alto riesgo
  • Protecciones basadas en reglas (Rules-based protections): medidas deterministas simples, como listas de bloqueo, límites de longitud de entrada y filtros por regex, para prevenir amenazas conocidas como términos prohibidos o inyección SQL
  • Validación de salida (Output validation): mediante prompt engineering y revisión de contenido, confirma que las respuestas estén alineadas con los valores de la marca

• Enfoque para construir guardrails

  • Empezar por guardrails para riesgos ya identificados y agregar más capas a medida que se descubren nuevas vulnerabilidades
  • Heurísticas efectivas:
    • Enfocarse en privacidad de datos y seguridad del contenido
    • Agregar nuevos guardrails con base en edge cases y fallas reales
    • Ajustar los guardrails conforme evoluciona el agente, optimizando tanto seguridad como experiencia de usuario
  • En el Agents SDK, los guardrails se tratan como un concepto de primera clase (first-class concept) y, por defecto, usan optimistic execution: el agente base genera proactivamente la salida mientras los guardrails se ejecutan en paralelo, y si hay violaciones de restricciones se dispara una excepción

• Plan para intervención humana

  • La intervención humana es una salvaguarda clave que puede mejorar el desempeño real del agente sin dañar la experiencia del usuario
  • Es especialmente importante en las primeras etapas del despliegue, ya que ayuda a identificar fallas, descubrir edge cases y establecer ciclos de evaluación robustos
  • Dos disparadores principales para requerir intervención humana:
    • Superar umbrales de falla: establecer límites para reintentos o acciones del agente, y si se superan (por ejemplo, no logra entender la intención del cliente tras varios intentos), escalar a una persona
    • Acciones de alto riesgo: acciones sensibles, irreversibles o de alto impacto (por ejemplo, cancelar un pedido de un usuario, aprobar grandes reembolsos o procesar pagos) requieren supervisión humana hasta que aumente la confianza en el agente

Conclusión

• Los agentes inauguran una nueva era de automatización de flujos de trabajo: pueden razonar en la ambigüedad, actuar mediante herramientas y resolver tareas de varios pasos con alta autonomía
• A diferencia de las aplicaciones LLM simples, los agentes ejecutan flujos de trabajo de extremo a extremo, por lo que son adecuados para decisiones complejas, datos no estructurados y sistemas frágiles basados en reglas
• Para construir agentes confiables: combinar un modelo competente con herramientas bien definidas e instrucciones claras y estructuradas, usar patrones de orquestación acordes con la complejidad y empezar con un solo agente, escalando a multiagente solo cuando sea necesario
• Los guardrails son importantes en todas las etapas, desde el filtrado de entradas hasta el uso de herramientas y la intervención humana, y garantizan que los agentes operen de forma segura y predecible en producción
• Un despliegue exitoso no es de todo o nada, sino un enfoque iterativo de empezar en pequeño, validar con usuarios reales y expandir capacidades con el tiempo

• También disponible en PDF