Tools nativas

Herramientas nativas disponibles en el nodo AI Agent para consultar productos, manipular fechas, enviar mensajes interactivos y transferir conversaciones

Las tools nativas son herramientas predefinidas e integradas en la plataforma que permiten al modelo de IA realizar acciones específicas durante una conversación. Estas herramientas extienden las capacidades del agente de IA más allá de la generación de texto, permitiéndole interactuar con el sistema, consultar información, manipular datos y ejecutar acciones concretas.

Las tools nativas se encuentran y configuran en el nodo AI Agent. Para acceder a ellas:

1. Selecciona el nodo AI Agent en tu flujo
2. Abre la sección TOOLS en la configuración del nodo
3. Haz clic en el botón ”+ Agregar tools”
4. En el campo “Selecciona un Tool”, verás la lista de todas las tools disponibles, incluyendo las nativas (marcadas con el texto “(Nativa)”)

A continuación se describen todas las herramientas nativas disponibles en el nodo AI Agent:

​

Búsqueda de productos

Busca productos en el catálogo disponible para recomendar al usuario. Utiliza un motor de búsqueda para encontrar coincidencias basadas en el nombre del producto o términos relacionados.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
product	string	Sí	Término de búsqueda o nombre del producto.
top_k	number	No	Cantidad máxima de resultados a retornar.
score_threshold	number	No	Puntuación mínima de similitud (0.0 a 1.0) para considerar un resultado relevante.
client_reference_id	string	No	ID de referencia del cliente para búsquedas personalizadas.

Ejemplo de Prompt:

“Si el usuario pregunta por la disponibilidad de algún artículo o modelo específico, DEBES usar la herramienta search_products para consultar el catálogo antes de responder.”

Ejemplo de Argumentos:

{
  "product": "iPhone 15 Pro",
  "top_k": 5,
  "score_threshold": 0.85
}

Respuesta: Retorna un listado de productos encontrados o un mensaje indicando que no se encontraron resultados. En caso de error, devuelve un mensaje de sistema descriptivo.

Notas:

• Requiere que el canal tenga un catálogo de productos configurado y accesible.

---

​

Transferir a asesor

Transfiere la conversación actual del usuario a un agente humano o a una cola de atención. Permite especificar estrategias de enrutamiento y prioridades.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
assignment_type	enum	No (Default: direct)	Método de asignación: direct (inmediato) o queue (cola de tickets).
assignment_by	enum	No (Default: shuffle)	Estrategia de enrutamiento: shuffle (auto), team, operators, general.
teamId	number	No*	ID del equipo. *Requerido solo si assignment_by es ‘team’.
operatorId	number	No*	ID del operador. *Requerido solo si assignment_by es ‘operators’.
priority	number	No (Default: 0)	Prioridad en la cola (0-10), solo relevante para assignment_type='queue'.

Ejemplo de Prompt:

“Cuando el usuario exprese frustración o solicite hablar explícitamente con una persona real, ejecuta la función transfer_to_agent inmediatamente.”

Ejemplo de Argumentos:

Caso: Transferencia directa automática (más común)

{
  "assignment_type": "direct",
  "assignment_by": "shuffle"
}

Caso: Transferencia directa a un equipo

{
  "assignment_type": "direct",
  "assignment_by": "team",
  "teamId": 4501
}

Caso: Crear ticket en cola general

{
  "assignment_type": "queue",
  "assignment_by": "general",
  "priority": 5
}

Respuesta: Retorna un objeto JSON con el resultado de la operación indicando si la transferencia se inició correctamente.

Notas:

• Puede finalizar el flujo de IA inmediatamente.
• Cuando se usa assignment_type: "queue" con assignment_by: "general", se crea un ticket en la cola general de atención.
• Importante: No se deben inventar IDs de equipos u operadores; se deben usar los configurados explícitamente.

---

​

Enviar mensajes interactivos

Envía un mensaje estructurado o interactivo al usuario. El formato exacto depende del canal (WhatsApp, Web, etc.), pero generalmente incluye botones o listas de opciones.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
text	string	Sí	Contenido principal del mensaje. Máximo 1024 caracteres.
title	string	No	Cabecera/título del mensaje. Máximo 60 caracteres.
caption	string	No	Subtítulo o descripción complementaria. Máximo 60 caracteres. En WhatsApp con 4+ opciones, se usa como texto del botón que despliega la lista.
options	array	Sí	Lista de opciones/botones. Ver estructura abajo.

