Arquitetura de agentes de IA: o blueprint em 6 camadas

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.

Agente de IA: definição, passo a passo e blueprint — onde este post entra

Antes de descer no diagrama, um mapa de intenção. "Agente de IA" é um assunto com três perguntas bem diferentes por baixo, e misturar as três é o motivo de muita gente ler três horas de conteúdo e continuar sem saber o que codar.

A divisão é proposital. O primeiro é a definição — conceito, critério, o teste que diz se aquilo que você chama de agente é agente mesmo. O segundo é o passo a passo: loop de raciocínio, tool calling e memória, em código, do zero. Este aqui é o blueprint: o desenho que você faz antes da primeira linha e o checklist que você usa depois da última.

Na prática o caminho é esse: leia a definição pra parar de chamar tudo de agente, faça o passo a passo pra ter um agente vivo na sua máquina, e volte pra cá quando esse agente precisar sair do seu notebook e encarar usuário de verdade. É aqui que entram as camadas que o tutorial de fim de semana não cobre — guardrail, recuperação, memória persistente, trace e eval.

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:

1. Entrada: valida o input antes de chegar no modelo. Prompt injection, dado fora de escopo, payload malformado.
2. 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.
3. 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.

Do problema ao diagrama: preenchendo as seis caixas

Diagrama genérico não decide nada. Ele só começa a valer quando você troca os rótulos pelas suas coisas: o seu banco, a sua API, o seu usuário. O exercício abaixo é o que eu faço em toda arquitetura nova, e leva uns 20 minutos por problema — muito menos do que as duas semanas que você perde codando a camada errada.

Comece pelo template. Seis caixas, uma linha de resposta cada. Se você não consegue preencher uma, você não tem arquitetura ainda: tem um palpite.

PROBLEMA: ..............................................................

[1] ENTRADA / ROTEAMENTO  quem dispara? (usuário, webhook, cron, fila)
    o caminho é decidido por código (if/switch) ou pelo modelo?
    ....................................................................

[2] MODELO                qual é a tarefa que SÓ o modelo faz?
    (se um regex ou um if resolve, tire daqui)
    ....................................................................

[3] TOOLS                 que ações no mundo? quais leem, quais escrevem?
    ....................................................................

[4] RECUPERAÇÃO           que dado não cabe no prompt? de onde vem?
    ....................................................................

[5] MEMÓRIA               o que precisa sobreviver ao fim do turno?
    ....................................................................

[6] OBSERVABILIDADE       o que você olha às 3h da manhã quando quebrar?
    ....................................................................

Três regras de preenchimento que economizam retrabalho. Primeira: roteamento é código até provar o contrário. Se você já sabe, pelo payload, qual fluxo executar, um switch faz isso em 0 ms e 0 token — não gaste uma chamada de LLM pra decidir o que um if decide. Segunda: toda escrita no banco é tool, nunca texto. O modelo devolve os argumentos, o seu código valida e executa. Terceira: recuperação e memória são caixas separadas mesmo quando moram na mesma instância de Postgres — uma responde "o que existe na base", a outra "o que já aconteceu com esse usuário".

Agora três problemas reais, desenhados do zero.

Problema 1: suporte que responde em cima da documentação do produto

PROBLEMA: responder dúvida de cliente usando a doc do produto (900 páginas)

[1] ENTRADA      widget do site -> job na fila (Laravel Horizon)
                 roteamento por CÓDIGO: pergunta técnica -> agente;
                 pedido de cancelamento -> humano, sem passar pelo modelo
[2] MODELO       redigir a resposta ancorada nos trechos recuperados
[3] TOOLS        abrir_ticket() (escrita), consultar_plano_do_cliente() (leitura)
[4] RECUPERAÇÃO  Postgres + pgvector: doc chunkada, top_k=20 -> reranker -> 5
[5] MEMÓRIA      últimas 5 mensagens da conversa, em tabela relacional comum
[6] OBSERVABILIDADE  trace com os 5 chunks usados + "resolveu?" do usuário

Onde entra cada um: o código do dev faz o roteamento inicial, o corte de escopo e a validação da resposta antes de devolver — nada disso é decisão do modelo. O banco aparece duas vezes: como store vetorial dos chunks (900 páginas em pedaços de ~500 tokens com overlap de 50 dão algo perto de 4 mil chunks) e como tabela relacional do histórico. O modelo faz uma coisa só: escrever a resposta em cima do que foi recuperado, citando a fonte.

O detalhe que separa isso de um RAG de demo é o reranker. Buscar top_k=5 direto no vetor parece econômico e é justamente o que produz a resposta errada com cara de certa: similaridade de embedding traz o parecido, não o relevante. Buscar 20 e reordenar por relevância antes de montar o contexto custa uma chamada a mais e derruba a maior parte das respostas fora de tema.

Problema 2: conciliação de faturas no fechamento do mês

PROBLEMA: conciliar 3.000 lançamentos do extrato com as faturas do ERP

