Construir agentes de IA que realmente funcionam

Um agente de IA é um LLM com a habilidade de tomar ações. Em vez de apenas gerar texto, ele pode chamar APIs, consultar bancos de dados, enviar mensagens, disparar fluxos de trabalho e tomar decisões em loop. A promessa é automação: um sistema que lida com tarefas sem supervisão humana constante.

A realidade é mais matizada. Agentes funcionam brilhantemente para tarefas bem delimitadas com fronteiras claras. Eles desmoronam espetacularmente quando recebem objetivos vagos, acesso irrestrito a ferramentas e nenhuma barreira. A diferença entre um agente de demo e um de produção não é o LLM — é tudo que cerca o LLM.

O que um agente realmente é

Tire o hype e um agente tem quatro componentes:

O LLM recebe entrada (mensagem do usuário, gatilho agendado, evento). Ele decide quais ferramentas chamar. As chama via servidores MCP. Recebe resultados. Decide o que fazer em seguida. Esse loop continua até a tarefa terminar ou o agente decidir parar.

Simples na teoria. O diabo está em cada detalhe.

Construir um agente no Zubnet

Na plataforma, criar um agente envolve quatro passos. Cada um tem decisões que vão determinar se seu agente funciona confiavelmente ou vira uma fonte de ligações às 3 da manhã.

1. Criar o agente

Dê a ele um nome, escolha um modelo e escreva um prompt de sistema.

O modelo importa mais do que você pensa. Para agentes que precisam chamar ferramentas confiavelmente, use um modelo forte em raciocínio. Claude Sonnet 4, GPT-4.1 ou Gemini 2.5 Pro. Modelos menores economizam dinheiro mas tomam piores decisões de chamada de ferramentas, e uma chamada ruim num agente não é só uma resposta errada — é uma ação errada.

O prompt de sistema é a constituição do seu agente. Seja explícito sobre:

• O que o agente deve fazer (e o que nunca deve fazer)
• Quando usar cada ferramenta e quando pulá-las
• Como lidar com erros e ambiguidade
• Quando pedir esclarecimento ao usuário vs. tomar uma decisão
• Que tom usar nas mensagens

2. Conectar um canal

Canais são como os agentes se comunicam com o mundo. No Zubnet, você pode conectar:

• Telegram — cole seu token de bot do @BotFather
• Discord — cole seu token de bot do Discord Developer Portal
• Webhooks — qualquer endpoint HTTP que possa enviar/receber JSON

O canal determina onde o agente vive. Um agente bot do Telegram responde em chats do Telegram. Um agente bot do Discord vive no seu servidor Discord. Um agente webhook responde a chamadas de API.

Escolha um canal para começar. Não tente construir um agente multi-canal no primeiro dia. Faça ele funcionar confiavelmente em uma plataforma primeiro.

3. Adicionar ferramentas (servidores MCP)

Ferramentas são o que faz os agentes serem mais que chatbots. No Zubnet, as ferramentas são fornecidas por servidores MCP (Model Context Protocol). Temos 117 deles. Alguns exemplos:

• GitHub — pesquisar repos, criar issues, ler arquivos, listar PRs
• PostgreSQL / MySQL — consultar bancos de dados (somente leitura se você for esperto)
• Brave Search — pesquisar na web
• Filesystem — ler e escrever arquivos
• Slack — enviar mensagens, ler canais

Ative os servidores de que precisar, configure suas credenciais (chaves de API, URLs de BD), e o agente pode usá-los.

4. Configurar gatilhos

Gatilhos determinam quando o agente é ativado:

• Mensagem do usuário — responde quando alguém escreve para o bot (padrão para agentes de chat)
• Agendamento cron — roda em horários fixos (ex., “todo dia às 9 da manhã”)
• Evento — dispara quando algo específico acontece (payload de webhook corresponde a um padrão)

Agentes disparados por cron são ótimos para tarefas recorrentes: resumos diários de standup, relatórios analíticos semanais, checks de monitoramento. Agentes disparados por eventos lidam com fluxos reativos: novo issue do GitHub → classificar e etiquetar, novo ticket de suporte → rascunhar resposta.

As partes difíceis

Construir o agente leva 20 minutos. Deixá-lo confiável leva semanas. Aqui é onde agentes de produção realmente falham:

Tratamento de erros: quando o LLM alucina uma chamada de ferramenta

LLMs às vezes chamam ferramentas com parâmetros incorretos, chamam ferramentas que não existem ou chamam a ferramenta certa no contexto errado. Seu agente precisa lidar com tudo isso de forma graciosa.

No Zubnet, chamadas de ferramenta que falharam retornam mensagens de erro para o LLM, que então pode decidir o que fazer. Mas você precisa dizer a ele o que fazer no prompt de sistema:

If a tool call fails:
1. Do NOT retry the same call with the same parameters
2. Analyze the error message
3. If it is a permission error, tell the user you cannot do that
4. If it is a rate limit, wait and try once more
5. If it is an unknown error, summarize what happened and ask for help
6. Never retry more than twice total

Sem essas instruções, agentes ficam presos em loops de retry, queimando tokens e tempo na mesma chamada que falha repetidamente.

Limites de taxa: tampas de frequência

