Conecta tu agente a un sistema de pedidos

Un cliente pregunta: “¿Dónde está el pedido A-1003?”. Tu agente puede usar una herramienta personalizada para consultar el pedido en tu sistema y explicar su estado actual en la conversación. Tú defines cuándo usar la herramienta y qué información recopilar. Tu endpoint consulta el pedido y devuelve los datos. Visito convierte esos datos en una respuesta.

Elige qué conectar

Usa Conocimiento para políticas y preguntas frecuentes. Usa una herramienta personalizada cuando necesites una consulta actualizada: el estado de un pedido, existencias, horarios disponibles o un saldo.

Tu sistema	Cómo conectarlo
Una API que acepta parámetros de consulta GET y devuelve JSON	Puedes conectarla directamente si los nombres de los parámetros coinciden con los de la API.
Una API que acepta el formato POST de Visito	Conecta el endpoint y configura su autenticación.
Una API con otro formato, rutas dinámicas, renovación de OAuth o varios pasos	Pide a tu desarrollador un endpoint pequeño que traduzca la solicitud de Visito a llamadas a ese sistema.
Una base de datos o un sistema sin API	Pide a tu desarrollador un endpoint de consulta específico. Este formulario no conecta Visito directamente a una base de datos.

En esta guía usamos una operación de solo lectura: consultar el estado de un pedido. Crea herramientas separadas para cancelaciones, reembolsos y cambios.

Antes de empezar

Necesitas acceso de administrador al espacio de trabajo correcto, un endpoint accesible desde el backend de Visito y un pedido de prueba. Para tu primer experimento, usa un espacio sin canales de clientes activos. Pide a tu desarrollador:

La URL del endpoint, el método HTTP y el secreto de autenticación.
Los nombres de los campos de entrada, como order_number.
Un pedido conocido y uno inexistente para probar.
Una respuesta JSON pequeña con información que se pueda mostrar al cliente.

Si aún no tienes un endpoint, sigue el ejemplo ejecutable de pedidos y vuelve aquí. Las URLs y los datos siguientes son ejemplos; sustituye el endpoint por tu URL real.

Playground envía solicitudes reales a tu endpoint. No simula tu sistema de pedidos. Activa también permite la ejecución en conversaciones reales; no es un interruptor exclusivo para Playground.

1. Agrega la definición

Abre Herramientas → Build → Tool calls → Definiciones y selecciona Nueva definición. Algunos nombres de navegación pueden aparecer en inglés.

Definiciones de herramientas en Build, interfaz en inglés

Campo	Valor para este ejemplo
Nombre	`get_order_status`
Método	`POST`
URL del endpoint	Tu URL, por ejemplo `https://api.example.com/visito/order-status`
Timeout	`8000` (milisegundos, u 8 segundos)
Descripción	Pega la descripción de abajo.
Esquema JSON de parámetros	Pega el esquema de abajo.
Auth	`Bearer`, si tu endpoint espera este tipo de token.
Secreto	El token del endpoint, sin el prefijo `Bearer` .
Activa	Desactivada mientras preparas y pruebas el endpoint; activada antes de la conversación del paso 3.
Solo lectura	Activada. Tu endpoint debe consultar datos sin modificarlos.
Playground	Activado para este ejemplo. Consulta el comportamiento de abajo.

La descripción explica cuándo usar la herramienta y cuándo pedir más información:

Consulta el estado actual de un pedido cuando el cliente pregunta dónde está
o si ya se envió. Pide el número de pedido si falta.
Usa el número que proporciona el cliente; nunca inventes uno.
Si found es false, pide al cliente que revise el número.
Esta herramienta no cancela, modifica ni reembolsa pedidos.

El esquema describe la información que debe recopilar el agente. Pega el esquema, no un pedido de ejemplo ni la solicitud HTTP completa:

{
  "type": "object",
  "properties": {
    "order_number": {
      "type": "string",
      "description": "El número de pedido proporcionado por el cliente, por ejemplo A-1003."
    }
  },
  "required": ["order_number"],
  "additionalProperties": false
}

Guarda la definición. Al editarla, deja Secreto vacío para conservar el valor guardado.

Entiende los tres interruptores

