Arquitetura de agentes de IA: o blueprint de ponta a ponta

A semana inteira cabe em um diagrama. Cinco dias destrinchando modelo, tools, MCP, contexto, prompt, RAG, guardrails e observabilidade — as peças de uma arquitetura de agentes de IA de ponta a ponta. E tudo isso existe pra responder uma pergunta só: que agente você consegue defender numa code review sem ficar vermelho?

Porque demo qualquer um faz. Você cola três tools, escreve um prompt bonito, grava o vídeo e posta no LinkedIn. O problema é o que acontece quando esse mesmo agente encontra um input que você não previu, uma tool que dá timeout, um documento que não devia ter recuperado. Aí não é mais demo. É produção. E produção não perdoa arquitetura improvisada.

Neste post a gente fecha a semana juntando tudo num blueprint único: as seis camadas de uma arquitetura de agentes de IA de ponta a ponta, o que vai em cada uma, como elas conversam, e um checklist do que revisar antes de subir. Não é teoria. É o mapa que amarra os dezenove posts dos últimos dias num desenho que você consegue colar na parede do time.

TL;DR

O que é: o blueprint de referência de uma arquitetura de agentes de IA — as seis camadas (modelo, contexto, tools, memória/RAG, guardrails, observabilidade) e como elas se encaixam num fluxo de produção.
Stack/Modelos: agnóstico de modelo (Claude, GPT, Gemini). Exemplos no tom da casa: Laravel/PHP + Claude API + Postgres com pgvector.
Custo/Acesso: conceitual — todo o código de cada camada está nos posts linkados ao longo do texto.
Link útil: este post é o índice da semana. Cada camada aponta pro tutorial que a destrincha de verdade.

O contexto — por que arquitetura de agentes de IA virou a habilidade que separa dev de dev

Há um ano, "agente" era um loop de while com uma chamada de API no meio. Hoje, um agente que aguenta produção tem mais peça móvel que um microserviço — e a maioria dos times trata cada peça como se fosse opcional.

Não é. A própria Anthropic, no Building Effective Agents, bate na mesma tecla: a maior parte dos casos bons não é um agente mágico e autônomo, é um sistema com componentes simples, bem definidos, compostos com cuidado. O ganho não está em adicionar inteligência. Está em arquitetar as restrições.

É exatamente por isso que arquitetura de agentes de IA virou habilidade de gente sênior. Não porque é difícil escrever o código de cada parte — você viu nesta semana que cada peça, isolada, cabe em um post. É difícil porque exige decidir, para o seu problema, o que entra em cada camada e o que fica de fora. Esse é o trabalho. O resto é digitação.

E tem um teste simples pra saber se a sua arquitetura está de pé: você consegue desenhar o caminho de uma request, do input do usuário até a resposta, nomeando cada componente que ela atravessa e o que ele faz? Se consegue, você tem arquitetura. Se a resposta é "aí o modelo resolve", você tem um wrapper de prompt com sorte. A diferença entre os dois é o tema da semana inteira — e começou na definição de o que é um agente de IA, e o que é só um wrapper de prompt.

O blueprint: as seis camadas em um diagrama

