Lucas Souza

A semana inteira em um diagrama só — as seis camadas de uma arquitetura de agentes de IA (modelo, contexto, tools/MCP, RAG, guardrails, observabilidade), como se encaixam e um checklist de produção pra defender o agente numa code review.

RAG não é memória, e confundir os dois quebra seu agente. O que é RAG, como funciona por dentro, e onde ele termina e a memória (e o fine-tuning) começam.

"Funciona nos meus testes" não é avaliação. Como montar evals honestos para um agente: golden set de falhas reais, métricas por etapa (recuperação, decisão de tool, resposta) e LLM como juiz com cautela.

As cercas que separam um agente que roda em produção de um que vive preso no "demo na minha máquina": validar a entrada, restringir o que as tools fazem e checar a saída antes de devolver pro usuário.

Funcionava na demo, virou conta de US$ 3 mil e loop infinito em produção. Os 5 anti-patterns de arquitetura que mais quebram agentes de IA em produção — context stuffing, tools sem timeout, retry burro, zero observabilidade e ausência de guardrails — cada um com o sintoma e a correção.

No RAG clássico a busca acontece sempre. No agentic RAG o agente decide se busca, o que busca e quantas vezes, tratando a recuperação como uma tool. Veja o padrão de código e, principalmente, quando esse poder vale o custo.

Antes de assinar um serviço gerenciado de memória, descubra por que o Postgres que você já tem resolve 80% do problema com pgvector: instalação, uso no Laravel e critérios de decisão.

Um walkthrough de um agente funcional em PHP puro com Laravel, batendo direto na Claude API, sem framework de agente nenhum. Só o loop prompt, tool use e resposta.

A busca vetorial traz 20 candidatos "parecidos" — mas parecido não é relevante. O reranker reordena por relevância real antes de mandar pro modelo. Este post mostra cross-encoder vs busca híbrida e quando cada um vale, com código rodando.

RAG não é mágica: é quebrar texto, virar vetor e buscar bem. O passo a passo de um RAG do zero — chunking recursive com overlap, embeddings com text-embedding-3-small e busca por similaridade no Postgres com pgvector e índice HNSW. Errar o chunking é onde 80% dos RAGs nascem ruins.

RAG virou resposta automática pra tudo, e quase sempre é a escolha errada. O mapa de decisão entre RAG, fine-tuning e contexto pelos critérios que importam: volatilidade do dado, custo, rastreabilidade e tamanho.

O system prompt não é onde você manda o modelo ser legal. É a constituição do agente: papel, políticas, ferramentas e formato. Como estruturar um de produção e por que ele joga num campeonato diferente de um prompt de chat.