Saltearse al contenido
Nappai Documentation

OpenAPI Agent

⚠️ ADVERTENCIA DE DEPRECACIÓN

Este componente está deprecado y será eliminado en una versión futura de Nappai. Por favor, migra a los componentes alternativos recomendados.

El Agente OpenAPI es una herramienta inteligente diseñada para automatizar la interacción con APIs externas. Imagínalo como un asistente que lee un “manual de instrucciones” técnico de una API y utiliza un modelo de lenguaje para decidir cómo realizar las acciones necesarias de forma automática.

Este componente permite a Nappai conectar con sistemas externos sin necesidad de programar manualmente cada paso. El agente interpreta tus instrucciones en lenguaje natural, consulta la estructura de la API y ejecuta las llamadas necesarias para obtener o enviar datos, devolviendo los resultados procesados para que puedas usarlos en el resto de tu flujo de trabajo.

¿Cómo funciona?

Este componente actúa como un intermediario inteligente entre tu flujo de trabajo y una API externa:

  1. Carga del Manual: Subes un archivo que contiene la documentación técnica de la API (en formato JSON o YAML). Este archivo actúa como el “mapa” que le dice al agente qué acciones puede realizar, qué datos necesita y cómo debe pedirlos.
  2. Cerebro del Agente: Conectas un Modelo de Lenguaje (LLM) que funciona como el “cerebro” del agente. Este modelo se encarga de entender tus instrucciones, tomar decisiones lógicas y generar las solicitudes correctas.
  3. Ejecución Automática: Cuando activas el agente, utiliza su modelo de lenguaje para analizar la tarea solicitada, consulta el archivo cargado para saber cómo interactuar con la API, y realiza las llamadas necesarias (GET, POST, etc.) de forma automática.
  4. Resultados: Devuelve las respuestas de la API procesadas y estructuradas, listas para ser usadas en nodos siguientes (como visualizaciones, almacenamiento o acciones adicionales).

El componente incluye protecciones de seguridad por defecto para evitar acciones riesgosas, y utiliza un sistema de registros asíncrono para mantener el flujo fluido y trazable.

Entradas

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente:

  • Model: Es el “cerebro” del agente. Debes conectar aquí un modelo de lenguaje que le permitirá entender las instrucciones, decidir qué acciones tomar y generar las llamadas a la API correctamente.
  • File Path: La ruta del archivo que contiene la especificación técnica de la API que deseas automatizar. El componente solo acepta archivos en formato .json, .yaml o .yml.
  • Allow Dangerous Requests: Interruptor de seguridad. Por defecto está desactivado (False) para proteger tu flujo de acciones potencialmente riesgosas. Si lo activas, permites que el agente realice solicitudes HTTP más amplias o restrictivas. Úsalo solo con APIs de confianza.
  • Handle Parse Errors: Control interno para gestionar errores de análisis en los datos de entrada.
  • Input: Entrada base heredada para la integración del agente en la cadena de flujo.
  • Max Iterations: Parámetro que limita el número máximo de decisiones o ciclos que el agente puede realizar. Ajustarlo es importante para equilibrar el rendimiento y evitar detenciones prematuras.
  • Verbose: Opción para habilitar o deshabilitar la salida detallada de registros durante la ejecución.

Salidas

  • Agent: Devuelve un agente ejecutable (tipo AgentExecutor) listo para ser activado dentro del grafo de flujo. Esta salida procesa las instrucciones y devuelve las respuestas generadas tras interactuar con la API.
  • Response: Mensaje estructurado con los resultados finales procesados por el agente, que puede ser mapeado en nodos subsiguientes para su visualización o uso.

Ejemplo de Respuesta JSON

Cuando el agente interactúa exitosamente con una API, el resultado suele tener una estructura como la siguiente: json { “status”: “success”, “data”: { “user_id”: 89452, “name”: “Cliente Ejemplo”, “subscription”: “Premium”, “last_activity”: “2023-11-15T14:30:00Z” }, “metadata”: { “source”: “External_API”, “endpoint”: “/api/v1/users/{id}”, “timestamp”: “2023-11-20T09:15:22Z” } }

Conectividad

