🛠️ Montando seu Jarvis de bolso (projeto)
Hora de juntar tudo. Neste modulo voce sai do "entendi a teoria" para o "esta funcionando no meu celular": um bot de Telegram pessoal, com cerebro, memoria, alma (soul), uma skill util, voz e um heartbeat que te manda o resumo do dia as 7h. Cinco passos curtos, cada um testavel antes do proximo. Sem app de loja, sem servidor exposto, sem mistura de chaves.
🗺️ Visao do projeto
Tudo que voce viu nas trilhas anteriores converge aqui em uma frase: vamos montar um bot de Telegram pessoal que conversa com voce, lembra de quem voce e, executa uma rotina util e ainda fala — acessivel de qualquer celular, sem instalar app de loja. O Telegram ja roda no seu telefone; ele vira a porta de entrada. O cerebro (o modelo de IA) e a memoria rodam num computador seu (em casa) ou na nuvem. O celular e so o canal.
A regra de ouro do projeto e brick-by-brick (tijolo por tijolo): voce constroi UM pedaco, testa que ele funciona, e so entao parte para o proximo. Nada de montar tudo de uma vez e tentar descobrir o que quebrou. Sao cinco passos, e cada um deixa o seu Jarvis um pouco mais vivo.
O celular nunca segura o cerebro — ele so conversa, pelo Telegram, com o agente que vive no seu PC ou na nuvem. Cada peca azul-ciano e um dos cinco passos: voce liga uma de cada vez.
Novo aqui? Um bot e um programa que conversa por um app de mensagens (aqui, o Telegram) em vez de uma tela propria. Agente e o nosso Jarvis: o programa que recebe sua mensagem, pensa com o modelo de IA e responde — eventualmente usando ferramentas. Heartbeat ("batimento") e uma tarefa agendada que faz o agente agir sozinho num horario, sem voce pedir.
🧰 O que voce vai precisar (1 vez)
- •Um computador seu (Windows, Mac ou Linux) com Node.js ou Python instalado — onde o agente vai rodar.
- •A conta de Telegram que voce ja usa no celular.
- •Uma chave de modelo (nuvem: OpenRouter/Anthropic) ou o Ollama instalado para rodar local — escolha no Passo 2.
- •~40 minutos e disposicao para testar cada tijolo.
Conceitos-chave
A porta por onde voce fala com o Jarvis — aqui, o Telegram.
Construir e testar um pedaco de cada vez, nunca tudo junto.
"O Telegram ja e mobile" — nada de publicar app nativo.
O cerebro mora no PC/nuvem; o telefone so conversa.
🤖 Passo 1: o bot
O primeiro tijolo e nascer o bot. No Telegram existe um robo oficial chamado @BotFather que cria outros bots para voce. Voce conversa com ele, recebe um token (uma senha longa que identifica o seu bot) e pronto — o canal existe. Em seguida voce coloca a primeira trava de seguranca: a whitelist (lista de permitidos), para que so voce seja atendido.
Fale com o @BotFather
No Telegram, busque @BotFather, abra a conversa e envie /newbot. Ele pergunta o nome e o usuario (precisa terminar em bot, ex.: meu_jarvis_bot).
Guarde o token
Ele responde com algo como 7891234:AAF...xYz. Esse e o token — trate como senha. Ele vai morar num arquivo .env, nunca no codigo nem em print publico.
Descubra o SEU user ID
Fale com @userinfobot: ele responde o seu numero de usuario (ex.: 123456789). E esse numero que entra na whitelist.
.env
Objetivo: guardar o token e a whitelist fora do codigo. Crie um arquivo chamado .env na pasta do projeto e cole o bloco abaixo, trocando os pedacos entre < > pelos seus valores.
# .env (NUNCA suba este arquivo pro GitHub)
TELEGRAM_BOT_TOKEN=<cole-seu-token-do-BotFather>
TELEGRAM_ALLOWED_IDS=<seu-user-id-do-userinfobot>Como verificar: rode o agente (ex.: npm start ou python main.py), mande /start ao seu bot pelo celular e veja se ele responde. Depois peca a um amigo para mandar mensagem ao mesmo bot: ele deve ser ignorado em silencio. Se isso acontecer, a whitelist esta funcionando.
Novo aqui? Um arquivo .env ("environment", ambiente) e um bloco de texto onde voce guarda segredos (tokens, chaves) separados do codigo. Long-polling e o jeito do Telegram funcionar sem abrir nenhuma porta no seu PC: e o seu agente que pergunta ao Telegram "chegou mensagem?", em vez de ficar esperando alguem bater na sua maquina. Por isso o bot e seguro mesmo rodando em casa.
Conceitos-chave
O bot oficial do Telegram que cria o seu bot e entrega o token.
A senha do bot. Vive no .env, nunca no codigo.
Lista do(s) ID(s) permitidos; qualquer outro e ignorado.
Sem porta exposta: o agente pergunta ao Telegram se chegou algo.
🧠 Passo 2: o cerebro
O bot ja recebe mensagem — mas ainda nao pensa. Agora voce pluga o cerebro: o modelo de IA que vai gerar as respostas. Aqui voce faz a escolha mais importante do projeto, e ela e uma so linha no .env. Voce pode usar a nuvem (potente, paga por uso) ou rodar local com Ollama (gratis depois de baixar, privado, mais lento). O melhor: trocar entre os dois nao mexe no codigo — e hot-swap (troca a quente).
☁️ Nuvem (OpenRouter / Anthropic)
- ✓Respostas rapidas e fortes, mesmo em PC fraco.
- ✓Zero configuracao de hardware.
- ✗Paga por token; os dados saem da sua maquina.
- ✗Precisa de internet.
🏠 Local (Ollama)
- ✓$0 por token apos baixar; dados ficam em casa.
- ✓Funciona offline.
- ✗Exige RAM (3B@8GB, 8B@16GB); CPU e lento (30-60s).
- ✗Respostas um pouco mais fracas que a nuvem de ponta.
.env
Objetivo: escolher o cerebro mudando so duas linhas. Adicione UM dos blocos abaixo ao seu .env (deixe o outro comentado com #).
# --- opcao A: NUVEM (potente, paga por uso) ---
LLM_PROVIDER=openrouter
LLM_MODEL=<ex: anthropic/claude-3.5-sonnet>
LLM_API_KEY=<cole-sua-chave-do-openrouter>
# --- opcao B: LOCAL com Ollama (gratis, privado) ---
# LLM_PROVIDER=ollama
# LLM_MODEL=<ex: llama3.2>
# (rode antes, no terminal: ollama pull <ex: llama3.2> )Como verificar: reinicie o agente e mande pelo celular: "em uma frase, quem e voce?". Se vier uma resposta coerente, o cerebro esta ligado. Para testar o hot-swap, troque o bloco ativo (comente A, descomente B), reinicie e mande de novo — mesma conversa, cerebro diferente, sem tocar no codigo.
⚠️ Cuidado classico: nao misture chaves
Chave da OpenAI nao e chave da Anthropic, e nenhuma das duas e o token do Telegram. Cada servico tem a sua. Misturar e a causa numero 1 de "nao funciona e nao sei por que". Se aparecer um erro de autenticacao (401/403), o primeiro lugar para olhar e qual chave foi para qual variavel no .env.
Conceitos-chave
O modelo que pensa em texto e gera as respostas.
Trocar o modelo mudando o .env, sem mexer no codigo.
Programa que roda modelos de IA no seu proprio computador.
Local p/ tarefa simples, nuvem p/ tarefa dificil.
💾 Passo 3: memoria + soul
Agora o bot pensa, mas e um estranho: esquece tudo ao fechar e nao tem personalidade. Dois arquivos resolvem isso. O soul.md ("a alma") da carater — quem ele e, o tom de voz, o que prioriza — e e injetado sempre no inicio da conversa. A memoria faz ele lembrar: as conversas viram texto guardado e um indice SQLite permite buscar o que ja foi dito. Sem o soul, voce tem "uma pasta de codigo"; com ele, voce tem um Jarvis.
soul.md
Objetivo: dar identidade ao bot. Crie um arquivo soul.md na pasta do projeto e cole o bloco, trocando os pedacos entre < >.
# soul.md — a alma do meu Jarvis
## Quem sou
Eu sou o <nome-do-seu-jarvis>, assistente pessoal de <seu-nome>.
## Tom de voz
Direto, caloroso e breve. Sem enrolacao. Trato <seu-nome> pelo nome.
## Prioridades
- Responder em portugues.
- Quando nao souber, dizer que nao sabe (nunca inventar).
- Lembrar do contexto das conversas anteriores.
## Sobre <seu-nome>
Fuso: <ex: America/Sao_Paulo>. Trabalho: <ex: professor>.
Prefere respostas em topicos curtos.Como verificar: reinicie e mande "qual e o seu nome e quem eu sou pra voce?". Ele deve responder com o nome do soul.md e te chamar pelo seu nome. Depois mande "meu prato favorito e lasanha", feche o Telegram, abra de novo mais tarde e pergunte "qual e meu prato favorito?". Se ele lembrar, a memoria SQLite esta gravando.
🧩 Como a memoria funciona, sem mistica
- •Cada conversa vira texto salvo num arquivo ou banco — a "verdade" e legivel por voce.
- •Um indice SQLite FTS5/BM25 (busca por palavra) acha rapido o trecho relevante quando voce pergunta algo.
- •Antes de responder, o agente busca na memoria e cola o trecho no contexto. Por isso ele "lembra".
Novo aqui? SQLite e um banco de dados que e so um arquivo na sua pasta (nada de servidor). FTS5/BM25 e o jeito dele fazer busca por texto — voce pergunta "lasanha" e ele acha a frase onde voce falou disso. System prompt e o texto invisivel colado no comeco de toda conversa: e ali que o soul.md entra para o modelo "saber quem e".
Conceitos-chave
A alma: personalidade, tom e prioridades, injetados sempre.
Conversas viram texto que sobrevive ao fechar o app.
Banco-arquivo simples; o indice da memoria.
O texto inicial onde o soul vira a identidade do modelo.
🧩 Passo 4: uma skill util
Ate aqui seu Jarvis conversa e lembra. Hora de ele fazer algo concreto. Uma skill e uma "receita": um arquivo curto que empacota um passo-a-passo que voce repetiria toda vez. A nossa: "resumo do meu dia" — ele puxa sua agenda (via uma ferramenta MCP de calendario) e devolve um resumo em topicos. Em vez de explicar cinco passos, voce diz uma frase e a skill executa.
MCP (Model Context Protocol) e o "USB das ferramentas de IA": cada integracao (calendario, e-mail, GitHub) e um servidor separado e padronizado que voce pluga sem reescrever o agente. E mais seguro do que baixar "skills da comunidade" de origem duvidosa — voce sabe exatamente o que cada servidor faz.
skills/resumo-do-dia/SKILL.md
Objetivo: dar ao Jarvis a receita de resumir seu dia. Crie a pasta e o arquivo SKILL.md abaixo, trocando os pedacos entre < >.
---
name: resumo-do-dia
description: Resume os compromissos de hoje em topicos curtos.
Acionar quando o usuario disser "resumo do dia", "como esta
meu dia" ou "agenda de hoje".
---
# Resumo do meu dia
Passos:
1. Use a ferramenta de calendario (MCP) para listar os
eventos de HOJE no fuso <ex: America/Sao_Paulo>.
2. Para cada evento, pegue horario + titulo.
3. Responda em ate <ex: 5> topicos curtos, do mais cedo
ao mais tarde. Comece com "Bom dia, <seu-nome>!".
4. Se nao houver eventos, diga que a agenda esta livre.Como verificar: reinicie o agente e mande pelo celular "resumo do meu dia". Ele deve acionar a skill, consultar o calendario e responder com a lista de eventos em topicos (ou avisar que esta livre). Se ele responder de forma generica sem olhar a agenda, confira se o servidor MCP de calendario esta conectado.
📊 Skill x ferramenta — qual e a diferenca?
- •Ferramenta (tool): uma acao atomica — "listar eventos do calendario". E uma mao.
- •Skill: um procedimento que orquestra ferramentas + julgamento — "monte o resumo do dia". E a receita que usa as maos.
- •A skill custa quase nada ate ser acionada: o agente le so o frontmatter (~100 tokens) e so carrega o resto quando precisa.
Novo aqui? O frontmatter e o bloco entre --- no topo do arquivo (nome + descricao). E por ele que o agente decide se aciona a skill. Carregamento progressivo significa que a receita inteira so e lida quando faz falta — economiza contexto e mantem o Jarvis leve.
Conceitos-chave
Uma receita empacotada num arquivo markdown.
O "USB das ferramentas": pluga integracoes padronizadas.
Nome + descricao no topo; decide quando acionar a skill.
A receita so e lida quando e necessaria.
🎙️ Passo 5: voz e cadencia
Os dois ultimos tijolos deixam o Jarvis humano e proativo. Voz: voce manda um audio no Telegram, o agente transcreve com Whisper (entende sua fala), pensa e — se quiser — responde falando com TTS (sintese de voz). Cadencia: um heartbeat agendado (cron) faz ele agir sozinho — por exemplo, te mandar o "resumo do meu dia" todo dia as 7h, mesmo com o celular no bolso e o laptop fechado.
O audio vira texto (Whisper), o LLM pensa em texto, e a fala de volta (TTS) e opcional. Lembre: "voz e a interface, o orquestrador e o cerebro" — voce decide por mensagem se responde em texto ou voz.
.env + terminal
Objetivo: ligar a voz e agendar o resumo diario. Acrescente ao .env e teste a conversao de audio no terminal.
# .env (voz e cadencia)
VOICE_ENABLED=true
STT_PROVIDER=whisper
OPENAI_API_KEY=<chave-da-OpenAI-so-para-Whisper>
# heartbeat: rodar a skill "resumo-do-dia" todo dia as 7h
HEARTBEAT_CRON=<ex: 0 7 * * *>
HEARTBEAT_SKILL=resumo-do-dia
# --- teste rapido da conversao de audio (no terminal) ---
# ffmpeg -i <audio-do-telegram.ogg> -ar 16000 saida.wavComo verificar: (voz) grave um audio no Telegram dizendo "me conte uma curiosidade" — o agente deve transcrever e responder. (cadencia) para nao esperar ate as 7h, troque temporariamente HEARTBEAT_CRON para daqui a 2 minutos (ex.: se sao 14h32, use 34 14 * * *), reinicie e veja a mensagem chegar sozinha. Funcionou? Volte o cron para 0 7 * * *.
⚠️ A chave do Whisper e diferente
O Whisper (transcricao) costuma usar a OPENAI_API_KEY, que NAO e a chave do seu cerebro se voce escolheu Anthropic/OpenRouter, nem o token do Telegram. Tres servicos, tres credenciais. Se a voz "nao transcreve", quase sempre e essa chave faltando ou trocada.
Novo aqui? STT ("speech-to-text") e transformar fala em texto; Whisper e o modelo que faz isso. TTS ("text-to-speech") e o caminho inverso: texto vira voz. ffmpeg e um conversor de audio/video que prepara o arquivo do Telegram para o Whisper. cron e a notacao de agendamento: 0 7 * * * quer dizer "as 7h00, todo dia".
Conceitos-chave
Transforma o audio que voce manda em texto.
Saida opcional: o Jarvis responde falando.
Agendamento que faz o agente agir sozinho num horario.
De "responde quando chamo" para "me avisa antes".
Auto-checagem (opcional): no seu Jarvis de bolso, onde mora o cerebro (o modelo)?
🎯 Resumo do modulo
Proximo:
Voltar para a trilha — voce concluiu a Trilha 5 (Jarvis no celular). Hora de revisar a jornada e seguir para a Trilha 6.