Activa pone la definición a disposición del agente. Las herramientas inactivas no están disponibles en conversaciones normales ni en Playground.
Solo lectura declara que el endpoint no modifica datos. No impone ese comportamiento en tu servidor.
Playground permite probar una herramienta que modifica datos. Las herramientas activas de solo lectura ya pueden usarse aunque este interruptor esté apagado. Apagarlo no deshabilita sus consultas en Playground.

Usa la credencial correcta

Este secreto autentica Visito → tu sistema. Una clave API de Visito autentica tu aplicación → Visito y solo es necesaria si administras o pruebas herramientas mediante la API. Con autenticación API key, escribe el Nombre del header exacto que espera tu endpoint, como X-API-Key, y su secreto. Con Bearer, Visito agrega Authorization: Bearer ... automáticamente. No incluyas credenciales en la descripción, el esquema ni el chat.

2. Comprueba el endpoint antes de conversar

Pide a tu desarrollador que envíe esta solicitud al endpoint con la autenticación configurada:

{
  "arguments": {
    "order_number": "A-1003"
  },
  "meta": {
    "tenantId": "YOUR_TEST_TENANT_ID",
    "source": "developer_test"
  }
}

En POST, el número está dentro de arguments, no en la raíz. Una respuesta adecuada es HTTP 200 con:

{
  "found": true,
  "order_number": "A-1003",
  "status": "out_for_delivery",
  "delivery_estimate": "today"
}

Una consulta correcta sin coincidencias también puede devolver HTTP 200:

{
  "found": false,
  "order_number": "A-9999"
}

La consulta funcionó, pero no encontró el pedido. Reserva los errores HTTP para solicitudes fallidas: entradas inválidas, fallos de autenticación o un servicio no disponible. Tu desarrollador también puede usar el endpoint de prueba de Visito con la definición inactiva. Así verifica la URL y las credenciales guardadas y genera un log. Esto no comprueba si el agente elige la herramienta o redacta una buena respuesta. El editor actual de Tool calls no tiene un formulario separado para probar el endpoint.

3. Prueba la experiencia en Playground

En tu espacio de pruebas, enciende Activa y guarda. Abre Agente → Playground y selecciona Nuevo chat. Estas conversaciones son ejemplos ilustrativos basados en la respuesta anterior. La redacción puede variar; compara los datos, la entrada de la herramienta y el resultado. Los registros de herramientas personalizadas pueden aparecer en inglés.

El cliente proporciona el número

Cliente: ¿Dónde está el pedido A-1003?

Actividad del operador: Running get order status...
Actividad del operador: Action completed: get order status

Asistente: El pedido A-1003 está en reparto, con entrega estimada para hoy.

Si el endpoint responde rápido, el estado de ejecución puede ser muy breve. En el nombre mostrado, los espacios sustituyen a los guiones bajos.

Falta el número de pedido

Cliente: ¿Ya enviaron mi pedido?
Asistente: ¿Cuál es tu número de pedido?
Cliente: A-1003

Actividad del operador: Action completed: get order status

Asistente: El pedido A-1003 está en reparto, con entrega estimada para hoy.

Comprueba que el agente pide el número antes de consultar. Si lo inventa, mejora la descripción y las instrucciones del agente; abre un chat nuevo y repite la prueba.

El pedido no existe

Cliente: ¿Dónde está el pedido A-9999?

Actividad del operador: Action completed: get order status

Asistente: No encontré el pedido A-9999. ¿Puedes revisar el número?

Action completed significa que la llamada HTTP funcionó. No confirma que el pedido exista, se haya enviado o esté entregado. Los datos devueltos determinan el resultado de negocio.

El sistema de pedidos no está disponible

Cliente: ¿Dónde está el pedido A-1003?

Actividad del operador: Action failed: get order status

Asistente: No pude consultar tu pedido en este momento. Inténtalo de nuevo en unos minutos.

El agente debe reconocer el fallo sin inventar un estado. Si necesitas seguimiento humano, configura y prueba una regla de escalamiento.

Estos registros son para operadores. El cliente recibe la respuesta del asistente, no el registro ni el JSON completo. En Conversaciones, el registro de éxito es el texto compacto Action completed.

