aws-agentic-ai-reference-architecture
Arquitetura de referência para IA agêntica na AWS que aguenta produção, não só demo
git clone https://github.com/fernando-moretes/app-aws-agentic-ai-reference-architecture.gitcerca de 4 min · áudio gerado ao tocar
Este repositório é a minha arquitetura de referência para IA agêntica na AWS. Ele cobre Amazon Bedrock, ferramentas via MCP, guardrails, identidade, observabilidade e esteira DevSecOps, e vem documentado em português e inglês, com ADRs, modelo de ameaças e testes.
Por que este repositório existe
A maioria das demos de IA termina numa tela de chat. Para quem desenha plataforma, a pergunta que importa não é "o agente responde?". É outra: "o que acontece quando a ferramenta que ele chama fica fora do ar, quando o modelo principal é limitado por throttling ou quando alguém tenta fazer o agente agir fora do escopo?".
Escrevi este blueprint para responder a essas perguntas antes de alguém precisar delas às duas da manhã. Ele documenta uma arquitetura que leva em conta o que a produção cobra: resiliência, segurança, controle de custo, visibilidade operacional, governança e integração com sistemas reais.
O foco são ambientes regulados. Lá, o custo de um agente não é o da primeira versão, é o de manter, auditar e corrigir as políticas dele por anos. Por isso o repositório traz, além do diagrama, os artefatos que uma revisão de arquitetura séria exige: ADRs, modelo de ameaças, revisão Well-Architected e checagens de CI.
Ele também é portfólio. A superfície pública em agentic-ai.moretes.com apresenta a arquitetura para quem quer entender o desenho sem clonar nada.
As cinco qualidades que o desenho persegue
O caminho de uma requisição pelo agente
Visão simplificada da arquitetura de referência. O diagrama completo está em docs/diagrams/architecture.mmd.
- IAM / identity broker · inbound + outbound authZ
- Bedrock Guardrails · policy enforcement
- Agent runtime · Lambda / ECS / AgentCore-style
- Amazon Bedrock · primary + fallback model
- Knowledge Bases / · OpenSearch Serverless
- MCP Tool Gateway · allow-listed tools
- Sistemas reais · Real systems
- EventBridge · HITL + audit events
- CloudWatch / X-Ray · OpenTelemetry
Como a arquitetura funciona
O desenho separa quatro responsabilidades que demos costumam misturar.
Identidade: a requisição entra por um identity broker em IAM, que resolve duas autorizações diferentes: quem pode falar com o agente (entrada) e com que credencial o agente fala com cada sistema (saída). Misturar as duas é o caminho mais curto para um agente com permissão de administrador.
Raciocínio: o runtime segue padrões de Lambda, ECS ou estilo Bedrock AgentCore, conforme a duração e o estado da sessão. A inferência vai para o Amazon Bedrock, com um modelo de fallback quando o principal falha. Bedrock Guardrails aplica a política de IA responsável na entrada e na saída. O RAG usa Bedrock Knowledge Bases ou OpenSearch Serverless.
Ação: o agente não chama sistema nenhum direto. Toda ferramenta passa por um MCP Tool Gateway com allow-list, que é onde ficam os retries com teto e os circuit breakers.
Operação: CloudWatch, X-Ray e OpenTelemetry registram traces, métricas e logs, incluindo cada chamada de ferramenta. O EventBridge carrega os eventos assíncronos: escalonamento para humano (human-in-the-loop) e trilha de auditoria.
O que tem dentro do repositório
São três camadas, cada uma com um papel distinto.
Documentação: docs/architecture.md é o documento principal, e docs/diagrams/architecture.mmd guarda o diagrama em Mermaid, versionado junto com o texto. Diagrama em imagem envelhece sem ninguém notar; em Mermaid, ele aparece no diff do PR. Os ADRs, o modelo de ameaças e a revisão Well-Architected ficam ao lado.
Pacote Python com testes: o repositório se instala como pacote editável e roda com pytest. É a parte que valida o que a documentação afirma, para a referência não virar texto que ninguém confere.
Frontend estático: a pasta frontend/ é uma superfície de portfólio com poucas dependências, pronta para deploy na Vercel. É ela que serve agentic-ai.moretes.com.
O OPERATIONS.md descreve o GitFlow, os segredos da Vercel e a esteira de segurança. Leia antes de abrir PR.
Como rodar localmente
- 1
Clone o repositório
git clone https://github.com/fernando-moretes/app-aws-agentic-ai-reference-architecture.gite entre na pasta. - 2
Instale o pacote Python e rode os testes
python -m pip install -e . pyteste depoispytest -q. Use um virtualenv para não sujar o Python do sistema. - 3
Construa o frontend
cd frontend,npm ci,npm run lintenpm run build. Usenpm ci, nãonpm install: ele respeita o lockfile e repete o que a CI faz. - 4
Leia a arquitetura na ordem certa
Comece por
docs/architecture.md, abra o diagrama emdocs/diagrams/architecture.mmde só então os ADRs e o modelo de ameaças. A decisão faz mais sentido depois que você viu o fluxo.
git clone https://github.com/fernando-moretes/app-aws-agentic-ai-reference-architecture.git
cd app-aws-agentic-ai-reference-architecture
python -m venv .venv && source .venv/bin/activate
python -m pip install -e . pytest
pytest -q
cd frontend
npm ci
npm run lint
npm run buildReferência, não infraestrutura pronta
Este repositório documenta e valida um desenho. Ele não provisiona Bedrock, OpenSearch nem EventBridge na sua conta. Trate cada componente como decisão a reproduzir no seu IaC, com os limites, as cotas e o regime regulatório do seu ambiente.
Perguntas frequentes
Por que passar as ferramentas por um gateway MCP em vez de deixar o agente chamar a API direto?
Porque é o único ponto onde allow-list, credencial de saída, retry com teto e circuit breaker ficam num lugar só. Sem ele, cada ferramenta nova reimplementa os quatro, e alguma vai esquecer um.
Lambda, ECS ou AgentCore para o runtime?
Depende da sessão. Use Lambda quando a interação é curta e sem estado. Use ECS quando o agente precisa de processo longo ou dependências pesadas. Use um runtime gerenciado estilo AgentCore quando memória de sessão e isolamento por sessão pesam mais que controle fino do container.
Knowledge Bases ou OpenSearch Serverless para RAG?
Knowledge Bases quando você quer menos peças para operar. OpenSearch Serverless quando precisa controlar índice, filtro e consulta, por exemplo para isolar tenants com filtro por tenantId.
Referências
Para quem é
Use este repositório quando você precisa defender uma arquitetura de agentes numa revisão de segurança ou de risco e quer um ponto de partida que já responde por identidade, fallback, auditoria e custo. Ele serve melhor a arquitetos e times de plataforma em ambiente regulado do que a quem quer um chatbot funcionando em uma tarde. Se o objetivo é um template de IaC para dar apply, ele não é isso: é o desenho e as decisões que o seu IaC deveria seguir.
Deep dives de arquitetura, AWS, IA e mercado: direto no seu email. Grátis.
Sem spam · cancele quando quiser