O vídeo tem oito minutos e cinquenta e dois segundos e termina com um agente respondendo mensagens em um canal real. Não é uma demo em cima de um mock: o agente fica ligado a um bot do Telegram, responde, e as conversas aparecem no Inbox como qualquer outra.
Esta é a versão escrita, com o que um vídeo não consegue parar para dizer: o que cada campo decide, o que é cobrado, e o ponto exato em que um agente para de responder e uma pessoa assume a conversa. A narração é em espanhol; os passos abaixo estão inteiros aqui.
O que você tem no final
- Um agente com nome, objetivo e prompt, criado pelo dashboard.
- Um bot do Telegram conectado e ativado, recebendo e respondendo.
- Tools declaradas: o que o agente tem permissão de fazer contra os seus sistemas.
- Uma forma de testar sem escrever para um cliente.
- Um Inbox onde você lê as conversas e pode entrar para responder.
Se você nunca montou um e quer o modelo mental primeiro — o que é um loop de agente, o que o separa de um chatbot — comece por como criar um agente de IA e volte aqui.
1. Criar o agente
No dashboard: Agents → criar agente. O diálogo pede duas coisas e mais nada.
Nome. Você vai vê-lo nas métricas, no Inbox e nos logs. "Suporte" basta.
Objetivo. Uma descrição em linguagem natural do que ele deve fazer. Isso vira o primeiro rascunho do prompt, então vale escrever como você explicaria o trabalho para alguém que começa amanhã: quais perguntas responde, em que tom, e o que não é da conta dele.
Os senders são conectados depois. Um agente recém-criado não está ligado a nenhum número nem a nenhum bot, e essa separação é proposital: o mesmo agente pode atender vários senders, e um sender responde com um agente por vez.
2. Configurar
Aqui o agente deixa de ser um nome. A tela do agente tem o prompt e as chaves que decidem quando ele acorda.
| Campo | O que decide | O detalhe que importa |
|---|---|---|
| System prompt | Como responde e o que nunca faz | É o único lugar onde a sua política vive. Se você não escrever, ela não existe |
| Modelo | Qual motor raciocina | Com o provider zavu você não precisa trazer sua própria API key |
| Janela de contexto | Quantas mensagens anteriores ele vê | Entre 1 e 50. Mais contexto é mais coerência e mais custo por resposta |
| Canais que disparam | Onde ele responde | Um agente que dispara em um canal que o sender não tem responde no playground e em mais lugar nenhum |
| Tipos de mensagem | Texto, imagem, áudio | Só texto por padrão |
Duas frases do prompt valem mais que todo o resto: o que ele faz quando não sabe e o que nunca deve prometer. Um agente que inventa um prazo de entrega com toda a confiança não é problema do modelo. É uma decisão de design que ninguém tomou.
3. Conectar o Telegram
Em Accounts você conecta o bot: fala com o @BotFather no Telegram, manda /newbot e cola o token que ele devolve. A Zavu guarda cifrado, registra o webhook, e o bot passa a receber.
Três coisas que vale saber antes de elas te surpreenderem:
Conectar não é ativar. Uma conta recém-conectada chega inativa e todo envio nela é recusado até você ligá-la. A ativação é o que conta como conexão de canal no seu plano.
O Telegram identifica as pessoas por um chat ID numérico, não por @usuário. Um bot não pode escrever primeiro para quem nunca abriu conversa com ele. Você escreve uma vez para o bot, e a resposta traz o ID.
O Telegram não tem janela de 24 horas nem templates para aprovar. É por isso que ele é o canal certo para o primeiro agente: dois minutos e você tem um canal real para testar. O WhatsApp é onde o volume acaba vivendo, e traz verificação de negócio e a janela de 24 horas; o mesmo agente serve nos dois, muda o sender. Se esse é o destino, o guia de WhatsApp cobre o que ele acrescenta.
4. As tools
Um modelo sem tools consegue falar sobre a sua política de devoluções. Um modelo com uma tool consultar_pedido consegue dizer a um cliente onde está a encomenda. Quase todo o valor de um agente de suporte está aí.
Uma tool são quatro coisas: um nome, uma descrição — que é o que o modelo lê para decidir se a chama —, os parâmetros em JSON Schema, e uma URL HTTPS sua que recebe a chamada.
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": "Retorna o status e a data estimada de um pedido pelo número.", "webhookUrl": "https://api.sualoja.com/zavu/pedidos", "parameters": { "type": "object", "properties": { "numero_pedido": { "type": "string", "description": "Número do pedido, ex. ORD-12345" } }, "required": ["numero_pedido"] } }'
A resposta traz um webhookSecret uma única vez. A Zavu assina cada chamada ao seu endpoint com ele, no header X-Zavu-Signature: um HMAC-SHA256 do corpo. Verifique antes de confiar na chamada, ou qualquer um que adivinhe a sua URL pode pedir dados de pedidos ao seu backend.
A descrição é o prompt da tool. "Consulta pedidos" faz o modelo chamá-la quando não deveria; "Retorna o status e a data estimada de um pedido pelo número" diz a ele quando sim e quando não.
5. Testar antes que um cliente teste
Há dois caminhos e eles fazem coisas diferentes.
O Playground roda o agente e mostra a resposta sem mandar nada para ninguém. É onde o prompt é iterado. Um detalhe que importa: por padrão ele não executa as tools, porque executá-las tem efeitos reais, então o modelo diz qual chamaria e para por aí. Existe uma chave para rodá-las de verdade quando você quiser exercitar o loop inteiro. Uma resposta que soa como "já consultei seu pedido" com as tools desligadas é uma resposta inventada, e essa confusão já custou mais de uma sessão de debug.
O Sandbox deixa você escrever para o agente por WhatsApp ou SMS a partir dos números da própria Zavu, do telefone de alguém do time. É o mesmo caminho que uma mensagem real percorre.
E pela API, para colocar no 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": "Onde está meu pedido ORD-12345?", "executeTools": true }'
A resposta traz warnings: coisas que são verdade sobre esse agente e que um teste a seco não consegue provar. Que o agente está desabilitado, por exemplo, ou que dispara em canais que o sender dele não tem. Leia antes de dar o setup por pronto.
6. Conversas reais, e quando ele se cala
Com o bot no ar, cada conversa cai no Inbox com o histórico completo. Você vê o que o agente respondeu e pode responder você mesmo.
A passagem para uma pessoa funciona exatamente assim: quando um handoff abre, o agente para de responder. Nem a próxima mensagem do contato, nem a seguinte. A conversa fica esperando no Inbox. Quando alguém do time responde, a thread volta para o agente no que vier depois, então o silêncio não é permanente.
Vale dizer com precisão, porque a versão anterior disso não fazia: o agente marcava um status, ninguém era avisado, e o bot continuava falando por cima da pessoa a quem acabara de prometer um humano.
O que é cobrado e o que não é
- Telegram, WhatsApp, Instagram e Messenger compartilham uma cota mensal de mensagens, e ela conta nas duas direções: o que você recebe gasta igual ao que você envia.
- A Zavu não cobra entrega no Telegram. O que se paga ali é a conexão ativa do canal, por mês, conforme o seu plano.
- O modelo é cobrado por token. A tela de Agents mostra execuções, tool calls, tokens e custo por agente; uma janela de contexto de 50 mensagens aparece nessa coluna.
- SMS, voz e email são cobrados à parte, por mensagem ou por minuto.
Quando isso deixa de bastar
Esta rota — dashboard, prompt, tools, Telegram — é a certa para um agente de suporte que responde perguntas e consulta dados. Ela deixa de bastar quando o agente precisa de lógica que não cabe em um webhook por tool: regras que atravessam vários sistemas, filas, retries, estado entre conversas.
Aí o agente é declarado em código e sobe como uma função, com defineAgent e defineTool, e continua aparecendo nas mesmas telas. O mesmo agente, escrito de outro jeito. E se você prefere que o seu coding agent escreva, isso já é um fluxo inteiro.
O que não muda em nenhuma das rotas: um agente vale o que valem as tools dele, e só funciona no canal onde os seus clientes já estão digitando.