Caça-Golpes
Agente de IA no Telegram que analisa mensagens e links suspeitos com dados reais de ameaças
- Papel
- Projeto independente · AI Engineering
- Situação
- Python · Gemini API · VirusTotal API · Telegram Bot API · 41 testes
Um agente de IA que recebe uma mensagem suspeita no Telegram e responde, em linguagem simples, se há sinais de golpe. Construí em Python puro um pipeline com duas chamadas de LLM, consulta a uma API de inteligência de ameaças e guardrails contra alucinação e prompt injection.
Tecnologias
Python
Só a biblioteca padrão (urllib, json, re, dataclasses). Orquestração, chamadas HTTP e testes, sem nenhuma dependência externa.
Gemini API
Dois papéis: um classificador leve (gemini-3.1-flash-lite, temperatura 0, saída em JSON) e o agente de análise (gemini-3.5-flash). O modelo leve também é o reserva quando o principal fica indisponível.
VirusTotal API v3
Reputação de cada link: quantos mecanismos de segurança o marcaram como malicioso ou suspeito. Link nunca analisado, chave inválida e limite de consultas viram respostas claras.
Telegram Bot API
A interface com o usuário. Long polling, sem servidor público; respostas longas são divididas no limite de tamanho do Telegram.
Prompt engineering
System prompt com formato de resposta fixo (veredito, motivos, recomendação), regras para citar só os dados recebidos e o texto do usuário delimitado por marcas.
unittest
41 testes com clientes falsos de Gemini, VirusTotal e Telegram, que rodam sem internet e sem gastar cota de API.
O problema
Golpes por SMS e WhatsApp funcionam porque chegam com urgência e parecem legítimos. Quem recebe nem sempre sabe avaliar um link ou uma mensagem antes de clicar. Eu queria uma ferramenta que respondesse no mesmo lugar onde a dúvida aparece: no chat.
Arquitetura
1. Classificação: um modelo leve, com saída em JSON, separa o que é segurança digital, saudação ou outro assunto. Fora do tema, o bot recusa com educação e nem chama o agente. 2. Coleta de evidências: o código extrai até 3 links da mensagem e consulta o VirusTotal antes de qualquer chamada ao agente. 3. Raciocínio: o agente recebe a mensagem delimitada e o resultado do VirusTotal como bloco de dados do sistema, e combina os sinais do texto (urgência, pedido de senha, remetente falso) com a reputação dos links. 4. Resposta: veredito, motivos e uma recomendação prática, em texto curto para ler no celular. Cada conversa guarda um histórico curto para perguntas de acompanhamento.
Do n8n para Python
A primeira versão era um fluxo no n8n em que o agente tinha o VirusTotal como ferramenta e decidia sozinho quando usá-la. Em alguns casos a consulta falhava sem que eu percebesse, e o veredito saía sem dado real. Na reimplementação, a etapa que precisa ser garantida saiu das mãos do modelo: o código sempre consulta o VirusTotal e o modelo só interpreta o resultado.
Guardrails e confiabilidade
• Grounding: o modelo só pode citar os números que recebeu e nunca chama um link de "seguro"; sem sinalizações, ele diz que isso não garante nada. • Prompt injection: o texto do usuário vai entre marcas e é tratado como conteúdo a analisar, nunca como instrução. Se alguém tenta fechar a marca, ela é removida. • Resiliência: erros 429, 500 e 503 do Gemini geram novas tentativas com espera crescente e, se o modelo principal continuar fora, o reserva responde. • Falha segura: se o classificador falhar, a mensagem segue para a análise; se o agente falhar, o usuário recebe uma orientação segura em vez de um erro. • Segredos: chaves de API e o token do Telegram são removidos de URLs antes de qualquer log ou mensagem de erro. • Privacidade: o bot avisa que os links consultados passam a fazer parte da base do VirusTotal.
Qualidade e testes
Os clientes de Gemini, VirusTotal e Telegram recebem a função de requisição como parâmetro, então os testes trocam a rede por clientes falsos. São 41 testes que cobrem extração de links, tratamento de erros das APIs, novas tentativas, modelo reserva, delimitação contra injection, memória e um ciclo completo do loop principal. Há também um modo terminal para testar as chaves sem o Telegram.
Limitações e próximos passos
Ainda não analisa imagens (prints e QR codes), a memória das conversas fica só em RAM e o bot roda localmente. Próximos passos: leitura de QR code e deploy. É um assistente educativo e não substitui ferramentas profissionais de análise de ameaças.
ProgramAuto
Próximo projeto