Por que sua IA inventa resposta? O que aprendi migrando para RAG Agêntico

E assim começava um dia pacato de uma terça-feira. Abri meus e-mails, revisei alguns PRs e aproveitei para analisar as métricas e feedbacks sobre o uso da Amália aqui na Academia, enquanto meus testes rodavam. E me deparei com uma situação um tanto quanto 'atípica' haha.

"Amália é um nome que carrega história — remete à Amália Rodrigues, a lenda do fado português. Tem esse peso de tradição, maestria, e alguém que realmente domina seu ofício..."

Foi essa a resposta que a Amália deu, quando um membro perguntou de onde vem o nome dela.

Uma resposta bem escrita. Articulada. Mas completamente inventada.

A Amália — a parceira de estudos da Academia — leva o nome da minha Golden Retriever. É essa a história inteira. Não tem fado, não tem Amália Rodrigues, não tem "peso de tradição". Tem uma cachorra que dorme do meu lado enquanto eu trabalho.

Seria melhor um bug comum em produção do quee esse tipo de resposta. Bug você abre o log e conserta. Resposta inventada parece certa, mas não fosse o report não teria me dado conta que havia algo fundamentalmente errado ali.

Sim, eu já resolvi. Mas antes da história, quero trazer uns updates rápidos do que está acontecendo na Academia do Ruby.

O que mudou na plataforma

Turma de maio do CAP aberta. O CAP — Ciclo de Aceleração Profissional — é o nosso bootcamp de ciclo curto: quatro encontros ao vivo, grupo pequeno, um desafio definido e uma entrega funcional ao final. A turma de maio começa em 07/05 e ainda temos algumas vagas. As inscrições passam por uma aplicação rápida — quem se interessar, a página tá aqui.

Coleções novas de Badges chegando. O Passaporte vai ganhar leva nova de Badges em coleções exclusivas, premiando conclusão de tarefas e cursos. O foco do trabalho foi UX — deixar claro o que cada conquista significa e dar peso visual à evolução de quem está chegando lá. Quem está perto de uma vai entender o cuidado quando ela aparecer.

Home e Conteúdos repaginadas. As duas páginas passaram por um aprimoramento de design pensado pra deixar a plataforma mais imersiva, design aprimorado e mais foco no que importa em cada momento da jornada. Aproveitei o trabalho pra testar o Claude Design, e o resultado ficou bom.

Apps nativos atualizados. Saiu versão nova de iOS e Android. Aprimoramos a estabilidade com alguns updates de dependências — e a experiência dos materiais complementares das aulas ficou ainda melhor no celular. Se você usa pelo app, vale atualizar.

Agora, de volta à Amália.

O problema era de arquitetura, não de modelo

A Amália usa RAG — Retrieval-Augmented Generation. Em português direto: a técnica de dar contexto ao modelo antes de ele responder, usando uma base de conhecimento própria.

Como funcionava: você manda uma pergunta, o sistema busca os trechos mais parecidos na base, cola tudo no prompt do modelo, e ele responde com aquele contexto.

Simples. E quebrava em casos que deveriam ser fáceis — como a pergunta sobre o nome.

Tinha três falhas que eu não tinha enxergado.

1. O sistema injetava contexto sempre, fosse relevante ou não. Se os cinco trechos mais próximos da pergunta fossem só vagamente parecidos, eles entravam no prompt do mesmo jeito. O modelo recebia isso e tentava fazer um milagre, criando uma 'fanfic'.

2. Era uma busca só por pergunta. Se os trechos certos não aparecessem naquela tentativa, acabou. O modelo não tinha como tentar de outro ângulo.

3. A terceira é a mais interessante. Depois que o contexto era injetado, o modelo ficava sem parâmetro. Aquilo era a aposta toda. Faltou alguma coisa? Improviso na cara dura. Se você perguntasse sobre Turbo e depois mudasse para o artigo mais recente sobre uso de IA: já era. Não encontrava.

A Amália improvisava bem demais. E essa era a raiz do problema e não era tão trivial de encontrar o problema.

Eu sei que precisava de uma solução e tentei planejar isso conversando sobre o problema com o Claude Opus.

Deixar o modelo decidir o que buscar

Em dezembro de 2024, a Anthropic publicou um guia chamado Building Effective Agents. Um dos padrões descritos por lá é simples, mas vira a chave:

Em vez de dar contexto ao modelo, dê a ele uma ferramenta pra buscar contexto quando precisar.

É a diferença entre entregar um resumo pronto e dar acesso à biblioteca.

Na prática, a Amália parou de receber chunks injetados no prompt inicial. Agora ela recebe uma ferramenta e decide ela mesma quando usar e com que query procurar.

Pra "por que você se chama Amália?", o fluxo virou esse:

1. 1

   Amália formula a query

   "origem nome Amália assistente Academia"

2. 2

   Recebe os trechos certos

   a história da Golden Retriever, que contamos num artigo anterior e anotações internas sobre como explicar.

3. 3

   Formula a Resposta Correta

   Amália responde com base no que achou na base de dados

Se a primeira busca não bastasse, ela tentaria outra com palavras diferentes. O modelo agora pensa sobre o que precisa antes de responder.

Essa abordagem é conhecida como RAG Agêntico. O modelo deixa de ser só gerador de texto e passa a tomar decisões sobre como chegar na resposta certa.

O que ficou diferente

A pergunta sobre o nome — antes inventada — agora traz a história verdadeira: a Golden Retriever, que dorme ao lado da minha mesa do escritório enquanto trabalho, sem nenhum fado ou Portugal envolvidos. Mas o ganho não é só nessa pergunta. Toda interação que dependia de informação específica da Academia ficou mais coerente e alinhada com o que eu pensei quando decidi criar a Amália.

E teve um bônus inesperado: implementar isso fez com que precisássemos adicionar um tratamento na estrutura das mensagens do RubyLLM. As chamadas da ferramenta podiam acabar aparecendo no chat como mensagens, e isso é errado pois não é uma resposta da agente. Resolvi criando uma estrutura que detecta o momento que a resposta real começa a chegar e esconde o indicador de busca. Sem polling, sem setTimeout, sem gambiarra. Usando apenas o que o Rails disponibiliza de melhor.

Pra quem quer o detalhe

Esse texto é o conceito e atualização das nossas principais novidades. A implementação completa, o código Ruby, a hierarquia de escopo (aula → módulo → curso), o filtro de similaridade e as decisões que ficaram no caminho estarão numa série de artigos exclusiva para assinantes onde vamos analisar os bastidores de como nossa ferramenta funciona.

E ainda vem muita coisa boa por aí. Estamos construindo uma experiência completa para nossa comunidade.

Até a próxima!