---
title: Como criar um agente de suporte com IA, passo a passo
description: Nove minutos de vídeo e a versão escrita: criar o agente, conectar ao Telegram, dar tools, testar sem incomodar ninguém e vê-lo responder no Inbox.
date: 2026-09-22
author: Joel Fereira
locale: pt
source: https://www.zavu.dev/pt/blog/agente-de-soporte-con-ia
tags: AI Agents, Telegram, Suporte, Tutorial
video: https://www.youtube.com/watch?v=oZVma3YRJ1U
---

# Como criar um agente de suporte com IA, passo a passo

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](/pt/blog/how-to-build-an-ai-agent) 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](https://t.me/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](/pt/blog/como-crear-chatbot-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.

```bash
curl -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:

```bash
curl -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](/pt/blog/build-ai-agents-with-your-coding-agent).

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.