4. Revisa lo que ocurrió

Abre Build → Tool calls → Logs de actividad, filtra por get_order_status y abre la fila correspondiente a la hora de tu prueba. Revisa el número enviado, endpoint, método, estado HTTP, respuesta, duración y errores. Los headers de autenticación configurados se ocultan; los cuerpos de solicitud y respuesta solo deben incluir datos necesarios.

Lo que observas	Qué revisar
No aparece actividad	Confirma el espacio de trabajo, Activa, una descripción clara y un chat nuevo. Si configuraste la herramienta por API, revisa también el alcance por propiedad.
El agente pide el número	Es lo esperado si falta. Proporciónalo y continúa.
HTTP `401` o `403`	Comprueba el secreto y el header de autenticación.
HTTP `400`	Verifica que el endpoint lea `arguments.order_number` en POST y valide la entrada.
Fallo de solicitud o timeout	Revisa el acceso desde Visito, la salud del endpoint y el tiempo de respuesta. Que funcione en tu navegador no garantiza que Visito pueda acceder.
Registro completado, respuesta incorrecta	Compara el JSON con la respuesta. Aclara estados ambiguos y elimina instrucciones contradictorias o conocimiento desactualizado.
Registro completado con `found: false`	La consulta funcionó; revisa el número y los datos del sistema.

Cada intento de herramienta consume un crédito, aparte de una respuesta de IA completada. Consulta el uso de créditos.

5. Úsala con clientes

Antes de activar la definición en el espacio de clientes, repite las pruebas de pedido conocido, número faltante, pedido inexistente y sistema no disponible. Tu backend debe comprobar qué pedidos puede consultar el solicitante; conocer un número no demuestra que sea su propietario. Sustituye los datos de ejemplo por tu consulta real, devuelve solo información apropiada para el cliente y revisa los primeros logs y respuestas. Para detener futuras llamadas, edita la definición y apaga Activa. Esto no revierte una solicitud en curso.

Adapta el patrón a disponibilidad

Para consultar existencias, llama a la herramienta check_stock y exige un sku. El endpoint podría devolver:

{
  "sku": "MUG-BLUE",
  "available": true,
  "quantity_available": 7
}

Prueba “¿Hay tazas azules?” y “¿Tienen el SKU MUG-BLUE?”. El agente debe obtener el SKU requerido o consultar un catálogo antes de comprobar existencias. Consultar disponibilidad no aparta inventario ni crea una reserva.

Crea el endpoint de ejemplo

Ejecuta un backend pequeño de pedidos y conéctalo a tu definición.

Primeros pasos

General

Agente

Buenas prácticas

Conexiones

Herramientas

Espacio de trabajo

Conecta tu agente a un sistema de pedidos

Elige qué conectar

Antes de empezar

1. Agrega la definición

Entiende los tres interruptores

Usa la credencial correcta

2. Comprueba el endpoint antes de conversar

3. Prueba la experiencia en Playground

El cliente proporciona el número

Falta el número de pedido

El pedido no existe

El sistema de pedidos no está disponible

4. Revisa lo que ocurrió

5. Úsala con clientes

Adapta el patrón a disponibilidad

Crea el endpoint de ejemplo

​Elige qué conectar

​Antes de empezar

​1. Agrega la definición

​Entiende los tres interruptores

​Usa la credencial correcta

​2. Comprueba el endpoint antes de conversar

​3. Prueba la experiencia en Playground

​El cliente proporciona el número

​Falta el número de pedido

​El pedido no existe

​El sistema de pedidos no está disponible

​4. Revisa lo que ocurrió

​5. Úsala con clientes

​Adapta el patrón a disponibilidad

Crea el endpoint de ejemplo

Elige qué conectar

Antes de empezar

1. Agrega la definición

Entiende los tres interruptores

Usa la credencial correcta

2. Comprueba el endpoint antes de conversar

3. Prueba la experiencia en Playground

El cliente proporciona el número

Falta el número de pedido

El pedido no existe

El sistema de pedidos no está disponible

4. Revisa lo que ocurrió

5. Úsala con clientes

Adapta el patrón a disponibilidad