Antes de abrir camada por camada, o desenho. Guarde essa imagem mental — o resto do post é só zoom em cada bloco.

                         ┌─────────────────────────────────────────────┐
                         │            6. OBSERVABILIDADE               │
                         │   (traces, custo por request, evals)        │
                         │   — envolve TODAS as camadas abaixo —       │
                         └─────────────────────────────────────────────┘
   ┌────────┐   input    ┌─────────────────────────────────────────────┐
   │usuário │ ─────────► │ 5. GUARDRAIL DE ENTRADA                     │
   └────────┘            │   (valida input, bloqueia injection)        │
        ▲                └───────────────────────┬─────────────────────┘
        │                                        ▼
        │                ┌─────────────────────────────────────────────┐
        │                │ 2. CONTEXTO                                 │
        │                │   system prompt + histórico + dado recuperado│
        │                └───────────────────────┬─────────────────────┘
        │                                        ▼
        │                ┌─────────────────────────────────────────────┐
        │                │ 1. MODELO  ──►  loop: decide / age / observa │
        │                └──────┬───────────────────────────┬──────────┘
        │                       ▼                            ▼
        │           ┌───────────────────────┐   ┌───────────────────────┐
        │           │ 3. TOOLS (via MCP)    │   │ 4. MEMÓRIA / RAG      │
        │           │  APIs, ações, escrita │   │  busca, embeddings,   │
        │           │                       │   │  histórico de longo   │
        │           └───────────────────────┘   └───────────────────────┘
        │                                        ▼
        │                ┌─────────────────────────────────────────────┐
        └─── resposta ───│ 5. GUARDRAIL DE SAÍDA                       │
                         │   (checa formato, política, alucinação)     │
                         └─────────────────────────────────────────────┘

Seis camadas. Duas delas (guardrails e observabilidade) não são etapas do fluxo — são camadas transversais que abraçam o resto. Esse é o erro de leitura mais comum: tratar segurança e observabilidade como "feature pra depois", quando na verdade elas envolvem todas as outras. Vamos de baixo pra cima.

Camada 1 e 2: o modelo e o que você coloca na frente dele

No centro está o modelo rodando um loop: ele recebe contexto, decide se responde ou age, executa, observa o resultado e decide de novo. Esse loop é o coração — e ele é mais simples do que o hype sugere. Dá pra construir um agente funcional batendo direto na Claude API, em PHP puro com Laravel, sem framework de agente nenhum, como mostramos no agente mínimo viável com Claude API + Laravel. Comece por aí antes de assinar qualquer abstração.

Mas o modelo só é tão bom quanto o que você bota na frente dele. E aqui mora a confusão mais cara da área: achar que "contexto" e "prompt" são a mesma coisa.

São três trabalhos diferentes:

Engenharia de contexto é decidir o que entra na janela e, principalmente, o que não entra. Contexto é orçamento, não armário. Encher de informação degrada a resposta em vez de melhorar — o tal do context rot. É o tema de engenharia de contexto: o que vai no prompt (e o que NÃO vai).
Engenharia de prompt é escrever a instrução como quem escreve contrato: papel, tarefa, restrição, formato de saída. Sem fórmula mágica, com exemplo few-shot quando paga o custo. O guia honesto de engenharia de prompt fecha esse ponto.
O system prompt é a constituição do agente — papel, políticas, ferramentas disponíveis, formato. Ele joga num campeonato diferente do prompt de chat, e estruturar um de produção é o assunto de system prompt de produção: a espinha dorsal do comportamento do agente.

Decisão de arquitetura aqui: o que é regra fixa (vai pro system prompt), o que é dinâmico do turno (vai no contexto da request) e o que é recuperado sob demanda (vem da camada 4). Misturar os três é a receita pra um agente caro e inconstante.

Camada 3: tools — onde o agente sai do chat e age no mundo

Um agente que só fala é um chatbot. O que separa um do outro é a capacidade de agir: chamar uma API, escrever no banco, disparar um e-mail. Isso é tool calling, e a anatomia desse loop — quando o modelo decide chamar uma ferramenta vs. responder direto, como desenhar contratos e schemas idempotentes — está em tool calling na prática.

O padrão que organizou esse caos foi o MCP. Antes dele, cada agente falava com cada ferramenta no seu próprio dialeto: integração N×M. O Model Context Protocol virou isso em N+M — o "USB-C dos agentes". Se o termo ainda é nebuloso, comece por o que é MCP, o protocolo que virou padrão de tools e depois suba o seu, expondo uma tool e um resource, com como criar seu primeiro MCP server.

E tem dois padrões de escala que quase ninguém implementa até queimar:

