Ejecuta el ejemplo
Con Node.js instalado, guarda este código comoorder-status-tool.mjs:
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:200:
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 conGET 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:
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.