# aws-agentic-ai-reference-architecture Arquitetura de referência para IA agêntica na AWS que aguenta produção, não só demo - URL: https://fernando.moretes.com/open-source/aws-agentic-ai-reference-architecture - Markdown: https://fernando.moretes.com/open-source/aws-agentic-ai-reference-architecture/guide.md?lang=pt - GitHub: https://github.com/fernando-moretes/app-aws-agentic-ai-reference-architecture - Homepage: https://agentic-ai.moretes.com - Language: HTML - Topics: agentic-ai, ai, aws, bedrock, devsecops, guardrails, mcp, moretes, observability, portfolio, solution-architecture, vercel, well-architected - Stars: 1 - Forks: 0 - Updated: 2026-09-29T16:21:29Z --- 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](https://agentic-ai.moretes.com) apresenta a arquitetura para quem quer entender o desenho sem clonar nada. ## As cinco qualidades que o desenho persegue - **Segurança primeiro:** allow-list de ferramentas, fronteira de identidade, guardrails e eventos de auditoria. - **Confiabilidade:** retries com teto, circuit breakers, estratégia de modelo de fallback e escalonamento para humano. - **Observabilidade:** traces do raciocínio, telemetria de cada chamada de ferramenta e sinais de avaliação de qualidade. - **Custo sob controle:** orçamento de tokens, roteamento de modelo e estratégia de cache. - **Pronto para governança:** ADRs, modelo de ameaças, revisão Well-Architected e checagens de CI. ## 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`. ### 🔐 AWS: identidade e política - IAM / identity broker inbound + outbound authZ (security) - Bedrock Guardrails policy enforcement (security) ### 🤖 AWS: runtime do agente - Agent runtime Lambda / ECS / AgentCore-style (compute) - Amazon Bedrock primary + fallback model (ai) - Knowledge Bases / OpenSearch Serverless (data) ### 🔧 Ferramentas - MCP Tool Gateway allow-listed tools (edge) - Sistemas reais Real systems (external) ### 📡 AWS: operação e auditoria - EventBridge HITL + audit events (messaging) - CloudWatch / X-Ray OpenTelemetry (compute) ### Fluxos - user -> idb: autentica - idb -> runtime: identidade propagada - runtime -> guard: entrada e saída filtradas - runtime -> bedrock: inferência com orçamento de tokens - runtime -> rag: recupera contexto - runtime -> mcp: chama ferramenta permitida - mcp -> sys: credencial de saída - runtime -> eb: escala para humano / audita - runtime -> obs: traces e métricas ## 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](https://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.git` e entre na pasta. 2. **Instale o pacote Python e rode os testes**: `python -m pip install -e . pytest` e depois `pytest -q`. Use um virtualenv para não sujar o Python do sistema. 3. **Construa o frontend**: `cd frontend`, `npm ci`, `npm run lint` e `npm run build`. Use `npm ci`, não `npm 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 em `docs/diagrams/architecture.mmd` e só então os ADRs e o modelo de ameaças. A decisão faz mais sentido depois que você viu o fluxo. _Quickstart: testes do pacote e build do frontend_ ```bash 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 build ``` > **Referê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 - [GitHub: fernando-moretes/app-aws-agentic-ai-reference-architecture](https://github.com/fernando-moretes/app-aws-agentic-ai-reference-architecture) - [Portfólio ao vivo / Live portfolio: agentic-ai.moretes.com](https://agentic-ai.moretes.com) - [Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) - [AWS Well-Architected Generative AI Lens](https://docs.aws.amazon.com/wellarchitected/latest/generative-ai-lens/generative-ai-lens.html) - [Model Context Protocol](https://modelcontextprotocol.io) ## 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. ## Links - [GitHub repository](https://github.com/fernando-moretes/app-aws-agentic-ai-reference-architecture) - [Homepage](https://agentic-ai.moretes.com)