El video dura ocho minutos y cincuenta y dos segundos y termina con un agente contestando mensajes en un canal real. No es una demo sobre un mock: el agente queda conectado a un bot de Telegram, responde, y las conversaciones aparecen en el Inbox como cualquier otra.
Esta es la versión escrita, con lo que un video no alcanza a decir: qué decide cada campo, qué se cobra, y en qué punto exacto un agente deja de contestar y una persona toma la conversación.
Lo que vas a tener al final
- Un agente con nombre, objetivo y prompt, creado desde el dashboard.
- Un bot de Telegram conectado y activado, recibiendo y respondiendo.
- Tools declaradas: lo que el agente tiene permitido hacer contra tus sistemas.
- Una forma de probarlo sin escribirle a un cliente.
- Un Inbox donde ves las conversaciones y puedes entrar a responder tú.
Si nunca armaste uno y quieres el modelo mental primero —qué es un loop de agente, qué lo separa de un chatbot— parte por cómo crear un agente de IA y vuelve acá.
1. Crear el agente
En el dashboard: Agents → crear agente. El diálogo pide dos cosas y nada más.
Nombre. Lo vas a ver en las métricas, en el Inbox y en los logs. "Soporte" alcanza.
Objetivo. Una descripción en lenguaje natural de qué debe hacer. Esto se convierte en el primer borrador de su prompt, así que sirve escribirlo como se lo explicarías a alguien que entra a trabajar mañana: qué preguntas responde, con qué tono, y qué no le toca.
Los senders se conectan después. Un agente recién creado no está enganchado a ningún número ni a ningún bot, y esa separación es a propósito: el mismo agente puede atender varios senders, y un sender responde con un agente a la vez.
2. Configurarlo
Acá es donde el agente deja de ser un nombre. La pantalla del agente tiene el prompt y los interruptores que deciden cuándo se despierta.
| Campo | Qué decide | El detalle que importa |
|---|---|---|
| System prompt | Cómo responde y qué no hace nunca | Es el único lugar donde vive tu política. Si no lo escribes, no existe |
| Modelo | Qué motor razona | Con el proveedor zavu no necesitas traer tu propia API key |
| Ventana de contexto | Cuántos mensajes previos ve | Entre 1 y 50. Más contexto es más coherencia y más costo por respuesta |
| Canales que disparan | En qué canales contesta | Un agente que dispara en un canal que el sender no tiene responde en el playground y a nadie más |
| Tipos de mensaje | Texto, imagen, audio | Por defecto solo texto |
Dos frases del prompt valen más que todo lo demás: qué hace cuando no sabe y qué no debe prometer nunca. Un agente que inventa un plazo de entrega con total seguridad no es un problema del modelo, es una decisión de diseño que no se tomó.
3. Conectar Telegram
En Accounts conectas el bot: hablas con @BotFather en Telegram, mandas /newbot, y pegas el token que te devuelve. Zavu lo guarda cifrado, registra el webhook y desde ahí el bot recibe.
Tres cosas que conviene saber antes de que te sorprendan:
Conectar no es activar. Una cuenta recién conectada llega inactiva y todo envío sobre ella se rechaza hasta que la activas. La activación es la que cuenta como conexión de canal en tu plan.
Telegram identifica a la gente por un chat ID numérico, no por @usuario. Un bot no puede escribirle primero a alguien que nunca le abrió conversación. Le escribes tú una vez al bot, y su respuesta trae el ID.
Telegram no tiene ventana de 24 horas ni plantillas que aprobar. Por eso es el canal correcto para el primer agente: en dos minutos tienes un canal real donde probar. WhatsApp es el canal donde después vive el volumen, y tiene verificación de negocio y la ventana de 24 horas; el mismo agente sirve para los dos, cambia el sender. Si ese es tu destino final, la guía de WhatsApp cubre lo que agrega.
4. Las tools
Un modelo sin tools puede hablar de tu política de devoluciones. Un modelo con una tool consultar_pedido puede decirle a un cliente dónde está su paquete. Casi todo el valor de un agente de soporte está ahí.
Una tool son cuatro cosas: un nombre, una descripción —que es lo que el modelo lee para decidir si la llama—, los parámetros en JSON Schema, y una URL HTTPS tuya que recibe la llamada.
terminalcurl -X POST https://api.zavu.dev/v1/agents/AGENT_ID/tools \ -H "Authorization: Bearer $ZAVU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "consultar_pedido", "description": "Devuelve el estado y la fecha estimada de un pedido por su número.", "webhookUrl": "https://api.tutienda.com/zavu/pedidos", "parameters": { "type": "object", "properties": { "numero_pedido": { "type": "string", "description": "Número del pedido, ej. ORD-12345" } }, "required": ["numero_pedido"] } }'
La respuesta trae un webhookSecret una sola vez. Zavu firma cada llamada a tu endpoint con él, en la cabecera X-Zavu-Signature: es un HMAC-SHA256 del cuerpo. Verifícalo antes de confiar en la llamada, o cualquiera que adivine tu URL puede pedirle datos de pedidos a tu backend.
La descripción es el prompt de la tool. "Consulta pedidos" hace que el modelo la llame cuando no corresponde; "Devuelve el estado y la fecha estimada de un pedido por su número" le dice cuándo sí y cuándo no.
5. Probarlo antes de que lo haga un cliente
Hay dos maneras y hacen cosas distintas.
El Playground corre el agente y te muestra la respuesta sin mandarle nada a nadie. Es donde se itera el prompt. Un detalle que importa: por defecto no ejecuta las tools, porque ejecutarlas tiene efectos reales, así que el modelo dice qué llamaría y ahí se detiene. Hay un interruptor para ejecutarlas de verdad cuando quieres probar el loop completo. Una respuesta que suena a "ya consulté tu pedido" con las tools apagadas es una respuesta inventada, y esa confusión ha costado más de un debug.
El Sandbox te deja escribirle al agente desde WhatsApp o SMS usando los números de Zavu, desde el teléfono de alguien del equipo. Es el mismo camino que recorre un mensaje real.
Y desde la API, para meterlo en CI:
terminalcurl -X POST https://api.zavu.dev/v1/agents/AGENT_ID/test \ -H "Authorization: Bearer $ZAVU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "¿Dónde está mi pedido ORD-12345?", "executeTools": true }'
La respuesta trae warnings: cosas que son ciertas de ese agente y que una prueba en seco no puede demostrar. Por ejemplo, que el agente está deshabilitado, o que dispara en canales que su sender no tiene. Vale la pena leerlas antes de dar el setup por bueno.
6. Conversaciones reales, y cuándo se calla
Con el bot activo, cada conversación entra al Inbox con su historial completo. Ahí ves lo que el agente respondió y puedes responder tú.
El traspaso a una persona funciona así, exactamente: cuando se abre un handoff, el agente deja de contestar. No responde el siguiente mensaje del contacto, ni el que venga después. La conversación queda esperando en el Inbox. Cuando alguien del equipo responde, el hilo vuelve a manos del agente para lo que siga, así el silencio no es permanente.
Vale la pena decirlo con precisión porque la versión anterior de esto no lo hacía: el agente marcaba un estado, nadie se enteraba, y el bot seguía hablando encima de la persona a la que acababa de prometerle un humano.
Qué se cobra y qué no
- Telegram, WhatsApp, Instagram y Messenger comparten una cuota mensual de mensajes, y cuenta en las dos direcciones: los que recibes gastan igual que los que envías.
- Zavu no cobra entrega por Telegram. Lo que se paga ahí es la conexión activa del canal, por mes, según tu plan.
- El modelo se cobra por tokens. La pantalla de Agents muestra ejecuciones, tool calls, tokens y costo por agente; un prompt con ventana de contexto de 50 mensajes se nota en esa columna.
- SMS, voz y email se cobran aparte, por mensaje o por minuto.
Cuándo esto no alcanza
Esta ruta —dashboard, prompt, tools, Telegram— es la correcta para un agente de soporte que responde preguntas y consulta datos. Deja de alcanzar cuando el agente necesita lógica que no cabe en un webhook por tool: reglas que dependen de varios sistemas, colas, reintentos, estado entre conversaciones.
Ahí el agente se declara en código y se deploya como una función, con defineAgent y defineTool, y sigue apareciendo en las mismas pantallas. Es el mismo agente, escrito distinto. Y si prefieres que lo escriba tu coding agent, eso ya es un flujo completo.
Lo que no cambia en ninguna de las dos rutas: un agente vale lo que valen sus tools, y solo sirve en el canal donde tus clientes ya están escribiendo.