Progressive disclosure. Jogar 50 tools no contexto degrada a escolha do modelo e estoura tokens. A saída é carregar ferramenta sob demanda — o agente descobre o que precisa quando precisa. O padrão está em progressive disclosure: como não afogar seu agente em 50 ferramentas.
Programmatic tool calling. Chamar 12 tools uma a uma é lento, caro e entope o contexto com resultado intermediário. Deixar o agente escrever um código que orquestra as chamadas e devolve só a resposta vira o jogo — detalhado em programmatic tool calling.

Camada 4: memória e RAG — o que o agente sabe além do que está no prompt

O modelo tem conhecimento congelado no treino e uma janela de contexto finita. Tudo que é específico do seu domínio, recente ou grande demais pra caber no prompt mora aqui — na camada de recuperação e memória.

Primeiro, a decisão de não fazer RAG à toa. Ele virou resposta automática pra tudo e quase sempre é a escolha errada. O mapa entre RAG, fine-tuning e contexto — por volatilidade do dado, custo e rastreabilidade — está em quando usar RAG (e quando fine-tuning ou contexto resolvem melhor). E porque RAG não é memória — confundir os dois quebra o agente e infla a conta —, vale fechar o conceito com o que é RAG (e onde ele termina e a memória começa).

Decidiu que precisa? Então a engenharia importa, e é onde 80% dos RAGs nascem ruins:

O pipeline base — chunking com overlap, embeddings, busca por similaridade — está em RAG do zero: chunking, embeddings e busca que funciona.
Onde guardar isso sem assinar serviço gerenciado: o Postgres que você já tem resolve 80% do problema com pgvector.
Parecido não é relevante. A busca vetorial traz candidatos parecidos; o reranker reordena por relevância real antes de mandar pro modelo.
E quando a busca vira uma decisão do próprio agente — buscar ou não, o quê, quantas vezes — você entra no agentic RAG, tratando recuperação como mais uma tool.

Camada 5: guardrails — as cercas que separam demo de produção

Aqui começa o que demo nenhum tem. Um agente sem guardrails é um estagiário com acesso de admin e zero supervisão: funciona até o dia em que não funciona.

Guardrail mora em três pontos do fluxo, e por isso ele aparece duas vezes no diagrama — entrada e saída:

Entrada: valida o input antes de chegar no modelo. Prompt injection, dado fora de escopo, payload malformado.
Ação: restringe o que cada tool pode executar. A tool de escrita no banco não apaga; a de e-mail não manda pra fora do domínio.
Saída: checa o que o modelo produziu antes de devolver. Formato, política, alucinação.

A regra de ouro é que guardrail é código testável, não boa intenção no prompt. "Pedi pro modelo não fazer isso" não é controle. O desenho completo dessas cercas está em guardrails para agentes de IA: validando o que entra e o que sai.

Camada 6: observabilidade e evals — porque você não conserta o que não enxerga

A última camada é a que envolve todas as outras, e é a primeira que os times cortam quando o prazo aperta. Erro caro. Sem observabilidade, um agente em produção é uma caixa-preta que às vezes vira uma conta de US$ 3 mil e um loop infinito — literalmente os anti-patterns que catalogamos em 5 anti-patterns que quebram seu agente de IA em produção.

Observabilidade é trace de cada request (qual tool chamou, quanto custou, quanto demorou) mais avaliação contínua. E "funciona nos meus testes" não é avaliação. Eval honesto é golden set de falhas reais, métrica por etapa — recuperou certo? escolheu a tool certa? respondeu certo? — e LLM-as-judge usado com cautela. O método replicável está em avaliação de agentes de IA: como montar evals honestos.

O checklist de produção: o que revisar antes de subir

Esse é o asset pra colar no PR template. Se você não consegue marcar todos, o agente ainda é demo.

