> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Agent
> Nodo de agente inteligente para conversaciones autónomas impulsadas por IA
El nodo **AI Agent** es el componente central para crear conversaciones autónomas impulsadas por inteligencia artificial en Brain Studio. Permite configurar un agente que procesa mensajes del usuario, consulta bases de conocimiento, ejecuta herramientas y genera respuestas contextuales de forma autónoma.
El panel de configuración se organiza en **cuatro pestañas**:
1. **General** — Modelo e instrucciones
2. **Tools** — Herramientas nativas, personalizadas y MCP
3. **Contexto** — Mensaje inicial, historial y conocimiento externo
4. **Avanzado** — Guardar respuesta, modelo de respaldo, seguridad, expiración, DLP y más
***
## General
La pestaña General contiene la configuración esencial del agente.
### Modelo
Selecciona el modelo de lenguaje (LLM) que utilizará el agente para generar respuestas. Considera latencia, costo y complejidad de las tareas antes de seleccionarlo.
Los modelos disponibles incluyen:
**OpenAI**
* **GPT 4.1 Mini**: variante simplificada de GPT-4.1 optimizada para respuestas rápidas con menor demanda de recursos.
* **GPT 4.1**: evolución refinada de GPT-4, con mejor comprensión, razonamiento y precisión.
* **GPT 4-o (Azure)**: versión de GPT 4-o alojada en Azure, enfocada en estabilidad y rendimiento en entornos empresariales. Soporta visión.
* **GPT 4-o Mini**: versión más rápida y ligera de GPT 4-o, orientada a casos donde prima la velocidad. Soporta visión.
* **GPT 5.2**: modelo de última generación de OpenAI con razonamiento avanzado, mayor contexto y alta precisión en tareas complejas.
**Anthropic (Claude)**
* **Claude 3.5 Sonnet**: excelente para tareas complejas que requieren textos más elaborados y contextos extensos.
* **Claude 4 Sonnet**: alta capacidad de razonamiento y análisis.
* **Claude 4.6 Sonnet**: última generación de Claude, con razonamiento mejorado y mayor precisión.
**Google (Gemini)**
* **Gemini 2.5 Flash**: procesamiento rápido con capacidades multimodales. Soporta visión.
* **Gemini 2.5 Pro**: razonamiento avanzado con capacidades multimodales. Soporta visión.
* **Gemini 3 Flash**: última generación de Gemini con procesamiento multimodal optimizado. Soporta visión.
**Meta (Llama)**
* **Llama 4 Scout**: modelo ágil y de baja latencia, ideal para ideas rápidas e interacciones ligeras.
* **Llama 4 Maverick**: modelo de alto rendimiento diseñado para razonamientos exigentes y resolución multistep.
Los modelos marcados con **"Soporta visión"** pueden procesar imágenes subidas en la pestaña Contexto. Si necesitas que el agente interprete imágenes como parte de su contexto, selecciona uno de estos modelos.
También puedes agregar **modelos personalizados** usando el botón "Agregar modelo". Esto permite conectar modelos propios o de terceros que no estén en la lista predefinida.
### Instrucciones
Define el comportamiento base del agente mediante un prompt de sistema. Las instrucciones determinan qué rol adopta, qué tono utiliza y qué pasos sigue antes de responder. Asegúrate de que sean breves, concretas y libres de ambigüedades.
Las instrucciones soportan **interpolación de variables** usando la sintaxis `{{$variable}}`, lo que permite personalizar el comportamiento dinámicamente según el contexto de la conversación.
El campo incluye un contador de caracteres que se ajusta según el modelo seleccionado, ya que cada modelo tiene un límite máximo diferente.
[Ver recomendaciones y ejemplos de prompting](/guides/agentes-ia/prompting)
***
## Tools
La pestaña Tools permite agregar herramientas que amplían las capacidades del agente más allá de la generación de texto. El agente decide autónomamente cuándo invocar cada herramienta según el contexto de la conversación.
Para agregar herramientas, haz clic en el botón **"+ Agregar tools"** y selecciona las herramientas que necesites.
### Tools nativas
Son herramientas predefinidas e integradas en la plataforma. Están marcadas con el texto "(Nativa)" en el selector:
| Herramienta | Descripción |
| :----------------------------- | :----------------------------------------------------------------- |
| **Búsqueda de productos** | Consulta el catálogo de productos configurado en el bot |
| **Enviar mensaje interactivo** | Renderiza botones, listas y quick replies al usuario |
| **Enviar Call to Action** | Envía botones CTA con URL, con soporte de WebView |
| **Fecha y hora actual** | Obtiene la fecha y hora del momento en una zona horaria específica |
| **Día de la semana** | Calcula el día correspondiente a una fecha |
| **Transferir a asesor** | Transfiere la conversación a un agente humano o cola de atención |
[Ver documentación detallada de tools nativas](/guides/agentes-ia/tools-nativas)
### Tools personalizadas
Herramientas creadas por el usuario desde Brain Studio. Al agregar una tool personalizada puedes configurar:
* **Nombre** y **descripción** que el modelo utiliza para decidir cuándo invocarla.
* **Parámetros de entrada** personalizados.
* **Acción al ejecutar**: comportamiento posterior a la ejecución de la herramienta.
[Ver cómo crear tu primer tool](/guides/tools/tu-primer-tool)
### Tools MCP (Model Context Protocol)
Integra servicios externos mediante el estándar MCP. Existen dos tipos de integración:
#### Apps MCP nativas
Aplicaciones del marketplace de Jelou que se instalan directamente en la plataforma. Cada app MCP puede configurarse en dos modos:
* **Modo integración**: habilita todas las herramientas de la app de una vez.
* **Modo granular**: permite seleccionar herramientas individuales de la app y configurar cada una por separado.
#### Parámetros por defecto
En modo granular, cada herramienta individual permite configurar **parámetros por defecto**. Haz clic en una herramienta para abrir su vista de detalle, donde puedes:
* Ver todos los parámetros de la herramienta con su tipo, descripción y si son requeridos.
* **Fijar valores por defecto** que el agente usará en cada invocación, en lugar de dejar que la IA los decida.
* Usar el **selector de variables** para inyectar valores dinámicos del flujo (ej: `{{$context.email}}`).
* Alternar entre vista de **formulario** y **editor JSON** para editar todos los parámetros de una vez.
* Buscar parámetros por nombre cuando la herramienta tiene muchos.
Cada parámetro muestra un indicador:
| Indicador | Significado |
| :--------- | :--------------------------------------------------------------- |
| **Manual** | Tiene un valor fijado por ti — el agente usará ese valor siempre |
| **Auto** | Sin valor fijado — el agente decide el valor en cada invocación |
Si dejas todos los parámetros en "Auto", el comportamiento es idéntico al anterior: el agente decide todos los valores según el contexto de la conversación.
#### Servidores MCP externos
Conexiones a servidores MCP propios mediante URL personalizada.
Ingresa la URL del endpoint de tu servidor MCP.
Configura headers personalizados (nombre y valor) para autenticación u otros metadatos.
Una vez conectado, selecciona las herramientas disponibles que deseas habilitar.
### Acciones de herramientas
Cada herramienta (nativa, personalizada o MCP) puede configurar una acción que se ejecuta tras su invocación:
| Acción | Comportamiento |
| :--------------------- | :--------------------------------------------------------- |
| **Ninguna** | El agente continúa la conversación normalmente |
| **Finalizar función** | La ejecución del flujo termina tras usar la herramienta |
| **Pausar interacción** | La conversación se pausa hasta que se reanude externamente |
***
## Contexto
La pestaña Contexto centraliza la configuración del contexto de entrada del agente: cómo inicia cada conversación, cuántos mensajes anteriores recuerda y qué fuentes de conocimiento consulta para generar sus respuestas.
### Mensaje inicial
Define el texto que el agente recibe como primer turno de usuario cuando el nodo comienza a ejecutarse. Esta configuración determina con qué información arranca el agente para generar su primera respuesta.
| Opción | Comportamiento | Cuándo usarla |
| :-------------------------- | :------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------- |
| **Pasar el último mensaje** | El agente recibe el último mensaje de la conversación como entrada inicial | La mayoría de los casos: atención al cliente, soporte técnico, consultas generales |
| **Sin mensaje de usuario** | No se envía ningún turno de usuario al modelo; el agente responde solo con sus instrucciones de sistema | Cuando no hay un mensaje de usuario relevante que pasar al agente (campañas HSM, workflows automatizados, post-recolección de datos) |
| **Personalizado** | Muestra un campo de texto con selector de variables para definir un valor personalizado | Cuando necesitas combinar variables o enviar un contexto específico al agente |
**Pasar el último mensaje** es la opción predeterminada y la recomendada para la mayoría de los casos. El agente recibe automáticamente lo que el usuario escribió (equivale internamente a `{{$message.text}}`), lo que permite una experiencia conversacional natural.
#### Ejemplos por caso de uso
**`Pasar el último mensaje`** — Atención al cliente
Un usuario escribe "¿Cuál es el horario de atención?" y el agente lo recibe directamente como entrada, generando una respuesta basada en su base de conocimiento.
**`Sin mensaje de usuario`** — Cuando no hay una consulta real del usuario
Usa esta opción cuando el último mensaje disponible no representa una consulta real del usuario. Escenarios comunes:
* **Post-campaña HSM**: el usuario respondió a una plantilla de WhatsApp tocando un botón como "Sí, me interesa". Ese payload no es una consulta — el agente debe iniciar desde sus instrucciones y el contexto del flujo.
* **Workflows automatizados**: el flujo fue disparado por un webhook, un scheduler o una API externa. No existe un mensaje de usuario porque ningún usuario escribió.
* **Post-recolección de datos**: nodos Input anteriores ya recopilaron nombre, número de orden, etc. El último mensaje es un dato (ej: `"ORD-12345"`), no una pregunta. El agente debe responder con base en la información ya almacenada en memoria.
En este modo, el agente genera su primera respuesta basándose únicamente en sus instrucciones de sistema. Si necesitas que el agente salude al usuario, configúralo en las instrucciones del agente.
**`Personalizado`** — Contexto a medida con variables
Permite construir un mensaje de entrada combinando variables del flujo. Por ejemplo, para pasar información de contexto al agente:
```
Producto: {{$context.product_name}}. Consulta: {{$message.text}}
```
Esto es útil cuando el agente necesita contexto adicional más allá del mensaje del usuario, como datos recopilados en nodos anteriores del flujo.
Al seleccionar **Personalizado**, el campo soporta interpolación de variables con la sintaxis `{{$variable}}` y tiene un límite de 100 caracteres. Usa el selector de variables para explorar las variables disponibles en tu flujo.
### Recordar mensajes previos
Cuando está habilitado, el agente incluye como contexto los últimos N mensajes de la conversación cada vez que inicia. Esto permite mantener coherencia conversacional cuando el usuario retoma una sesión después de un intervalo.
Activa el toggle de **Recordar mensajes previos**.
Ingresa cuántos mensajes anteriores debe recordar el agente. El rango válido es de **1 a 50 mensajes**.
Usa un valor bajo (5–10 mensajes) para conversaciones transaccionales y un valor más alto para soporte técnico donde el historial completo puede ser relevante.
### Bloque de carga
El bloque de carga unificado acepta documentos e imágenes en la misma interacción. Puedes agregar archivos de tres formas:
* **Arrastra y suelta** archivos directamente sobre el bloque
* **Haz clic** en el bloque para abrir el selector de archivos
* **Pega una URL** en el campo de enlace ubicado en la parte inferior del bloque (soporta los mismos formatos de documentos e imágenes listados abajo)
| Tipo | Formatos soportados | Tamaño máximo |
| :------------- | :---------------------------------------------- | :---------------- |
| **Documentos** | `.pdf`, `.xlsx`, `.md`, `.txt`, `.json`, `.csv` | 2 MB por archivo |
| **Imágenes** | `.jpg`, `.jpeg`, `.png` | 10 MB por archivo |
Además de `.pdf` y `.csv`, puedes cargar archivos `.xlsx`, `.md`, `.txt` y `.json` como fuentes de conocimiento.
Los documentos se procesan uno por uno. Si seleccionas o arrastras varios documentos simultáneamente, solo el primero se procesará y recibirás un aviso para cargar los restantes individualmente. Las imágenes, en cambio, se procesan en lote.
### Documentos
Al cargar un documento se abre un panel donde defines su **nombre** (máximo 30 caracteres) y una **descripción** opcional que ayuda al agente a entender el contenido del archivo. Una vez cargado, puedes editar sus metadatos o eliminarlo desde la lista.
### Imágenes
Las imágenes se suben directamente sin pasos adicionales y aparecen como miniaturas debajo del bloque de carga. Puedes subir hasta **3 imágenes** por agente.
* Haz clic en una miniatura para verla en pantalla completa
* Pasa el cursor sobre una miniatura para ver el botón de eliminar
Las imágenes requieren un modelo con **capacidades multimodales** (marcados con "Soporta visión" en la [lista de modelos](#modelo)). Si el modelo seleccionado no soporta visión, verás un banner de advertencia y el agente no procesará las imágenes durante la conversación.
### Datastores
Conecta bases de datos de Datum para que el agente consulte información estructurada en tiempo real:
* Selecciona el datastore a conectar
* Configura las operaciones permitidas sobre la base de datos
Se recomienda cargar siempre documentos en la pestaña Contexto para anclar las respuestas del agente a la documentación oficial de tu negocio. Asigna descripciones claras a cada archivo cargado para maximizar la efectividad. El modelo priorizará la información de tus archivos y datastores sobre su conocimiento general, reduciendo drásticamente el riesgo de alucinaciones.
### Contexto externo
Permite reanudar este nodo desde un sistema externo mediante la API de reanudación. Útil para flujos que requieren procesamiento asíncrono externo, como validaciones, pagos o aprobaciones.
Activa el toggle **Agregar contexto externo** para desplegar la configuración.
Copia la URL del endpoint que tu sistema externo deberá llamar:
```
POST https://gateway.jelou.ai/workflows/v1/skills/resume
```
Tu sistema externo debe enviar la siguiente petición:
**Headers**
```json theme={null}
{
"x-api-key": "Tu API key",
"Content-Type": "application/json"
}
```
**Payload**
```json theme={null}
{
"executionId": "{{$context.executionId}}",
"message": "string (opcional)",
"pauseInteraction": false
}
```
El `executionId` está disponible como `{{$context.executionId}}` dentro del flujo y tiene una validez de 24 horas.
***
## Avanzado
La pestaña Avanzado contiene configuraciones adicionales para un control más fino del comportamiento del agente.
### Guardar respuesta
Permite almacenar la última respuesta del agente en una variable para usarla en nodos posteriores del flujo.
Activa el toggle correspondiente.
Escribe el nombre de la variable donde se almacenará la respuesta (por ejemplo: `ai_agent_response`).
La variable estará disponible como `{{$context.ai_agent_response}}` en los nodos siguientes del flujo.
### Modelo de respaldo (Fallback)
Selecciona un modelo alternativo que se utilizará automáticamente si el modelo principal falla o no está disponible.
El modelo de respaldo no puede ser el mismo que el modelo principal.
### Opciones de procesamiento
Opciones independientes para habilitar capacidades adicionales sobre los mensajes que el usuario envía durante la conversación:
| Opción | Descripción |
| :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------- |
| **Soporte PDF** | Permite al agente leer y procesar documentos PDF enviados por el usuario durante la conversación (solo texto, no imágenes dentro del PDF) |
| **Leer URLs de imagen** | Habilita al agente para procesar imágenes que el usuario envía como URL con texto descriptivo durante la conversación |
| **Soporte Quick Reply Payload** | Permite al agente interpretar el payload de respuestas rápidas de mensajes interactivos |
Estas opciones aplican a los archivos que el **usuario final** envía durante la conversación. Las imágenes y documentos que tú configuras como contexto del agente se gestionan desde la pestaña **Contexto**.
### Respuesta en varios mensajes
Divide la respuesta del agente en burbujas separadas cuando contiene saltos de párrafo (`\n\n`), URLs de medios o listas. Las URLs de imagen, video, audio o documento se envían como burbujas de medios independientes según el canal, mientras que las listas numeradas se mantienen juntas.
Activado por defecto en los agentes creados a partir del 24 de abril de 2026. Los agentes anteriores mantienen el comportamiento previo (una sola burbuja) hasta que actives el toggle manualmente.
### Seguridad (Guardrails)
Configura el nivel de protección del agente contra usos indebidos, inyecciones de prompt y solicitudes fuera de alcance.
Activa el toggle de seguridad para acceder a las opciones de configuración.
Elige el preset que mejor se ajuste a tu caso de uso:
| Nivel | Descripción |
| :---------- | :---------------------------------------------------------- |
| **Bajo** | Protección mínima, mayor flexibilidad en respuestas |
| **Medio** | Balance entre seguridad y flexibilidad (recomendado) |
| **Alto** | Protección estricta, restringe respuestas fuera del alcance |
| **Crítico** | Máxima protección, ideal para contextos regulados |
Habilita una capa adicional de protección que filtra entradas y salidas del modelo para detectar contenido malicioso.
[Ver guía completa de seguridad y guardrails](/guides/agentes-ia/seguridad)
### Expiración
Configura un tiempo límite para la sesión del agente. Si el usuario no responde dentro del tiempo configurado, la sesión expira automáticamente.
Activa el toggle de expiración.
Define el tiempo y selecciona la unidad:
* **Minutos**: rango de 1 a 1200
* **Horas**: rango de 1 a 20
* **Valor por defecto**: 8 horas (28,800 segundos)
### DLP (Prevención de pérdida de datos)
Habilita la detección y enmascaramiento automático de información sensible en las conversaciones del agente.
Activa el toggle de DLP para acceder a la configuración.
Elige qué tipos de información deben ser detectados y enmascarados automáticamente:
| Tipo de dato | Valor de reemplazo por defecto |
| :--------------------------- | :----------------------------- |
| Número de tarjeta de crédito | `[CreditCardNumber]` |
| Track de tarjeta de crédito | `[CreditCardTrackNumber]` |
| Correo electrónico | `[EmailAddress]` |
| Número de cuenta financiera | `[FinancialAccountNumber]` |
| Dirección IP | `[IpAddress]` |
| Ubicación | `[Location]` |
| Coordenadas geográficas | `[LocationCoordinates]` |
| Número de teléfono | `[PhoneNumber]` |
| Fecha | `[Date]` |
| Nombre de persona | `[PersonName]` |
Modifica el valor de reemplazo para cada tipo de dato según tus necesidades.
El tipo **Número de tarjeta de crédito** siempre está seleccionado por defecto y no puede deshabilitarse.
### Mensaje de seguimiento
Permite que el agente retome de forma proactiva una conversación inactiva, enviando un recordatorio al usuario que dejó de responder. Al activar el toggle **Habilitar mensaje de seguimiento** aparece un botón de configuración que abre un modal donde defines cómo se comporta el recordatorio.
Activa el toggle para mostrar el botón de configuración. Haz clic en el ícono de engranaje para abrir el modal **Mensaje de seguimiento**.
Selecciona cómo se genera el recordatorio:
* **Automático**: el agente redacta el recordatorio por sí mismo a partir de la conversación.
* **Manual**: escribes una instrucción que define cómo debe comportarse el agente al retomar. El campo admite hasta **900** caracteres.
Ajusta los dos controles que evitan que el agente insista de más:
| Campo | Descripción | Valores |
| :---------------------------------------- | :------------------------------------------------------------------------------ | :---------------------------------------------------------- |
| **Espera entre wakeups** | Tiempo de inactividad antes de enviar cada recordatorio. | 5, 10, 15, 20, 25, 30, 45, 60 o 120 minutos (por defecto 5) |
| **Detener tras # intentos sin respuesta** | Cantidad máxima de recordatorios consecutivos sin respuesta antes de detenerse. | 1 a 5 (por defecto 2) |
Las opciones disponibles se limitan al **tiempo de expiración** del agente: solo puedes elegir valores menores a ese tiempo. Una vez que la sesión expira, el agente deja de enviar recordatorios.
***
## Ejemplo de configuración
Un flujo típico de configuración para un agente de atención al cliente:
Selecciona **GPT-4.1** como modelo y escribe instrucciones claras definiendo el rol, tono y alcance del agente.
Habilita **Transferir a asesor** para escalar conversaciones complejas, **Búsqueda de productos** si el agente gestiona consultas de catálogo, y **Enviar mensaje interactivo** para mostrar opciones al usuario.
Selecciona **Pasar el último mensaje** como mensaje inicial, sube el documento de preguntas frecuentes en formato PDF, agrega imágenes de referencia si el modelo soporta visión, y conecta el datastore de productos si aplica.
Configura un **modelo de respaldo**, establece la **expiración** en 30 minutos, habilita **seguridad** en nivel medio y activa **DLP** si se manejan datos financieros o personales.