Conecta tu agente con un sistema externo

Conectar un sistema permite que tu agente llame a una API externa durante una conversación. Puede consultar información actualizada o realizar una operación compatible con tu sistema usando los detalles que ha compartido el cliente. Tú defines cuándo debe ejecutarse la acción, qué información necesita y qué endpoint debe llamar. Tu servidor procesa la solicitud y devuelve un resultado que el agente puede explicar al cliente.

​

Cuándo usarla

Usa esta acción cuando la respuesta o la operación dependa de otro sistema: consultar existencias, recuperar información de una cuenta, buscar una solicitud o enviar un cambio autorizado. Una API permite conectar el agente con tu propio software o con un servicio de terceros. Usa Conocimiento para información de referencia y políticas. Usa Recopilar datos para guardar información estructurada de la conversación en Visito. Usa Google Sheets para acceder a filas de una hoja de cálculo.

​

Antes de empezar

Necesitas acceso de administrador, un endpoint accesible desde los servidores de Visito y las credenciales que requiera. Crear una acción no crea un servidor ni proporciona acceso directo a una base de datos.

​

1. Describe la acción

Abre Configuración → Acciones → Conectar un sistema. La ventana se titula Nueva acción HTTP. Asigna un nombre claro. En Cuándo y cómo debe usarla la IA, explica:

• Qué intención del cliente debe activar la acción.
• Qué datos usar de la conversación y cuáles pedir si faltan.
• Si hace falta confirmación del cliente antes de ejecutarla.
• Cómo interpretar un resultado correcto, un registro no encontrado o un error.

Selecciona los negocios donde corresponde la acción. Elige Todos los negocios solo si el mismo endpoint y las mismas instrucciones aplican a todo el espacio de trabajo.

​

2. Configura la conexión

Al editar, deja el secreto vacío para conservar el valor guardado. Mantén las credenciales en los ajustes de autenticación, no en las instrucciones ni en el esquema de entrada. Solo lectura describe la operación prevista. Tu servidor debe aplicar sus reglas de comportamiento y acceso; este ajuste no impide que un endpoint mal implementado modifique datos.

​

3. Define los datos de entrada

Esquema JSON de parámetros define la información estructurada que debe proporcionar el agente. Añade una propiedad por dato, con su tipo y descripción. Marca como obligatorios solo los datos necesarios para ejecutar la solicitud. El agente puede aprovechar lo que ya se ha compartido y pedir los valores que falten. Describe formatos, unidades y opciones aceptadas. No incluyas resultados fijos ni credenciales en el esquema. Tu endpoint también debe validar los valores recibidos. El esquema define las entradas de la acción, no una plantilla arbitraria del cuerpo HTTP:

• GET: las entradas se envían como parámetros de consulta.
• POST: las entradas se incluyen en arguments, junto a los metadatos de conversación meta.

El endpoint lee los datos, realiza la consulta u operación autorizada y devuelve el resultado. Visito lo pone a disposición del agente para continuar la conversación. Devuelve información breve y apropiada para el cliente, en lugar de instrucciones dirigidas al agente. Si tu API requiere otro cuerpo o un valor dentro de la ruta URL, tradúcelo mediante un adaptador. Consulta qué envía Visito a tu endpoint.

​

4. Prueba antes de activar

Empieza en Solo área de pruebas con un endpoint de prueba y datos ficticios. Playground envía solicitudes HTTP reales; usa un destino donde puedas probar de forma segura los cambios permitidos. Prueba una solicitud completa, datos faltantes, valores no válidos, un registro inexistente y un fallo del servidor. Comprueba que el agente usa los hechos devueltos y explica los errores sin inventar respuestas. Para operaciones que modifican datos, verifica también el cambio en el sistema de destino. Después de probarla, guarda la acción en modo Activa para ofrecerla en las conversaciones elegibles de los negocios seleccionados. Tu endpoint debe controlar a qué registros y operaciones puede acceder cada solicitud.

​

5. Revisa la ejecución

Abre Acciones → Historial y selecciona la acción. Revisa parámetros, datos guardados de la solicitud, respuesta, estado y tiempos. Los datos guardados pueden mostrar los argumentos sin el cuerpo POST completo; las credenciales se ocultan o se redactan. Usa Abrir conversación para relacionar la ejecución con la solicitud del cliente y la respuesta del agente. Que una llamada HTTP termine no significa necesariamente que la operación haya tenido éxito: comprueba el resultado devuelto. Si no se ejecuta, revisa modo, negocios, propósito, datos pendientes y si la conversación se ha derivado a una persona. Si falla la solicitud, comprueba autenticación, acceso al endpoint, validación y tiempo de espera. Pon la acción en Inactiva para impedir nuevas llamadas; esto no deshace una solicitud que ya esté en curso.

​

Ejemplo: consultar un pedido

Los desarrolladores también pueden administrar acciones mediante la API de Acciones.