[ ] Modelo + loop: o ciclo decidir → agir → observar tem condição de parada? (sem isso, loop infinito)
[ ] Contexto: o que é fixo está no system prompt, o que é dinâmico está no turno, o que é grande é recuperado? Nada de despejar tudo na janela.
[ ] Prompt: instrução com papel, tarefa, restrição e formato de saída explícito.
[ ] Tools: cada tool tem schema validável, contrato claro e é idempotente onde precisa?
[ ] Tools em escala: mais de ~15 ferramentas? Progressive disclosure ligado.
[ ] RAG: você precisa mesmo de RAG, ou contexto/fine-tuning resolvia? Se precisa, tem reranker?
[ ] Memória: onde mora o estado de longo prazo, e ele está separado da recuperação?
[ ] Guardrail de entrada: input validado contra injection e escopo.
[ ] Guardrail de ação: cada tool tem o mínimo de privilégio e timeout.
[ ] Guardrail de saída: formato e política checados antes de devolver.
[ ] Observabilidade: trace por request, custo e latência medidos.
[ ] Evals: golden set rodando antes de cada deploy, não só na sua cabeça.

Doze itens. Cada um é uma camada do diagrama virando linha de revisão. É isso que significa "defender o agente numa code review": para cada item, você tem uma resposta que não é "confia".

Limitações e pontos de atenção

Esse blueprint é um mapa, não uma obrigação. O erro simétrico do "agente sem arquitetura" é o overengineering: montar as seis camadas pra um problema que um prompt bem escrito resolvia. Se a sua tarefa é classificar um texto em três categorias, você não precisa de RAG, MCP nem agentic loop. Precisa de uma chamada de API. Arquitetura é sobre proporção — adicione camada quando a dor justifica, não por completude.

Segundo ponto: as camadas não são fases sequenciais que você implementa uma vez e esquece. Elas evoluem juntas. Mudou o prompt? Roda os evals. Adicionou uma tool? Revisa o guardrail de ação. Tratar o blueprint como checklist único de setup, e não como disciplina contínua, é como escrever teste só no dia do deploy.

E o óbvio que precisa ser dito: nenhuma dessas camadas substitui entender o problema. A melhor arquitetura de agente em cima da pergunta errada entrega, com excelência técnica, a resposta que ninguém pediu.

FAQ rápido

Preciso implementar as seis camadas pra dizer que tenho um agente? Não. Você precisa do modelo + loop e de pelo menos tools ou contexto pra não ser um chatbot. Guardrails e observabilidade você adiciona quando sai do protótipo pra produção — mas adiciona, não pula.

Onde MCP entra nesse desenho? MCP é o protocolo da camada 3 (tools). Ele padroniza como o modelo descobre e chama ferramentas e acessa dados, sem você reescrever integração a cada ferramenta nova. É infraestrutura da camada, não uma camada separada.

RAG e memória são a mesma coisa no diagrama? Estão na mesma camada (4) porque ambos respondem "o que o agente sabe além do prompt", mas são coisas distintas: RAG é recuperação sob demanda de uma base; memória é estado que persiste entre conversas. Misturar os dois é um dos jeitos mais comuns de inflar custo.

Por que observabilidade aparece "envolvendo" tudo no desenho? Porque ela não é uma etapa do fluxo da request — é a instrumentação que atravessa todas as etapas. Você quer trace do contexto montado, da tool chamada, do dado recuperado e da saída, num request só. Por isso ela abraça o resto em vez de ficar no fim.

Conclusão

A semana inteira cabe nesse diagrama: modelo no centro, contexto e prompt na frente dele, tools e RAG nas laterais, guardrails e observabilidade abraçando tudo. Não é arquitetura sofisticada — é arquitetura explícita. A diferença entre o agente que você defende numa code review e o que você reza pra não cair em produção não está em nenhuma tecnologia nova. Está em saber nomear cada peça e justificar por que ela está (ou não está) ali.

Esse é o salto que a gente vem martelando: o próximo nível do dev não é usar IA. É arquitetar produto real com IA, com engenharia de verdade. Se você quer ver esse blueprint saindo do diagrama e virando código — decisões de arquitetura na mesa, sem slide motivacional —, é exatamente isso que a gente vai construir ao vivo no Workshop Arquitetando Soluções de IA.

Agora pega o checklist, abre o seu agente e marca item por item. O primeiro que você não conseguir marcar é o seu próximo post pra reler.