💬 Bot do Telegram
O canal por onde você vai falar com seu agente é um bot do Telegram. Bot é uma conta automática — você não loga manualmente, é seu código que controla. A criação leva 2 minutos e o resultado é um token, que é a chave que dá ao seu programa permissão pra ler e enviar mensagens.
🎯 Como criar em 5 passos
- 1.No Telegram, abra conversa com @BotFather (o bot oficial pra criar outros bots).
- 2.Mande
/newbot. - 3.Escolha um nome de exibição (qualquer um) e um username terminado em
_bot. - 4.Copie o token que ele envia (parecido com
123456:ABC...). - 5.Mande
/startpro @userinfobot e copie seu próprio chat ID — você vai usar pra liberar só você.
💡 Dica prática
O token equivale à senha do bot. Se vazar, qualquer um controla seu agente. Trate como senha de banco: nunca commitar, nunca colar em chat público, e se vazou, peça novo no BotFather (/revoke).
✓ Fazer
- ✓Restringir por chat ID (só você fala)
- ✓Salvar token só no .env
- ✓Usar polling no dev, webhook em prod
✗ Evitar
- ✗Hardcoded do token no código
- ✗Bot público sem allowlist (qualquer um chama)
- ✗Compartilhar print do BotFather
🔑 Chave de modelo (LLM)
A chave do modelo é o que dá ao seu código permissão de chamar a IA. Sem ela, o agente não pensa. Você tem quatro caminhos e a melhor estratégia é usar mais de um.
🎯 Os 4 caminhos
- Anthropic direto: qualidade alta, preço médio. Pega chave em console.anthropic.com.
- OpenAI direto: qualidade alta, ecossistema maduro. platform.openai.com.
- OpenRouter: uma chave só, dezenas de modelos, inclui DeepSeek e modelos gratuitos. openrouter.ai.
- Ollama local: modelo rodando na sua máquina. Custo zero, mas precisa de GPU decente. ollama.ai.
📊 Faixa de custo (Maio 2026)
- ~$0,003/mil tokens input · DeepSeek e modelos gratuitos no OpenRouter
- ~$3/milhão tokens input · Claude Sonnet, GPT-4 família
- ~$15/milhão tokens input · Modelos premium (Claude Opus, GPT top)
- $0 · Ollama local com Llama 3.1, Qwen 2.5 ou Mistral
💡 Estratégia recomendada
Comece com OpenRouter — uma chave, vários modelos. Use DeepSeek ou Llama 3.1 8B pra tarefas simples (centavos por dia), troque pra Claude Sonnet pra raciocínio complexo. Em 2 minutos você muda só a string do modelo no .env e o resto continua igual.
📦 Bootstrap do projeto
Aqui você cria o esqueleto: Node 20+, TypeScript, package.json e tsconfig.json. Se isso já é familiar pra você, são 3 minutos. Se não é, leia com calma — esse é o terreno onde tudo o resto vai morar.
🎯 Sequência de comandos
- 1. Verifique o Node:
node -v(se for < 20, atualize via nvm). - 2. Crie o projeto:
mkdir agente && cd agente && npm init -y - 3. Adicione TypeScript e tsx (executor):
npm i -D typescript tsx @types/node - 4. Crie tsconfig com
npx tsc --inite ajuste target ES2022, module Node16. - 5. No package.json, adicione
"dev": "tsx watch src/index.ts"nos scripts.
💡 Por que tsx e não ts-node
tsx é mais rápido, lida com ES modules sem dor de cabeça, tem watch mode embutido. Vai te poupar 30 minutos de configuração que você gastaria com alternativas.
🔐 Variáveis de ambiente
Token do Telegram, chave do LLM, IDs autorizados — todos esses são segredos. Eles ficam num arquivo .env que você nunca commita. Em paralelo, você cria um .env.example com os nomes (sem valores) pra documentar quais variáveis existem.
📝 Estrutura mínima do .env
TELEGRAM_BOT_TOKEN=123456:ABC-seu-token-real
ALLOWED_CHAT_IDS=123456789
LLM_PROVIDER=openrouter
LLM_API_KEY=sk-or-v1-...
LLM_MODEL=anthropic/claude-3.5-sonnet
DATABASE_PATH=./data/agente.db
TIMEZONE=America/Sao_Paulo⚠️ Atenção
Antes do primeiro git add, confirme que o .gitignore tem a linha .env. Token vazado no GitHub é descoberto por bots em minutos e usado pra spam — vira problema seu.
📁 Estrutura de pastas
Convenção simples e clara: código vai em src/, dados em tempo real em data/, scripts utilitários em scripts/. Dentro de src, divide por domínio, não por tipo.
🌳 Layout sugerido
agente/
├── src/
│ ├── index.ts # ponto de entrada
│ ├── config.ts # carrega .env
│ ├── memory/ # camadas de memória
│ ├── llm/ # adapters de modelo
│ ├── tools/ # ferramentas (web, files, etc)
│ ├── telegram/ # bot e handlers
│ └── agent.ts # loop principal
├── scripts/ # migrations, seeds, utilitários
├── data/ # SQLite, logs (gitignored)
├── tests/
├── .env # SEGREDOS (gitignored)
├── .env.example # template, sem valores
├── .gitignore
├── package.json
└── tsconfig.json💡 Dica
Cada pasta dentro de src/ tem um index.ts que exporta o que é público. O resto fica privado. Isso cria uma fronteira clara entre "uso interno do módulo" e "API pro resto do projeto".
👋 Primeiro "olá agente"
Antes de construir loop, memória ou ferramentas, escreva um script de smoke test: ele só prova que o Telegram, o LLM e o seu código se conversam. Se isso roda, você está pronto pra escalar.
🎯 O que o smoke test faz
- 1. Lê o token e a chave do .env via dotenv.
- 2. Conecta no Telegram e escuta uma única mensagem.
- 3. Manda essa mensagem pro LLM com um system prompt fixo ("Responda em uma frase").
- 4. Pega a resposta e envia de volta no chat.
- 5. Encerra.
Se a resposta chega no seu Telegram, está tudo conectado. Se algo falha, você sabe exatamente em qual das 4 camadas (env, Telegram, LLM, código) corrigir.
🔍 Erros comuns nesse passo
- 401 do LLM: chave errada ou modelo que não existe pra essa chave.
- Bot não responde: token errado, ou você não mandou /start pro bot antes.
- "Cannot find module": esqueceu npm install depois de adicionar dependência.
- Resposta truncada: max_tokens muito baixo no payload do LLM.
✅ Resumo do módulo
Próximo módulo:
1.2 — Identidade e Memória (dar voz ao agente e fazer ele lembrar de você)