Um agente conectado a um servidor Discord movimentado com 500 usuários ativos pode receber centenas de mensagens por minuto. Sem limitação de taxa, ele vai:

• Esgotar seu orçamento de tokens de API em horas
• Bater em limites de taxa do provedor e começar a retornar erros
• Gerar tantas respostas que o canal fica inutilizável

Configure tampas de frequência. No Zubnet, você pode configurar:

• Máx de respostas por minuto (por canal)
• Máx de tokens por hora (controle de orçamento)
• Período de cooldown entre respostas ao mesmo usuário
• Limite de profundidade de fila (descartar mensagens quando atrasa muito)

Permissões: restringir o que os agentes podem fazer

Essa é a que vai te salvar de desastres. Agentes devem ter as permissões mínimas necessárias para o trabalho.

• Ferramentas de BD: somente leitura a menos que escritas sejam especificamente necessárias
• Ferramentas GitHub: ler + criar issues, mas não fechar/merge/deletar
• Ferramentas filesystem: diretórios específicos apenas, nunca /
• Ferramentas de mensagem: canais específicos apenas, nunca DMs para executivos

Pense assim: qual é a pior coisa que esse agente poderia fazer com as ferramentas que tem? Se a resposta te deixa nervoso, reduza as permissões.

Degradação graciosa

Quando uma ferramenta está fora do ar, o agente não deveria falhar. Ele deveria reconhecer a limitação e fazer o que puder sem aquela ferramenta. Inclua isso no seu prompt de sistema:

If a tool is unavailable or returning errors:
- Acknowledge it to the user: "I cannot access GitHub right now"
- Do what you can without that tool
- Never make up data to compensate for a missing tool
- Suggest the user try again later

Exemplos reais

Exemplo 1: bot de suporte

Um bot do Telegram que responde perguntas de clientes usando sua base de conhecimento.

• Modelo: Claude Sonnet 4 (forte em seguir instruções)
• Ferramentas: Brave Search (para docs), PostgreSQL (somente leitura, para buscas de conta)
• Canal: Telegram
• Gatilho: mensagem do usuário
• Limite de taxa: 30 respostas/min, cooldown de 2s por usuário

O prompt de sistema foca em: responder a partir dos docs primeiro, escalar para humano se não tiver certeza, nunca compartilhar dados de outros clientes, nunca fazer promessas sobre recursos ou prazos.

Exemplo 2: agente de resumo diário

Um bot do Discord que publica um resumo matutino do que aconteceu durante a noite.

• Modelo: GPT-4.1 (bom para resumos estruturados)
• Ferramentas: GitHub (ler PRs e issues), Slack (ler canais)
• Canal: Discord (canal #daily-summary)
• Gatilho: cron, todo dia útil às 9:00 AM
• Limite de taxa: 1 mensagem por disparo (só dispara uma vez)

O prompt de sistema foca em: resumir PRs com merge, issues abertos/fechados e discussões-chave do Slack. Mantenha abaixo de 500 palavras. Use bullet points. Marque membros relevantes do time.

Exemplo 3: monitor de conteúdo

Um agente que fica de olho em eventos específicos e alerta o time.

• Modelo: Gemini 2.5 Pro (rápido, bom em classificação)
• Ferramentas: Brave Search (monitorar menções), Slack (enviar alertas)
• Canal: webhook (disparado por serviço de monitoramento)
• Gatilho: evento (webhook de entrada com resultados de busca)
• Limite de taxa: 10 alertas/hora (prevenir fadiga de alertas)

O prompt de sistema foca em: classificar menções como positivas/negativas/neutras, só alertar em negativas ou críticas, incluir URL fonte e resumo de uma frase.

Testes: comece pequeno

Agentes do Zubnet têm dois modos:

• Modo rápido — configuração simplificada, bom para testes. Configuração limitada de ferramentas, gatilhos básicos. Use para validar que seu conceito de agente funciona.
• Modo avançado — configuração completa, pronto para produção. Prompts de sistema detalhados, limites de taxa granulares, controles de permissão, múltiplos gatilhos.

Sempre comece no modo rápido. Faça o comportamento básico funcionar bem. Depois graduate para o modo avançado e adicione as barreiras.

A verdade inconveniente sobre agentes

Agentes não são mágica. São LLMs em loop com acesso a ferramentas. Eles cometem erros. Às vezes vão fazer a coisa errada. A pergunta não é “meu agente vai cometer um erro?” — é “o que acontece quando ele cometer?”

Agentes que funcionam em produção são os que têm:

• Escopo apertado (“faça bem essa única coisa”)
• Fronteiras explícitas (“nunca faça essas coisas”)
• Permissões limitadas (menor privilégio, sempre)
• Limites de taxa e tampas de orçamento (prevenir custos descontrolados)
• Rotas de escalação humana (“na dúvida, pergunte a um humano”)
• Monitoramento e logs (pra saber o que aconteceu)

---

Agentes no Zubnet estão disponíveis para todos os usuários. Comece com um bot simples do Telegram ou Discord, acerte, depois expanda. A infra lida com as partes difíceis — você foca no prompt de sistema, nas ferramentas e nas barreiras.

Pronto para construir? Crie seu primeiro agente em zubnet.com