Skip to main content
Este ejemplo proporciona un endpoint para la guía de herramientas personalizadas. Usa pedidos ficticios y módulos incluidos en Node.js; no requiere paquetes adicionales ni una base de datos. Implementa Visito → tu endpoint. Registrar una herramienta no crea el backend por ti.

Ejecuta el ejemplo

Con Node.js instalado, guarda este código como order-status-tool.mjs:
Inicia el servidor:
local-demo-only es un valor público de ejemplo para pruebas en tu máquina. Usa un secreto privado nuevo antes de exponer el endpoint fuera de ella. El servidor devuelve datos fijos y no verifica la identidad del cliente; no es un servicio de pedidos de producción.

Comprueba la solicitud y la respuesta

En otra terminal, ejecuta:
Respuesta esperada con HTTP 200:
Prueba estas variantes antes de conectar Visito: El esquema ayuda al agente a construir los argumentos; valida también las solicitudes en tu backend. No exijas metadatos de conversación en las pruebas directas: el endpoint de prueba de Visito envía meta.tenantId y meta.source: "developer_test". Las llamadas desde conversaciones incluyen meta.tenantId, meta.conversationKey, meta.conversationId, meta.channel y meta.eventId cuando corresponden.

Haz accesible el endpoint

La URL guardada debe funcionar desde el backend de Visito, no solo desde tu navegador. En un contenedor puede ser necesario cambiar 127.0.0.1 por 0.0.0.0 y configurar el acceso al puerto. Restringe el acceso al entorno de pruebas. Una URL de loopback guardada en Visito alojado no permite acceder a tu laptop. Usa la URL resultante con la ruta /visito/order-status en Build → Tool calls. Selecciona POST, Bearer y el secreto de tu endpoint. Copia el esquema y la descripción de la guía del producto.

Conecta una API existente

Una herramienta GET envía argumentos como parámetros de consulta, por ejemplo ?order_number=A-1003. Una herramienta POST envía { "arguments": { ... }, "meta": { ... } }. No envía un objeto de pedido plano ni sustituye argumentos en plantillas de rutas. Si tu proveedor espera /orders/A-1003, otro cuerpo de solicitud o credenciales OAuth que se renuevan, resuelve esos detalles en tu endpoint adaptador. Valida la solicitud, consulta al proveedor y devuelve un JSON pequeño. Las credenciales del proveedor permanecen en tu servidor; el secreto de la herramienta autentica a Visito frente al adaptador.

Prueba la definición guardada

Puedes mantener Activa apagada para esta prueba por API. Obtén el ID con GET https://platform-api.visitoai.com/m2m/v1/tools usando una clave con tools:read. Define VISITO_API_KEY en tu terminal desde un almacenamiento seguro. Para ejecutar la prueba, la clave debe pertenecer al espacio de pruebas y tener tools:execute. Sustituye YOUR_TOOL_ID antes de ejecutar:
La prueba llama a tu endpoint y crea un log. Comprueba ok: true y output; una ejecución fallida puede devolver HTTP 200 desde la API de prueba de Visito con ok: false y un error. Que curl termine correctamente no basta. Esta clave API de Visito es distinta de TOOL_DEMO_SECRET. No la pegues en el campo Secreto de la herramienta para autenticarte con este ejemplo.

Prueba el comportamiento del agente

En un espacio sin canales de clientes activos, habilita la definición y abre un chat nuevo en Playground:
  • “¿Dónde está el pedido A-1003?” debe mostrar actividad completada y una respuesta basada en el estado.
  • “¿Ya enviaron mi pedido?” debe pedir el número.
  • “¿Dónde está el pedido A-9999?” debe mostrar actividad completada y explicar que no se encontró el pedido.
  • “¿Dónde está el pedido A-5000?” debe mostrar actividad fallida y reconocer el error de consulta.
Son resultados esperados, no sesiones capturadas. Revisa Build → Tool calls → Logs de actividad para comprobar la entrada y respuesta reales. Consulta los ejemplos de Playground para distinguir lo que ve el operador de lo que recibe el cliente.

Sustituye el ejemplo por tu sistema

Reemplaza los datos fijos con una lectura autorizada de tu sistema de pedidos. Autentica a Visito, verifica que el solicitante pueda ver el pedido y devuelve solo los campos necesarios. Los metadatos de conversación aportan contexto, pero no prueban que el pedido pertenezca al cliente. Usa estados claros y estimaciones de entrega basadas en tu sistema. No devuelvas un estado de envío si el proveedor falla. Limita las solicitudes y responde dentro del timeout; Visito también puede limitar el tiempo mediante su presupuesto de ejecución. Al terminar, desactiva la definición de demostración, detén el servidor con Ctrl+C y cierra cualquier túnel de desarrollo. Mantén las cancelaciones y otras modificaciones en herramientas con autorización separada.