> ## Documentation Index > Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt > Use this file to discover all available pages before exploring further. # Conecta tu agente a un sistema de pedidos > Crea tu primera herramienta personalizada, conecta una consulta de pedidos y prueba la experiencia del cliente en Playground. 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](/es/api-docs/guides/order-status-tool) 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: ```text theme={null} 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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "found": true, "order_number": "A-1003", "status": "out_for_delivery", "delivery_estimate": "today" } ``` Una consulta correcta sin coincidencias también puede devolver HTTP `200`: ```json theme={null} { "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](/es/api-docs/guides/order-status-tool#prueba-la-definicion-guardada) 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 ```text theme={null} 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 ```text theme={null} 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 ```text theme={null} 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 ```text theme={null} 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](/es/product-guides/ai-agent/ai-escalations). 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](/es/product-guides/product/usage-billing). ## 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: ```json theme={null} { "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. Ejecuta un backend pequeño de pedidos y conéctalo a tu definición.