Estructura de options (Array de objetos):

• title (string, obligatorio): Texto de la opción/botón. Máximo 20 caracteres. No se permiten títulos duplicados.
• description (string, opcional): Descripción adicional de la opción. Máximo 72 caracteres.

Ejemplo de Prompt:

“Si el usuario pregunta qué servicios ofrecemos DEBES usar send_interactive_message para mostrar un menú con las opciones disponibles.”

Ejemplo de Argumentos (Botones - 3 o menos opciones):

{
  "text": "¿Cómo deseas continuar con tu consulta?",
  "title": "Opciones de Servicio",
  "caption": "Selecciona una opción",
  "options": [
    {
      "title": "Hablar con Agente",
      "description": "Transferir a soporte humano"
    },
    {
      "title": "Ver Catálogo",
      "description": "Explorar productos disponibles"
    }
  ]
}

Ejemplo de Argumentos (Lista WhatsApp - 4+ opciones):

{
  "text": "Tenemos varios departamentos disponibles para atenderte.",
  "title": "Departamentos",
  "caption": "Ver opciones",
  "options": [
    { "title": "Ventas", "description": "Consultas de productos y precios" },
    { "title": "Soporte Técnico", "description": "Ayuda con problemas técnicos" },
    { "title": "Facturación", "description": "Consultas sobre pagos" },
    { "title": "Devoluciones", "description": "Gestionar devoluciones" }
  ]
}

En WhatsApp, cuando envías 4 o más opciones, el mensaje se muestra como una lista desplegable. El valor de caption se usa como texto del botón que abre la lista (en el ejemplo anterior, “Ver opciones”).

Respuesta: Retorna "Message sent successfully." si el envío fue exitoso o un mensaje de error en caso contrario.

Notas:

• Envía un mensaje real al usuario.
• El tipo de mensaje se adapta automáticamente según el canal y la cantidad de opciones.

---

​

Enviar Call to Action (CTA)

Envía un botón de llamada a la acción que abre una URL externa. Puede configurarse como WebView para formularios o pagos que requieren esperar una respuesta del usuario.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
text	string	Sí	Contenido principal del mensaje.
url	string	Sí	URL que se abre al hacer clic en el botón.
display_text	string	Sí	Texto del botón CTA. Máximo 20 caracteres.
title	string	No	Cabecera/título del mensaje.
caption	string	No	Subtítulo para complementar el mensaje.
is_webview	boolean	No	Si es true, envía como WebView que pausa el flujo y espera callback. Default: false.
expiration_time	number	No	Segundos para esperar el callback antes de expirar. Default: 300. Solo aplica cuando is_webview=true.
pending_message	string	No	Mensaje a mostrar si el usuario envía texto mientras se espera el callback del WebView.
response_variable	string	No	Nombre de la variable donde guardar la respuesta del callback.
input	string | object	No	Datos para pasar al WebView como parámetros de URL.

Ejemplo de Prompt:

“Cuando el usuario confirme que desea realizar el pago, usa send_call_to_action con is_webview=true para enviar el enlace de pago y esperar la confirmación.”

Ejemplo de Argumentos (CTA simple):

{
  "text": "Visita nuestra tienda online para ver todos los productos disponibles.",
  "url": "https://tienda.ejemplo.com/catalogo",
  "display_text": "Ver Catálogo",
  "title": "Tienda Online"
}

Ejemplo de Argumentos (WebView con espera de respuesta):

{
  "text": "Haz clic en el botón para completar tu pago de forma segura.",
  "url": "https://pagos.ejemplo.com/checkout",
  "display_text": "Pagar Ahora",
  "title": "Completar Pago",
  "is_webview": true,
  "expiration_time": 600,
  "pending_message": "Por favor, completa el pago en la ventana abierta antes de continuar.",
  "response_variable": "payment_result",
  "input": {
    "order_id": "12345",
    "amount": 99.99
  }
}

Respuesta:

• CTA normal: "Call-to-action message sent successfully."
• WebView: "WebView message sent. Waiting for user action."

