🔌 HTTP Request y Code Tool - Cortex

Son las dos formas principales de integrar lógica propia en tu flujo. HTTP Request llama a una API externa, mientras que Code Tool ejecuta un script personalizado en el entorno de Atom. Ambas herramientas pueden usar campos de la conversación como entrada y guardar sus respuestas como nuevos campos.

⚖️ ¿Cuál usar? HTTP Request vs. Code Tool

Esta es la primera decisión arquitectónica que debes tomar al integrar sistemas. Elegir la herramienta equivocada puede complicar el mantenimiento o sumar latencia innecesaria.

Criterio	🌐 HTTP Request	💻 Code Tool
Punto de conexión	Ya existe un endpoint que hace lo que se necesita.	La lógica es propia del flujo y no aplica a otros sistemas.
Mantenimiento	La lógica vive en un sistema mantenido por otro equipo.	La lógica cambia seguido con las reglas del negocio.
Manipulación de datos	No se requiere transformación.	Hay que transformar o filtrar datos antes/después de una llamada.
Persistencia	Se necesita persistir datos (crear registros, actualizar estados).	Lógica condicional compleja o cálculos sin persistencia externa.
Ejemplos típicos	Consultar el CRM, crear un ticket, ver stock en un ERP.	Calcular una cuota, reglas de elegibilidad, enmascarar datos.

4 preguntas clave para decidir rápido:

¿Ya existe un endpoint que hace esto? Si sí 👉 HTTP Request.
¿La lógica es reutilizable por otros sistemas? Si sí 👉 HTTP Request (a un microservicio propio).
¿La lógica cambia seguido con el negocio? Si sí 👉 Code Tool.
¿Hay que transformar o combinar datos? Si sí 👉 Code Tool.

⚠️ Anti-patrones frecuentes:

Escribir un endpoint dentro de un Code Tool solo porque "es más rápido" duplica lógica que ya existe en tu ecosistema y rompe el monitoreo de origen.
Crear un microservicio entero solo para un cálculo matemático simple suma infraestructura y latencia de red sin motivo.
Regla práctica: Si la lógica entra en 30 líneas de código y no necesita guardar datos en una base externa, usa un Code Tool.

🌐 HTTP Request

📍 ¿Dónde se configura?

Canvas → Nodo Cortex → Panel derecho → Tab Herramientas → HTTP Request.

🗂️ Qué se configura

Campo	Descripción
Método	GET, POST, PUT, PATCH, DELETE.
URL	Admite parámetros de ruta y de query dinámicos.
Headers	Claves y valores (ambos admiten variables).
Query params	Claves y valores (ambos admiten variables).
Body	Estructura JSON (admite variables).

🔗 Usar campos como variables

En cualquiera de los campos anteriores, al escribir /: se despliega la lista de campos de guardado del nodo (el menú es filtrable). Las variables se pueden usar solas o concatenadas directamente con texto fijo:

[https://api.crm.com/customers//](https://api.crm.com/customers//)[ID Cliente]/vehicles?year=/[Año Preferido]

Los valores se codifican automáticamente para URL (por ejemplo, los espacios pasan a %20).
También puedes inyectar variables de entorno usando {{VARIABLE}} (ideal para tokens de autorización y URLs base).

💡 Seguridad en Runtime: Si una variable referenciada no tiene valor al momento de ejecutar la petición, esta no se dispara. El nodo se dará cuenta y le pedirá el dato faltante al cliente antes de continuar.

👁️ Vista previa

Antes de probar o romper algo, la "Vista previa" te muestra cómo quedará la URL armada y el body final con valores de ejemplo. Sirve para verificar la construcción sin ejecutar nada en tu servidor.

💾 Guardar la respuesta

En la configuración avanzada encontrarás la sección ¿Cómo guardar las respuestas?.

Haz clic en Probar API desde aquí para ejecutar la petición con valores de ejemplo y ver la respuesta completa en formato JSON.
Haz clic sobre cualquier valor del JSON para abrir el formulario de mapeo.
Por cada valor que necesites guardar, configurarás lo siguiente:

Campo	Descripción
Nombre de variable	Identificador interno del mapeo (para reconocerlo visualmente).
Valor a guardar	La ruta exacta dentro del JSON de respuesta (ej. `data.user.firstName`). Obligatorio.
Seleccionar campo	El campo de guardado de Cortex donde se persistirá el dato (puedes crear uno nuevo ahí mismo).

📝 Ejemplo de flujo

El nodo capturó el correo del cliente y dispara un GET a:

[https://crm.empresa.com/api/contacts?email=/](https://crm.empresa.com/api/contacts?email=/)[Email del cliente]

La API devuelve:

JSON

{    "id": "12345",    "tier": "premium",    "vehicles": 2  }

Mapeas id al campo ID Cliente, tier a Tier del Cliente, y vehicles a Vehículos previos. En la siguiente respuesta, la IA puede usar /[Tier del Cliente] para decir: "Como eres un cliente premium, te ofrecemos...".

(Los errores de red y respuestas 4xx/5xx se manejan con mensajes configurables y quedan registrados en la trazabilidad).

💻 Code Tool

📍 ¿Qué es?

Es un script escrito en JavaScript que se ejecuta en un entorno aislado (seguro) dentro de Atom. No requiere autenticación ni whitelisting de IPs, y su latencia es casi nula porque no sale a la red pública.

📥 Parámetros de entrada

Aquí defines la firma de tu script. Por cada parámetro configuras:

Campo	Descripción
Nombre del parámetro	El identificador exacto con el que accederás a él dentro del código JavaScript.
Origen del valor	Campo de información: Eliges un campo capturado del nodo. Valor fijo: Ingresas un dato literal estático.

(Nota: Además del mapeo formal, dentro del código puedes escribir /: para insertar referencias rápidas a campos que se resolverán justo antes de la ejecución).

📤 Estructura de salida

Debes declarar qué va a devolver tu script utilizando un esquema JSON con claves y tipos de dato:

JSON

{    "resultado": "string",    "monto_calculado": "number",    "es_valido": "boolean"  }

Esta declaración cumple una doble función: le enseña al LLM qué esperar del script y habilita la interfaz visual para guardar las respuestas en campos.

⚙️ Ejecución y descripción

Guardar el resultado: Funciona exactamente igual que en HTTP Request (pruebas el script y mapeas el JSON de retorno a tus campos).
Descripción de ejecución: El Code Tool lleva un campo de "descripción". Esto es vital: es lo que el LLM lee para saber cuándo debe ejecutar el código. Sin una buena descripción, la IA no lo invocará.

📝 Ejemplo de flujo

El nodo capturó Precio del vehículo y Plazo en meses. El Code Tool recibe ambos parámetros, hace su cálculo interno y devuelve:

JSON

{    "cuota_mensual": 850.50,    "interes_total": 2406.00,    "tasa_aplicada": 0.18  }

Mapeas los resultados a tus campos y el prompt responde: "Tu cuota mensual sería de $/[Cuota Mensual Calculada] con una tasa del /[Tasa Aplicada]%."

🚨 Manejo de errores y Seguridad

Si el script falla (por excepción, timeout o error de sintaxis), se marca como error de herramienta, se captura en los logs sin romper el flujo y se dispara tu mensaje de error configurado.
Regla de oro de Seguridad: Un Code Tool NUNCA debería contener contraseñas o credenciales escritas en texto plano. Si necesitas llamar a un servicio externo seguro, usa un HTTP Request donde las credenciales vivan en variables de entorno cifradas.

🔄 Disponibilidad de los datos capturados

Los campos que escriben tanto HTTP Request como Code Tool quedan inmediatamente disponibles para:

Referenciarlos usando / en los siguientes mensajes del mismo nodo.
Usarlos como variables en otras peticiones HTTP o Code Tools.
Pasarlos a los nodos siguientes de tu arquitectura en Flowbuilder.

¡Lleva la inteligencia de tu agente al siguiente nivel! 🚀

Integrar HTTP Requests y Code Tools convierte a tu IA conversacional en un operador transaccional capaz de resolver cálculos complejos, conectarse con tu ecosistema y personalizar cada experiencia al máximo. ✅