[1] ENTRADA      cron 1x/dia; o LOTE é dividido por CÓDIGO, não pelo modelo
[2] MODELO       só os casos ambíguos: nome do fornecedor não bate,
                 valor divergente por centavos, pagamento agrupado
[3] TOOLS        buscar_fatura(), marcar_conciliado(), abrir_pendencia()
                 -> escrita SEMPRE com structured output validado por schema
[4] RECUPERAÇÃO  nenhuma busca vetorial. É SQL. Não force RAG aqui.
[5] MEMÓRIA      tabela de decisões anteriores: "esse CNPJ = esse fornecedor"
[6] OBSERVABILIDADE  custo por lote e taxa de reversão humana por regra

Esse é o caso onde a maior parte do trabalho não é do modelo. Match exato de valor e documento é JOIN. Se 3.000 lançamentos entram e 2.700 casam por regra determinística, sobram 300 pro agente — e a conta de tokens cai junto na mesma proporção. O erro clássico é jogar os 3.000 no modelo "porque ele resolve", pagar dez vezes mais e ainda introduzir erro em linha que o SQL acertaria sozinho.

O banco aqui não é vetorial: é o ERP e a tabela de aprendizado (fornecedor_alias), que é memória de verdade — cresce a cada fechamento e reduz o volume ambíguo do mês seguinte. O código do dev carrega o guardrail de ação mais importante do sistema: marcar_conciliado() só aceita um par (lançamento, fatura) com diferença dentro da tolerância configurada, e qualquer coisa fora disso vira pendência humana. O modelo pode errar; a tool não deixa o erro virar lançamento contábil.

Problema 3: triagem e roteamento de tickets internos

PROBLEMA: classificar ticket que chega no e-mail e mandar pro time certo

[1] ENTRADA      webhook do e-mail -> normaliza -> guardrail de tamanho/anexo
[2] MODELO       classificar em {infra, billing, bug, acesso, outros}
                 + extrair sistema afetado e urgência (structured output)
[3] TOOLS        criar_ticket(), notificar_time() — as duas idempotentes
                 por message-id, pra reprocessamento não duplicar
[4] RECUPERAÇÃO  runbooks internos, só quando a classe for "infra"
[5] MEMÓRIA      nenhuma. Cada ticket é independente. Não invente estado.
[6] OBSERVABILIDADE  matriz de confusão contra a classe final corrigida pelo time

Aqui o desenho é honesto sobre o que não entra. Sem memória, porque ticket não é conversa. Recuperação condicional, porque puxar runbook pra um ticket de billing só polui contexto e paga token à toa. E a caixa 6 é o coração desse sistema: como o time corrige a classe errada na mão, você ganha de graça um golden set crescente — cada correção humana vira um caso de eval.

O modelo entrega JSON com schema fixo, não prosa. O código do dev decide o roteamento a partir desse JSON e é ele quem chama a API do sistema de tickets, com idempotência por message-id — porque webhook reenvia, e reenvio sem idempotência é como se ganham três tickets iguais às 2h da manhã. O banco aqui é só a tabela de tickets do sistema que já existe. Nenhum vetor, nenhuma migração nova.

Repare no padrão dos três: o modelo faz cada vez menos coisa conforme o desenho amadurece. Isso não é rebaixar a IA — é o que torna o sistema barato, testável e defensável. Se você quer ver o caminho inverso (do zero até o primeiro agente vivo, com loop e tool calling em código), o passo a passo está em como criar um agente de IA do zero; volte pra cá com ele rodando e preencha as seis caixas.

O diagrama acima é o entregável do dia 1 do Lab. Na 3ª edição do AI Engineering Lab a gente faz exatamente esse exercício com o seu problema na mesa — e depois codifica as caixas que dão trabalho: tool calling, structured output, roteamento, memória, grounding, tracing, evals e custo por request. 19 e 20/09/2026, 9h às 13h, online ao vivo no Google Meet. Lote 1 por R$ 37. Ver o programa do AI Engineering Lab

Checklist de produção de agentes de IA

Esse é o asset pra colar no PR template. Ele tem heading próprio de propósito: é pra você linkar direto essa seção quando alguém do time perguntar "falta o quê pra subir?". 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".

Se você travou em três ou quatro itens dessa lista — quase sempre guardrail de saída, tracing e eval, na minha experiência —, é esse buraco específico que a 3ª edição do AI Engineering Lab fecha. Dois dias montando a arquitetura em cima de tool calling, structured output, roteamento, memória, grounding, tracing, evals e custo, com código rodando e não slide. 19 e 20/09/2026, 9h às 13h, ao vivo no Google Meet, Lote 1 a R$ 37. Garantir a vaga no Lote 1

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.

Qual a diferença entre este post e um tutorial de "como criar um agente de IA"? Escopo. O tutorial te dá um agente rodando: loop, tool calling e memória em código — é o como criar um agente de IA do zero. Este post é o desenho que decide quais peças o seu problema pede e o checklist que diz se aquilo aguenta produção. E se a dúvida ainda é conceitual, o que é um agente de IA fecha a definição.

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.