🔌 Projeto 4: GitHub e documentos
Um agente que so conversa e util; um agente que le as suas fontes e poderoso. Neste projeto voce conecta o Hermes ao seu codigo (GitHub) e aos seus documentos, e passa a fazer perguntas sobre o repo e os arquivos — tudo rodando no modelo local, em modo Vault, sem que nada proprietario saia da sua maquina.
🎯 Objetivo: conectar as suas fontes
No projeto anterior voce deu ao agente uma memoria e uma cara. Agora vai dar a ele olhos: o acesso ao seu codigo no GitHub e aos seus documentos locais. A diferenca e enorme — em vez de responder so com o que "sabe" do treino, o agente passa a responder sobre o seu repo e os seus arquivos. E como roda local em Vault, nem o codigo proprietario nem os documentos saem da maquina.
📋 O que voce vai entregar
- •Um repositorio do GitHub conectado ao agente.
- •Uma pasta/arquivo de documentos que o agente consegue ler.
- •Pelo menos uma pergunta respondida sobre o repo e outra sobre o doc.
- •A confirmacao de que tudo rodou em Vault, sem vazamento.
Pre-requisitos: o agente Hermes ja conectado ao modelo local (Projeto 2 / modulo 3.2). As conexoes deste projeto sao feitas pela interface do Hermes (painel de conexoes) — nao ha um comando de CLI para "conectar GitHub", entao descrevemos a acao na tela. Para diagnostico, valem os comandos reais hermes status e hermes doctor.
Conceitos-chave
Uma ponte do agente para uma fonte externa (repo, pasta).
O codigo ou documento que o agente vai ler.
Modo airgapped: nada sai da maquina.
O log que mostra quais fontes o agente acessou.
🐙 Etapa 1 — Conectar o GitHub
A primeira fonte e o GitHub. No painel de conexoes do Hermes, voce autoriza o acesso a um repositorio. A partir dai o agente consegue ler os arquivos, o historico de commits e a estrutura do projeto — e responder perguntas sobre ele sem voce abrir cada arquivo na mao.
Abra o painel de conexoes
No dashboard do Hermes, va ate a area de conexoes/integracoes e escolha "GitHub".
Autorize o acesso
Siga o fluxo de autorizacao na tela e selecione somente os repos que voce quer expor ao agente.
Confirme a conexao
O repo passa a aparecer como conectado. Esse e o sinal de que o agente ja consegue enxerga-lo.
✓ Boas praticas
- ✓Conecte so os repos necessarios — escopo minimo.
- ✓Comece por um repo pequeno pra testar o fluxo.
- ✓Revise no Activity o que o agente leu da primeira vez.
- ✓Mantenha o modelo local selecionado antes de perguntar.
✗ A evitar
- ✗Dar acesso a toda a sua conta "por preguica" de filtrar.
- ✗Conectar e ja mandar pra nuvem — confirme o modo Vault antes.
- ✗Assumir que conectou sem checar o status da conexao.
- ✗Esquecer de desconectar repos que nao usa mais.
🔎 Como verificar esta etapa
O repo aparece como conectado no painel. Se a conexao nao subir, rode hermes status e hermes doctor no terminal para diagnosticar o estado do agente antes de tentar de novo.
Conceitos-chave
Onde voce liga GitHub e outras fontes.
O passo que da permissao de leitura ao agente.
Conceder so o necessario, repo por repo.
Comandos reais de diagnostico do agente.
📄 Etapa 2 — Ler documentos
A segunda fonte sao os seus documentos: PDFs, notas, planilhas, contratos, manuais. Em vez de conectar a um servico remoto, voce aponta o agente a uma pasta ou arquivo local. Ele le o conteudo direto do disco — e, justamente por ser local, nenhum byte do documento precisa subir pra internet.
Novo aqui? "Ler um documento" aqui significa o agente extrair o texto do arquivo e usa-lo como contexto da resposta. Documentos grandes consomem janela de contexto (lembra do modulo 1.4 / 2.4): por isso o modelo do agente tem 64k — pra caber documento + pergunta + resposta sem estourar.
Aponte a pasta/arquivo
Na interface do Hermes, indique a pasta de documentos ou anexe o arquivo que quer que o agente leia.
Deixe o agente indexar/ler
Ele processa o conteudo localmente. Documento maior leva mais tempo na primeira leitura.
Veja registrado em Activity
O acesso ao documento aparece no log — confirme que foi o arquivo certo.
🔎 Como verificar esta etapa
Peca um resumo de uma linha do documento. Se o resumo bate com o conteudo real do arquivo (e nao com algo generico), o agente de fato leu a fonte local.
Conceitos-chave
Pasta/arquivo no seu disco, lido sem rede.
Processar o conteudo pra poder consultar depois.
O texto do arquivo entra na janela de contexto.
Contexto grande cabe documento + pergunta + resposta.
🔎 Etapa 3 — Perguntar sobre o repo e o doc
Com as fontes conectadas, o agente vira um copiloto que conhece o seu material. Em vez de você caçar a informacao, voce pergunta — e ele responde puxando do repo e dos documentos reais. Esse e o momento em que conexao vira valor.
O GitHub e os documentos entram no agente local, que responde sobre o seu material. Tudo dentro da borda tracejada do Vault — nada cruza pra internet. E essa fronteira que torna seguro conectar fontes proprietarias.
💬 Perguntas que ja valem a pena
- •"Resuma os ultimos commits e o que mudou neles."
- •"Ache a funcao que faz X e explique como ela funciona."
- •"Do que fala esse PDF? Liste os 3 pontos principais."
- •"Tem inconsistencia entre o contrato e o documento de specs?"
🔎 Como verificar esta etapa
A resposta cita detalhes especificos do seu repo/doc (nome de arquivo, funcao, trecho do PDF) que so existem na fonte conectada. Se for generica, o agente nao leu — reveja a conexao.
Conceitos-chave
Responde com base no seu material, nao so no treino.
Quanto mais concreta, melhor a resposta ancorada.
Detalhe real prova que a fonte foi lida.
Cruzar repo + doc revela inconsistencias.
🔒 Etapa 4 — Manter tudo no Vault
Conectar fontes proprietarias so e seguro se a leitura acontecer 100% local. Esse e o papel do modo Vault: o agente usa o modelo do Ollama na sua maquina e nao manda nada pra nuvem. Antes de perguntar sobre codigo de cliente ou um contrato, confirme que o modo Vault esta ligado e que o modelo selecionado e o local.
🛡️ Checklist de privacidade antes de perguntar
- •O modo Vault esta ativo (airgapped).
- •O modelo no canto inferior direito e o local (ex.: qwen3-coder-64k).
- •So os repos/pastas necessarios estao conectados.
- •O Activity nao mostra nenhuma chamada externa.
💡 Dica pratica
Quer a prova cabal? Desconecte o cabo de rede / desligue o wi-fi e faca a pergunta sobre o repo. Se o agente continuar respondendo, e porque a leitura e a inferencia rodam de fato na sua maquina — exatamente o que o Vault promete.
🔎 Como verificar esta etapa
Com a rede desligada, o agente ainda responde sobre o repo e o documento. Esse teste offline confirma que nenhuma fonte proprietaria precisou sair da maquina.
Conceitos-chave
Modo airgapped: leitura e resposta 100% locais.
Confirmado no canto inferior direito do Hermes.
Codigo/doc que nao pode vazar — fica no Vault.
Sem rede e ainda responde = privacidade real.
✅ Etapa 5 — Resultado: agente sobre as suas fontes
Voce saiu de um agente que so "sabia coisas do mundo" para um agente que conhece o seu codigo e os seus documentos — e responde sobre eles sem que nada saia da maquina. Esse e o tipo de uso que justifica o local de verdade: trabalhar com material proprietario que jamais poderia ir pra nuvem.
🏁 Resultado esperado
- ✓GitHub conectado e o repo aparecendo como acessivel.
- ✓Documento lido, com resumo que bate com o conteudo real.
- ✓Perguntas respondidas com detalhes do seu material.
- ✓Tudo confirmado em Vault — funciona ate offline.
⚠️ Se algo nao bateu
- ✗Resposta generica? O agente nao leu a fonte — revise a conexao no painel.
- ✗Conexao nao sobe? Rode
hermes status/hermes doctor. - ✗Travou offline? Confirme que o modelo selecionado e o local, nao a nuvem.
Auto-checagem (opcional): por que conectar GitHub e documentos ao Hermes local e seguro pra dado proprietario?
🎯 Resumo do projeto
Proximo modulo:
3.5 — Projeto 5: Background agents 24/7 a $0