Skip to main content
Una tool es una función que tu agente puede llamar en medio de la conversación para consultar o escribir en tus sistemas: buscar un pedido, cotizar, registrar un lead, confirmar disponibilidad. Tú expones un endpoint HTTPS; Ryvo lo llama con los datos que el modelo extrajo de la conversación y le devuelve la respuesta al agente para que la use en su siguiente frase. Funciona igual en el probador de chat y en las llamadas de voz.

​
Dar de alta una tool

En el Constructor, riel izquierdo, entra a Tools y haz clic en + (Nueva herramienta). El único tipo disponible hoy es Solicitud API.
Panel de Tools del Constructor

(1) Tools en el riel. (2) Nueva herramienta. A la derecha, el detalle de una tool: endpoint, autenticación, parámetros y tiempo límite.

El secreto de autenticación se cifra al guardar y no se vuelve a mostrar. Si lo pierdes, borra la tool y créala de nuevo. Las cabeceras Content-Type, Content-Length y Host no se pueden usar como cabecera de autenticación.
Modal Nueva tool

El modal de alta: tipo, nombre, autenticación, endpoint y parámetros.

​
La descripción de cada parámetro sí importa

El modelo recibe el nombre y la descripción de cada parámetro como parte del esquema de la función. Una descripción como «Número de pedido de 8 dígitos que el cliente dicta» produce mejores extracciones que dejarla vacía.
El campo «Cuándo debe usarla el agente» todavía no se guarda: el modelo decide cuándo llamar la tool conociendo únicamente su nombre y sus parámetros. Mientras tanto, explica en el prompt del agente cuándo y para qué usar cada tool, por su nombre exacto. Ejemplo: «Cuando el cliente pregunte por el estado de un pedido, pide el número y llama a buscar_pedido».

​
Publica para que el agente la vea

Crear la tool no la activa. Las tools se asignan a una versión del agente, así que tienes que Publicar después de crearla. El panel de Tools te enseña el estado de cada una: Puedes probarla sin publicar: el probador de chat y la prueba de voz del Constructor usan el borrador (la versión que estás editando), no la publicada.

​
La petición que recibe tu servidor

Cuando el modelo decide llamar la tool, Ryvo resuelve los parámetros y hace una petición a tu URL. GET y DELETE: los parámetros viajan como query string, sin cuerpo.
POST, PUT y PATCH: los parámetros viajan como JSON en el cuerpo.
Lo que sí llega: los parámetros que declaraste, con los valores que el modelo extrajo (o el cuerpo tal cual lo armó el modelo si la tool no tiene parámetros). Lo que no llega hoy: identificador de la llamada, del agente ni teléfono del llamante, ni firma HMAC. Si necesitas correlacionar con la conversación, pide al modelo que capture ese dato como parámetro.

​
Lo que Ryvo hace por su cuenta

  • Timeout de 8 segundos y un reintento (500 ms después) sólo si tu servidor respondió 5xx, hubo error de red o venció el timeout. Un 4xx no se reintenta.
  • Idempotencia: cada llamada del modelo lleva un identificador único. Si el mismo turno se repite (por ejemplo, tras un corte del audio), tu endpoint no se vuelve a ejecutar; el agente recibe el resultado registrado la primera vez.
  • Redirecciones: máximo 3, sólo al mismo origen y siempre HTTPS. Una redirección a otro dominio se corta para no llevarse tu secreto.
  • Tope de llamadas por turno según tu plan (4 en Pago por uso, 6 en Starter, 10 en Pro, 12 en Scale). Si el modelo intenta más, recibe tool_call_budget_exhausted.

​
Lo que debe responder tu servidor

Cualquier código 2xx. El cuerpo se entrega al modelo:
  • Si es JSON válido, como JSON.
  • Si no, como texto.
Responde corto y estructurado: el agente tiene que leerlo en voz alta o convertirlo en una frase. {"estado":"en camino","entrega":"jueves 2 de octubre"} funciona mejor que una página de datos. Hay un tope de bytes por respuesta según tu plan: 16 KB en Pago por uso, 32 KB en Starter, 64 KB en Pro y 128 KB en Scale y Enterprise. Si tu respuesta lo excede, el agente recibe el fragmento leído marcado como truncado:
Un 4xx o 5xx llega al modelo como error con el código HTTP y el cuerpo que enviaste. Si mandas un mensaje legible en el cuerpo ({"error":"No encontramos ese pedido"}), el agente puede decírselo al cliente.

​
Errores que puede ver el agente

​
Diferencias entre chat y voz

  • En voz, la ejecución corre en un hilo aparte para no trabar el audio, pero el agente no tiene nada que decir hasta que llega tu respuesta. Mantén tus tools por debajo de 2 o 3 segundos; el silencio se nota.
  • Los valores de variables dinámicas (por ejemplo, el teléfono del llamante) no se inyectan en tools durante llamadas de voz por ahora.

​
Tools nativas

Además de las tuyas, el agente puede traer dos tools que Ryvo opera:
  • search_kb: busca en tu base de conocimiento. Aparece sola cuando el agente tiene documentos en modo «Cuando haga falta». Más en Base de conocimiento.
  • agendar_cita: reserva en tu calendario. Aparece sola cuando conectas Cal.com en Configuración → Integraciones (o desde Calendario). Recibe start (fecha y hora ISO 8601 con zona horaria), name, phone, email y timeZone (por omisión America/Monterrey). Si el horario ya está tomado devuelve slot_unavailable con un mensaje que el agente puede decir.

​
Integraciones

Desde el plan Pro, el agente puede usar acciones de apps que ya usas (Google Calendar, Gmail, Outlook, Google Sheets, HubSpot, Salesforce, Pipedrive, Notion, Airtable, Slack y Calendly) sin que tengas que escribir un webhook. Ryvo las conecta por Composio, que guarda y renueva el acceso por ti.
  1. En Integraciones (menú principal) pulsa Conectar en la app. Se abre la pantalla de autorización de esa app; al terminar vuelves a Ryvo con la tarjeta en Conectada.
  2. En el constructor, Nueva tool → Integración: elige la app conectada y marca las acciones que quieres darle al agente (las recomendadas van primero y hay buscador). Cada acción se crea como una tool con sus parámetros ya definidos por la app; no se editan, sólo se borran.
  3. Publica. Igual que cualquier tool, el agente las ve cuando la versión publicada las declara.
Límites: hasta 10 acciones de integración por agente sumando todas las apps, y cada acción expone al modelo como mucho 24 parámetros (las requeridas siempre entran). Funciona igual en chat y en voz; en voz cuenta el tiempo de respuesta de la app, así que prefiere acciones concretas (crear un evento, buscar un contacto) a listados largos. Si desconectas una app, sus tools siguen en el agente pero fallan con integration_disconnected hasta que la vuelvas a conectar. Cal.com sigue en Configuración → Integraciones y no pasa por aquí.

​
Lo que todavía no está

En la pantalla verás rotulado Próximamente: probar una tool suelta, editarla sin borrarla, el mensaje de espera («Mientras se ejecuta»), tools de tipo Webhook (aviso al terminar la llamada). Hoy la única forma de cambiar una tool es borrarla y crearla de nuevo, y hay que volver a pegar el secreto.