Ricardo IA Studio · guia de bolso
Glossário de IA
As palavras que aparecem toda vez que a gente mexe com IA e com a Naia, cada uma explicada em uma ou duas frases e, quando faz diferença, com o exemplo de como ela funciona na nossa instalação.
Nenhum termo com essa palavra.
Termos gerais de IA
Valem para qualquer ferramenta: ChatGPT, Claude, Gemini, a Naia ou o Claude Code aqui no PC.
| Termo | O que é |
|---|---|
| Modelo (LLM) | O "cérebro" que lê texto e escreve a resposta. gpt-5.5, gpt-6-astra, Claude Opus e Gemini são modelos. Trocar o modelo muda a qualidade e o custo, não o que o agente sabe fazer. |
| Provedor (provider) | A empresa ou a rota por onde o modelo é acessado. A Naia usa o provedor openai-codex, que é o ChatGPT pela conta do Ricardo. |
| Prompt | O pedido que você escreve. Prompt bom diz o que quer, para quem e em que formato. |
| System prompt | As instruções fixas que o modelo recebe antes de qualquer mensagem sua. Na Naia ele é montado a partir do SOUL.md e do AGENTS.md. |
| Token | O pedaço de texto que o modelo conta. Em português, uma palavra dá mais ou menos 1,5 token. Cota e preço são medidos em tokens. |
| Janela de contexto | Quanto texto o modelo consegue "ter na cabeça" numa conversa. Quando enche, o começo some ou é resumido. Por isso o /new na Naia limpa a conversa e ela volta a ler as regras do zero. |
| Alucinação | Quando o modelo inventa um fato com toda a confiança. A defesa é mandar ele conferir (abrir o site, rodar o comando) antes de afirmar. |
| Raciocínio (reasoning) | Modelos que "pensam" antes de responder. Acertam mais em tarefa longa, mas demoram para mandar o primeiro byte, e isso estoura prazo curto. |
| Multimodal | Modelo que entende mais que texto: imagem, áudio, PDF. |
| STT (speech-to-text) | Transformar fala em texto. Na Naia quem faz é o Whisper rodando no próprio servidor. |
| TTS (text-to-speech) | Transformar texto em voz. Na Naia é o edge-tts, voz pt-BR Francisca, gratuito. |
| Whisper | Modelo de transcrição da OpenAI, que dá para rodar no seu computador sem pagar por uso. O Handy aqui no PC também usa. |
| Embedding | Uma lista de números que representa o sentido de um texto. Serve para buscar "coisas parecidas" em vez de palavras iguais. |
| RAG | Buscar documentos relevantes e colar no prompt antes de o modelo responder. É como o agente "consulta a apostila" sem ter sido treinado nela. |
| Fine-tuning | Treinar de novo um modelo com exemplos seus. Caro e quase nunca necessário: instrução bem escrita resolve 90% dos casos. |
| Temperatura | O quanto o modelo varia a resposta. Baixa repete, alta inventa mais. |
| API | A porta pela qual um programa conversa com outro. A fal, a Meta e o Zernio têm API. |
| Chave de API (API key) | A senha de um programa para usar uma API. Mora no .env e nunca vai para chat, print ou GitHub. |
| OAuth | Login pelo navegador no lugar da chave. A Naia entrou no ChatGPT assim: o Ricardo autorizou num código, sem chave nenhuma. |
| Cota / rate limit | O limite de uso por período. Estourou, a API devolve erro 429 e para de responder até a cota voltar. |
| Agente | Um modelo com ferramentas e autonomia para executar tarefas em vários passos, não só conversar. A Naia é um agente. |
| Ferramenta (tool) | Uma ação que o agente pode disparar: rodar comando no terminal, buscar na web, gerar imagem, criar tarefa. Sem ferramenta, o modelo só escreve. |
| MCP | Model Context Protocol: o padrão para ligar ferramentas externas num agente. A fal e o Firecrawl entram no Claude Code por MCP. |
| Skill | Um arquivo de instruções (SKILL.md) que ensina o agente a fazer um tipo de tarefa do jeito certo. Skill registra método; ela não liga integração sozinha. |
| Subagente | Um agente que o agente principal chama para fazer uma parte do trabalho. |
| Orquestrador(a) | O agente que recebe o pedido, divide e distribui para a equipe. Na nossa instalação é a Maya do Hermes. |
| Memória | Arquivos que o agente lê em toda conversa para lembrar fatos sobre você e o trabalho. O modelo em si não lembra de nada entre conversas. |
| Geração de imagem | Modelos como Muse (Meta), GPT Image e Nano Banana, chamados pela fal.ai ou pelo Codex. Muse custa US$ 0,01 por imagem. |
| fal.ai | Loja de modelos de imagem, vídeo e áudio, paga por uso, com uma chave só para todos. |
| Codex | O agente de programação da OpenAI. Usa a mesma conta e a mesma cota do ChatGPT da Naia: se um estoura, o outro sente. |
Termos da Naia
A Naia é o Hermes Agent (da Nous Research) instalado num servidor e conversando pelo Telegram. Estes são os nomes das peças dela.
Peças da instalação
| Termo | O que é |
|---|---|
| Hermes Agent | O programa que faz a Naia existir. Ele junta modelo, ferramentas, memória e Telegram. A versão é fixada de propósito pelo roteiro do curso: não atualizar. |
| VPS / servidor | O computador alugado onde ela roda 24 horas. A nossa é a KVM4 da Hostinger. O PC do Ricardo pode estar desligado que ela continua funcionando. |
| Gateway | O processo que fica ligado no servidor ouvindo o Telegram e entregando as mensagens para a Naia. Reiniciar o gateway faz ela reler a configuração. Cada reinício manda "Gateway shutting down" no Telegram, então junte as mudanças e reinicie uma vez. |
| Bot do Telegram | A conta pela qual você fala com ela. Só o Id do Ricardo está na lista de permitidos; mensagem de outra pessoa é ignorada. |
HERMES_HOME (/root/.hermes/) | A pasta com tudo dela: config.yaml, .env, SOUL.md, AGENTS.md, memórias, skills, perfis. |
| config.yaml | As configurações: modelo, voz, terminal, aprovações, busca. |
| .env | Onde ficam as chaves (fal, Meta, Zernio, Firecrawl). Arquivo trancado, ninguém imprime o conteúdo. |
| SOUL.md | A personalidade: quem ela é, como fala, o que nunca faz. Inclui a seção "Qual Maya eu sou". |
| AGENTS.md | O manual de operação: regras de trabalho, a equipe, onde publicar, como verificar. Tem limite de 20 mil caracteres; acima disso o Hermes corta o meio do arquivo. Detalhe longo vai para /srv/naia/regras/. |
| USER.md e MEMORY.md | A memória dela sobre o Ricardo e sobre o trabalho. A ferramenta de memória grava direto nesses arquivos. |
| Perfil (profile) | Um agente separado dentro do mesmo Hermes, com SOUL, modelo e skills próprios. Cada membro da equipe é um perfil. |
| Skill da Naia | Pasta com SKILL.md em skills/. Exemplos nossos: imagem-fal (gera imagem pela Muse) e captura-de-tela. Ela tem as 90 de fábrica mais as 55 do Turbo Naia. |
| Toolset | O conjunto de ferramentas ligado para um canal. A Maya tem kanban ligado no Telegram, por exemplo. |
Segurança e acesso
| Termo | O que é |
|---|---|
| Contêiner / sandbox | Uma caixa isolada (Docker) onde rodam os comandos de terminal dela. Lá dentro ela não enxerga o servidor inteiro. A caixa morre depois de 5 minutos parada, então arquivo deixado no /tmp dela some. |
terminal.backend: docker | A linha do config.yaml que liga o contêiner. Com local, ela rodaria comando direto no servidor, ao lado do CRM com dado de paciente. |
| Mount (docker_volumes) | Uma pasta do servidor que aparece dentro do contêiner. Pode ser só leitura (ro) ou leitura e escrita (rw). Ela lê /opt mas não consegue apagar nada lá: o próprio sistema recusa. |
/srv/naia | A área de trabalho dela, única pasta com o mesmo caminho dentro e fora do contêiner. Por isso imagem gerada ali chega no Telegram, e documento que ela precisa ler pelo terminal tem que morar ali. |
| docker_forward_env | A lista de chaves do .env que entram no contêiner. O formato certo é '["FAL_KEY"]', com colchetes; sem eles a lista fica vazia em silêncio. |
| approvals.mode: manual | Comando perigoso vira botão de aprovar ou recusar no Telegram antes de rodar. |
| Contrato de verificação | Como ela marca o que entregou. ✅ VERIFICADO só depois de conferir de verdade (o site respondeu 200). 🔸 FEITO, NÃO TESTADO quando fez mas não conseguiu provar. ⚪ quando não fez. |
Trabalho do dia a dia
| Termo | O que é |
|---|---|
| Kanban | O quadro de tarefas da equipe. A Maya cria um cartão, um perfil pega e executa. Tarefa nasce "blocked" e é liberada com hermes kanban promote <id>. |
| Delegação | Quando a Maya passa uma tarefa para outro perfil, que roda num modelo menor (gpt-6-luna) para economizar cota. |
| Cron (job agendado) | Tarefa que roda sozinha em horário marcado, como o vigia-sites (a cada 2h, das 8h às 22h) e o vigia-certificados (9h). |
--no-agent | Modo de cron em que o script faz tudo e a Naia só entrega a saída. Não gasta token e não inventa nada. Saída vazia = nenhuma mensagem. |
| Vigia silencioso | Cron que só fala quando algo quebra. Precisa de teste de entrega, porque silêncio pode ser "tudo no ar" ou "o vigia morreu". |
| Hotsite / acervo | Landing de nicho da Agente Maya montada por novo_hotsite.py e publicada em ricardoiastudio.tech/demo/. O acervo são 11 temas de imagem prontos, custo zero. |
| PUBLICAR | Arquivo que ela cria numa pasta de site para mandar publicar. Um script no servidor copia para produção a cada minuto, faz backup antes e nunca apaga nada do destino. |
| Subdomínio | Site novo em nome.ricardoiastudio.tech, publicado por script com certificado próprio. Nasce fora do Google; o arquivo .indexar libera. |
| Fila de captura | Pedido de print de site em /srv/naia/capturas-fila/. Devolve a primeira dobra e a página inteira, para não confundir carregamento lento com defeito. |
| ddgs / Firecrawl | A busca na web (ddgs, gratuita) e a leitura de página (Firecrawl, que extrai o texto limpo). |
| Ponte (maya-ponte) | A ligação entre o servidor e o app Maya Desktop no PC: você fala "OK Maya" no computador e quem responde é a Maya do servidor. |
Comandos que você usa
| Comando | Onde | O que faz |
|---|---|---|
/new | Telegram | Começa conversa nova. Regra nova no AGENTS.md só vale depois disso. |
/voice tts | Telegram | Ela responde em texto e áudio. O espaço é obrigatório: /voicetts dá erro. |
/voice on / /voice off | Telegram | Só áudio / desliga a voz. |
hermes -z "pergunta" | Servidor | Pergunta rápida sem Telegram, ótima para testar. Rodar sempre de /root, a mesma pasta do gateway, senão ela não lê o AGENTS.md. |
hermes -p <perfil> -z "..." | Servidor | O mesmo, falando com um perfil da equipe. |
hermes auth list | Servidor | Mostra a credencial do ChatGPT e se ela está marcada como esgotada. |
hermes auth reset openai-codex | Servidor | Tira a marca de cota esgotada. Resolve a Naia muda depois de um 429. |
systemctl --user restart hermes-gateway | Servidor | Reinicia o gateway. Antes, export XDG_RUNTIME_DIR=/run/user/0. |
Naia, Maya e Maya
"Naia" é o nome que o curso dá ao agente. Na nossa instalação três coisas diferentes se chamam Maya, e isso confunde até a própria agente, que tem ordem de perguntar quando a conversa ficar ambígua.
| Qual | O que é | Onde vive |
|---|---|---|
| Maya do Hermes | A Naia do curso, renomeada em 23/09/2026. É a agente pessoal e orquestradora da equipe. As pastas continuam com "naia" no nome de propósito. | Servidor KVM4, no Telegram |
| Agente Maya (personagem) | A personagem 3D de marca que vende automação de atendimento no Instagram e nos hotsites. | Instagram, maya.ricardoiastudio.tech |
| Maya do OpenClaw | A orquestradora antiga, em outro programa (OpenClaw) e outro servidor. | VPS do AgencyOS, outro bot do Telegram |
Erros e o que eles querem dizer
Vários erros do Hermes mentem sobre a causa. Esta tabela traduz os que já apareceram.
| Mensagem | O que é de verdade | O que fazer |
|---|---|---|
AuthError: No Codex credentials stored | Quase nunca é login perdido. A cota do ChatGPT estourou (429) e o Hermes se bloqueou por dias. | hermes auth list para confirmar, depois hermes auth reset openai-codex. O cron destrava-maya faz isso às 22h. |
429 usage limit has been reached | A cota do ChatGPT acabou, para a Naia e para o Codex do PC juntos. | Esperar a data que a mensagem informa. Crédito na fal não resolve: a fal é só imagem. |
Broken pipe / stale for 90s | O modelo demorou para começar a responder numa tarefa pesada e o Hermes cortou a ligação. | Já corrigido com HERMES_API_CALL_STALE_TIMEOUT=300. Se voltar, subir esse número. |
Gateway shutting down no Telegram | Alguém reiniciou o gateway. Não é pane. | Nada. |
unrecognized slash command | Comando colado, tipo /voicetts. | Escrever com espaço: /voice tts. |
Read-only file system | Ela tentou mexer numa pasta só de leitura. É a trava funcionando. | Trabalhar em /srv/naia e publicar pelo caminho certo. |
| "Esse arquivo não existe" (sobre um arquivo que existe) | O arquivo está fora das pastas que o contêiner enxerga. | Mover para /srv/naia/. |
| Ela diz ✅ que editou o próprio SOUL/AGENTS, mas nada mudou | A edição caiu na cópia dentro do contêiner, não no arquivo real. | Mandar o texto para o Claude Code aplicar no servidor e reiniciar. |
invalid key credentials / Exhausted balance (fal) | Chave da fal vencida ou conta sem saldo. | Trocar a chave pelo script trocar-falkey.sh ou pôr crédito. |
Um guia da Ricardo IA Studio