Notas:

• Disponible solo para los proveedores de WhatsApp que soportan este tipo de mensajes.
• Cuando is_webview=true, el flujo se pausa hasta que el WebView devuelve un callback o expira el tiempo.
• El valor de input se convierte a parámetros de URL query string.
• La respuesta del callback se guarda en la variable especificada en response_variable.

---

​

Fecha y hora actual

Obtiene la fecha y hora actual. Permite especificar una zona horaria para obtener la hora local correcta.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
timezone	string	No	Zona horaria deseada en formato IANA (ej: “America/Guayaquil”, “UTC”).

Ejemplo de Prompt:

“Antes de procesar cualquier solicitud que dependa de la hora (como ‘buenos días’ o citas para ‘hoy’), llama a get_current_date_time para saber la hora exacta.”

Ejemplo de Argumentos:

{
  "timezone": "America/Mexico_City"
}

Respuesta: Retorna un string con la fecha y hora formateada, por ejemplo: "Monday, December 08, 2025 10:30 AM".

Notas:

• No tiene efectos secundarios visibles para el usuario.
• Es puramente informativa para el modelo.

---

​

Día de la semana

Calcula y retorna el día de la semana correspondiente a una fecha específica proporcionada.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
date	string	Sí	Fecha a consultar (formato ISO o legible standard, ej: “2024-12-25”).

Ejemplo de Prompt:

“Si el usuario quiere agendar para una fecha específica, verifica primero qué día de la semana es usando get_weekday_of_a_date para asegurar que sea un día hábil.”

Ejemplo de Argumentos:

{
  "date": "2025-12-10"
}

Respuesta: Retorna el nombre del día de la semana, por ejemplo: "Wednesday".

Notas:

• Útil para validar citas o agendas.

---

​

Gestión de memoria

Las siguientes tools se activan desde la sección Gestión de memoria de la pestaña Contexto del nodo AI Agent. Dan al agente memoria de trabajo, acceso al CRM de la bandeja de entrada, variables del contexto del flujo e información de plataforma. Consulta la sección Gestión de memoria del nodo AI Agent para ver cómo activarlas y configurar sus permisos.

​

Memoria interna

Permite al agente guardar, recordar y eliminar información de la conversación para reutilizarla más adelante. Es memoria de trabajo por usuario, con vigencia limitada: recuerda datos del mismo usuario entre conversaciones, pero no es un almacén permanente.

Operaciones:

Operación	Acción	Descripción
Crear	save	Guarda un dato en la memoria del usuario.
Buscar	recall	Recupera datos previamente guardados.
Eliminar	delete	Borra un dato guardado.
Listar	list	Lista los datos guardados disponibles.

Notas:

• Incluye un campo opcional Espacio de memoria para aislar o agrupar los guardados, evitando que distintos contextos se mezclen.
• Cada operación admite configurar sus parámetros en modo IA, variable o estático, y un comportamiento post-ejecución (Continuar, Terminar o Pausar).

---

​

CRM de bandeja de entrada

Lee, define y actualiza datos del contacto del CRM (nombre, teléfono, etiquetas, notas y más) directamente desde la bandeja de entrada.

Operaciones:

Operación	Acción	Descripción
Leer	readStoredParams	Lee los datos almacenados del contacto.
Definir	setStoredParams	Establece datos del contacto.
Actualizar	updateStoredParams	Actualiza datos existentes del contacto.
Listar etiquetas	listTags	Lista las etiquetas del contacto.
Agregar etiqueta	addTag	Agrega una etiqueta al contacto.
Quitar etiqueta	removeTag	Quita una etiqueta del contacto.

Notas:

• Los permisos se administran por grupo (datos del contacto / etiquetas) con lectura y escritura separadas. Puedes restringir a qué etiquetas puede acceder el agente.
• Requiere al menos un canal conectado para que existan contactos sobre los cuales operar.

---

​

$context

Lee y escribe variables del contexto del flujo para compartir datos entre nodos.

Operaciones:

Operación	Acción	Descripción
Obtener	get	Lee el valor de una variable del contexto.
Establecer	set	Escribe o actualiza una variable del contexto.

Notas:

• En la lista de tools aparece como $context para distinguirla de la pestaña Contexto.
• Las variables escritas quedan disponibles para nodos posteriores del flujo, por ejemplo {{$context.mi_variable}}.

---

​

Información de plataforma

Bloques de contexto de solo lectura que inyectan datos de plataforma en el prompt del agente. No consumen una llamada de tool: la información se agrega automáticamente como contexto cuando la fuente está activa.

Fuente	Campos	Descripción
Información del usuario	names, referenceId, botId, roomId	Datos del usuario actual.
Información del canal	name, type	Datos del canal conectado.
Información de la empresa	name, plan, organizationId	Datos de la empresa.

Notas:

• Las tres fuentes son de solo lectura; el agente no puede modificarlas.
• Se inyectan como bloques de contexto, por lo que no cuentan como una invocación de herramienta.

---

​

Bases de datos

Conexión nativa a Bases de datos (Datum v2) desde la pestaña Tools del nodo AI Agent. Permite que el agente busque, cree, actualice y elimine registros en tus colecciones sin encadenar nodos auxiliares.

Operaciones: buscar, crear, actualizar y eliminar registros sobre las colecciones que habilites.

Parámetro	Tipo	Obligatorio	Descripción
operation	enum	Sí	search, create, update o delete.
collectionId	string	Sí	Colección de Bases de datos sobre la que se opera.
query	object	No*	Filtros de búsqueda. *Requerido para search.
document	object	No*	Documento a insertar o actualizar. *Requerido para create y update.
recordId	string	No*	ID del registro. *Requerido para update y delete.

Notas:

• El agente solo puede operar sobre las colecciones de la misma compañía que habilites explícitamente en el popover Configurar.
• Las operaciones de escritura persisten de inmediato.
• El comportamiento post-ejecución (Continuar, Terminar o Pausar) se configura por operación.

---

​

AI Routing

Envía la solicitud del usuario al workflow que puede atenderla, cuando pide algo que este agente no puede hacer. Usa el AI Routing del proyecto para elegir el destino, por lo que el proyecto debe tener AI Routing habilitado.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
mode	enum	No (Default: evaluate)	evaluate (elige el destino automáticamente), direct (destino indicado por el usuario) o search (lista los destinos disponibles).
message	string	No*	Mensaje del usuario tal cual. *Requerido para evaluate.
target	string	No*	Nombre o ID del destino. *Requerido para direct.

Ejemplo de Prompt:

A diferencia de otras tools, ai_router no necesita que le indiques cuándo usarla: al activarla se agregan automáticamente las reglas de derivación a las instrucciones del agente. Lo único que tienes que definir es el alcance del agente, porque todo lo que quede fuera de ahí es lo que se deriva.

“Atiendes únicamente consultas de facturación: estados de cuenta, fechas de pago y detalle de cargos.”

Ejemplo de Argumentos:

Caso: el usuario pregunta algo fuera del alcance del agente (más común)

{
  "mode": "evaluate",
  "message": "quiero reportar un problema con mi pedido"
}

Caso: el usuario nombra explícitamente el destino

{
  "mode": "direct",
  "target": "Soporte"
}

Caso: consultar los destinos disponibles antes de decidir

{
  "mode": "search"
}

Respuesta: Retorna un objeto JSON con el destino elegido, si la derivación se ejecutó y una guía para el modelo sobre qué hacer a continuación. En search y en direct sin coincidencia, retorna los destinos disponibles y no deriva nada.

Notas:

• Una derivación exitosa termina el turno del agente: la respuesta al usuario llega desde el workflow de destino. El agente no debe responder también.
• Si no hay coincidencia o la derivación falla, el agente sigue a cargo de la conversación y debe continuar atendiendo al usuario.
• Requiere que el proyecto tenga AI Routing habilitado y workflows con nombre y descripción configurados. El comportamiento posterior a la ejecución es fijo: la derivación siempre termina el turno del agente.
• El agente solo puede derivar a workflows del mismo proyecto.

Las reglas de derivación se agregan solas al activar la tool: el agente ya sabe que debe resolver por su cuenta lo que sus instrucciones cubren, que no debe derivar porque otra tool falló o porque no está seguro, y que no debe responder además de derivar. No necesitas escribir nada de esto en el prompt.