Este componente es un nodo de tipo Agente y su flujo lógico suele encajar en flujos de automatización de datos y orquestación:

  • Conexión a Salida: Es común conectar la salida Agent a nodos de visualización (como gráficos o tablas) o nodos de almacenamiento para ver los datos obtenidos de la API.
  • Encadenamiento de Agentes: Puede conectarse a la entrada de otros agentes para crear flujos complejos donde la salida de una API sirve como entrada para otra acción automatizada.
  • Herramientas y Controladores: En el ecosistema Nappai, este agente se integra con el sistema de eventos y control de flujo, permitiendo que su ejecución sea monitoreada y trazada en el dashboard.

Ejemplo de Uso

Escenario: Automatización de Consulta de Clientes

  1. Objetivo: Obtener automáticamente los detalles de un cliente desde un sistema CRM externo cuando se recibe una nueva orden.
  2. Configuración:
    • Conectas tu modelo de LLM preferido al campo Model.
    • Subes el archivo de especificación OpenAPI del CRM al campo File Path.
    • Asegúrate de que Allow Dangerous Requests esté desactivado (ya que solo necesitas leer datos).
  3. Ejecución: Al activar el flujo, el agente interpreta la solicitud, consulta el archivo OpenAPI para identificar el endpoint correcto de consulta de cliente, realiza la llamada HTTP y devuelve los datos del cliente estructurados.
  4. Resultado: El flujo continúa con los datos del cliente, permitiendo por ejemplo enviar un correo personalizado o actualizar un registro interno.

Notas Importantes

🔒 Dangerous Request Control 🟴 El “Allow Dangerous Requests” es una palanca de seguridad crítica. Si se activa, el agente puede enviar cualquier método HTTP, incluyendo acciones potencialmente destructivas. Utiliza esta opción únicamente con especificaciones de confianza y en entornos controlados.

🔒 Use Secure Endpoints 🟡 Cuando el agente llama a APIs externas, asegúrate de que esos endpoints requieran una autenticación adecuada. Evita exponer credenciales sensibles en la especificación o en el entorno del flujo.

⚠️ Only JSON or YAML Spec Files 🟡 El componente solo carga especificaciones OpenAPI en formato JSON o YAML. Las especificaciones en otros formatos causarán un error durante la inicialización.

📋 Compatible Language Model Required 🟢 Debes proporcionar un modelo de lenguaje (LLM) que el componente pueda utilizar para generar las llamadas a la API. El modelo debe ser compatible con las plantillas de prompts utilizadas por LangChain.

💡 Validate the OpenAPI Spec First 🟢 Antes de cargar la especificación, ejecuta tu archivo OpenAPI a través de un validador. Un archivo válido asegura que el agente pueda construir correctamente las llamadas a la API.

💡 Keep Spec Files Manageable 🟢 Las especificaciones OpenAPI grandes pueden ralentizar el inicio del agente. Si es posible, utiliza archivos enfocados o recorta rutas no utilizadas para mejorar el rendimiento.

⚙️ Check the Max Iterations Setting 🟡 El parámetro “max_iterations” controla cuántos ciclos de decisión puede realizar el agente. Un valor muy alto puede aumentar el tiempo de ejecución, mientras que un valor bajo podría detener al agente prematuramente.

Consejos y Mejores Prácticas

  • Valida siempre tus archivos: Antes de subir un archivo OpenAPI, asegúrate de que sea válido y siga el estándar. Errores en la estructura del archivo impedirán que el agente funcione.
  • Mantén tus especificaciones limpias: Usa archivos OpenAPI lo más concisos posible. Elimina rutas o operaciones que no necesites para acelerar el agente.
  • Revisa la seguridad: Activa “Allow Dangerous Requests” solo si es estrictamente necesario y confías en la fuente de la API.
  • Monitorea las iteraciones: Ajusta “Max Iterations” según la complejidad de tu flujo. Un valor demasiado bajo puede cortar respuestas complejas.
  • Usa modelos compatibles: Asegúrate de que el modelo de lenguaje que conectas sea compatible con las capacidades requeridas para la generación de llamadas API.

Consideraciones de Seguridad

  • Protección de Credenciales: Nunca incluyas claves de API, tokens secretos o credenciales directamente en los archivos de especificación OpenAPI. Utiliza mecanismos de autenticación seguros en el entorno de ejecución.
  • Control de Daños: El valor predeterminado de “Allow Dangerous Requests” es False, lo que restringe las acciones riesgosas. Mantén esta configuración por defecto siempre que sea posible.
  • Validación de YAML: El componente utiliza loaders seguros para archivos YAML (yaml.FullLoader), protegiéndote contra vulnerabilidades de carga arbitraria. No modifiques esta configuración a menos que tengas un caso de uso explícito y seguro.