# aws-agentic-ai-reference-architecture Arquitetura de referência AWS para agentes de IA em produção — segurança, observabilidade e DevSecOps. - 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/fernandofatech/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-05-16T02:23:08Z --- Uma arquitetura de referência bilíngue e pronta para produção para workloads de IA agêntica na AWS, cobrindo Amazon Bedrock, MCP tool gateways, guardrails, identidade, observabilidade e pipelines DevSecOps alinhados ao Well-Architected Framework — construída como um blueprint de qualidade de portfólio para arquitetos de soluções enterprise. ## Por que este projeto existe A maioria das demos de IA para no chat. Elas provam que o modelo responde — não provam que o sistema opera com segurança em escala dentro de uma empresa regulada. Essa lacuna é exatamente o que este repositório endereça. Construí este projeto para documentar e validar uma arquitetura AWS que responde às perguntas difíceis: Como aplicar políticas de IA responsável de forma programática? Como dar a um agente acesso a ferramentas sem abrir um raio de explosão descontrolado? Como rastrear uma cadeia de raciocínio multi-etapa até uma invocação específica para fins de auditoria? Como conter custos quando o consumo de tokens é não-determinístico? As respostas estão codificadas aqui como Architecture Decision Records (ADRs), um modelo de ameaças, um diagrama Mermaid e código funcional — não slides. O frontend é um site estático leve implantado no Vercel que expõe a documentação como um artefato de portfólio ao vivo. A camada Python contém a lógica testável: aplicação de guardrails, allow-listing de ferramentas e padrões de runtime de agentes. Juntos, formam uma referência que você pode fazer fork, adaptar e defender em uma revisão de design. ## Qualidades da arquitetura - **Segurança em primeiro lugar:** allow-listing de ferramentas, aplicação de fronteiras de identidade, Bedrock Guardrails para políticas de IA responsável e eventos de auditoria via EventBridge. - **Confiável por design:** retries limitados, circuit breakers, estratégia de fallback de modelo e caminho de escalação humana. - **Observável:** traces de raciocínio, telemetria de invocação de ferramentas e sinais de avaliação de qualidade via CloudWatch, X-Ray e OpenTelemetry. - **Consciente de custos:** orçamentos de tokens, roteamento de modelos e estratégia de cache para conter gastos não-determinísticos. - **Pronto para enterprise:** ADRs, modelo de ameaças, checklist de revisão Well-Architected e verificações de segurança no CI. - **Documentação bilíngue:** todo o conteúdo de arquitetura é mantido em inglês e português, refletindo necessidades reais de times multi-região. ## Visão geral da arquitetura do sistema Fluxo de requisição do usuário final pelo runtime agêntico, gateway de ferramentas, base de conhecimento e retorno — com guardrails e observabilidade em cada camada. ### 👤 User / Client - End User or App (user) ### 🌐 Frontend (Vercel) - Static Portfolio Vercel Deploy (frontend) ### 🔒 Security Layer - AWS IAM Identity Broker (security) - Bedrock Guardrails (security) ### 🤖 Agentic Runtime (Lambda / ECS) - Agent Orchestrator (compute) - Amazon Bedrock Foundation Model (ai) - MCP Tool Gateway (compute) ### 🗄️ Knowledge & Data - Bedrock Knowledge Bases / OpenSearch (data) ### 📡 Observability & Events - CloudWatch + X-Ray + OpenTelemetry (external) - EventBridge Audit / HITL (messaging) ### Fluxos - user -> frontend: visualiza docs - user -> iam: autentica - iam -> agent: requisição autorizada - agent -> guardrails: verificação de política - agent -> bedrock: invocação do modelo - bedrock -> agent: raciocínio / resposta - agent -> mcp: chamada de ferramenta (allow-listed) - mcp -> agent: resultado da ferramenta - agent -> kb: recuperação RAG - agent -> otel: traces / métricas / logs - agent -> eventbridge: evento de auditoria / HITL ## Como o repositório está estruturado O repositório tem três camadas distintas que funcionam juntas, mas podem ser entendidas de forma independente. **Core Python (raiz `/`):** Aqui vive a lógica de arquitetura testável. O pacote é instalável com `pip install -e .` e o conjunto de testes roda com `pytest`. Esta camada codifica os padrões de runtime do agente — aplicação de guardrails, allow-listing de ferramentas, lógica de retry/circuit-breaker — como módulos Python que você pode inspecionar, estender e validar no CI sem uma conta AWS. **Frontend (`/frontend`):** Um site estático com poucas dependências, construído com HTML, CSS e JavaScript. É a superfície de portfólio pública hospedada em `agentic-ai.moretes.com` via Vercel. Renderiza a documentação de arquitetura, diagramas e ADRs de forma legível. Construa com `npm ci && npm run build`; o linting é aplicado antes do build. **Documentação (`/docs`):** Architecture Decision Records, o modelo de ameaças e o diagrama Mermaid (`docs/diagrams/architecture.mmd`) ficam aqui. O diagrama é a referência visual canônica — se você quer entender o sistema rapidamente, comece por ele. **Operações (`OPERATIONS.md`):** Estratégia de branching GitFlow, gerenciamento de secrets no Vercel e configuração do pipeline de segurança estão documentados aqui. O pipeline de CI inclui verificações de segurança em cada pull request, mantendo o codebase alinhado com práticas DevSecOps. ## Instalação e uso local 1. **Clone o repositório** — Clone localmente e entre na raiz do projeto. Você precisará de Python 3.9+ e Node.js 18+ disponíveis no PATH. 2. **Instale o pacote Python e execute os testes** — Instale o pacote em modo editável e execute o conjunto de testes. Credenciais AWS não são necessárias para os testes unitários — a lógica de arquitetura é validada localmente. 3. **Construa o frontend** — Entre no diretório frontend, instale as dependências com npm ci (instalação limpa, respeita o lockfile), execute o linter e construa o site estático. A saída está pronta para deploy no Vercel. 4. **Revise o diagrama de arquitetura** — Abra docs/diagrams/architecture.mmd em qualquer visualizador compatível com Mermaid (o GitHub renderiza nativamente, ou use o Mermaid Live Editor). Este é o referencial visual canônico para o design do sistema. 5. **Leia OPERATIONS.md para configuração de CI/CD e secrets** — OPERATIONS.md documenta o modelo de branching GitFlow, como configurar secrets de ambiente no Vercel e os passos do pipeline de segurança. Siga isso antes de fazer push para um fork ou configurar seu próprio deploy. _Quick start: instalar, testar e construir_ ```bash # 1. Clone git clone https://github.com/fernandofatech/aws-agentic-ai-reference-architecture.git cd aws-agentic-ai-reference-architecture # 2. Python: install in editable mode and run tests python -m pip install -e . pytest pytest -q # 3. Frontend: install deps, lint, build cd frontend npm ci npm run lint npm run build # 4. View architecture diagram (Mermaid) # Open in GitHub or paste into https://mermaid.live cat docs/diagrams/architecture.mmd ``` > **Sobre o MCP Tool Gateway:** O gateway de ferramentas MCP (Model Context Protocol) é uma das decisões de design menos óbvias, mas mais importantes aqui. Em vez de dar ao agente acesso aberto a APIs da AWS ou serviços externos, todas as chamadas de ferramentas são roteadas por um gateway controlado que aplica um allow-list. Isso significa que um modelo comprometido ou alucinando não pode invocar ações arbitrárias — ele só pode chamar ferramentas explicitamente permitidas para o escopo daquele agente. Combinado com IAM de menor privilégio no próprio gateway, este é o principal mecanismo de contenção do raio de explosão para a camada agêntica. ## Perguntas frequentes ### Preciso de uma conta AWS para explorar este repositório? Não. O conjunto de testes Python e o build do frontend rodam completamente localmente. A documentação de arquitetura e os diagramas são estáticos. Você só precisa de credenciais AWS se pretende implantar a infraestrutura real descrita nos ADRs. ### Este é um projeto IaC implantável ou um projeto de referência/documentação? É primariamente uma arquitetura de referência — o valor está nas decisões documentadas, padrões e lógica testável, não em um deploy com um clique. Pense nisso como o blueprint e a justificativa que você produziria antes de escrever CDK ou Terraform. Os módulos Python validam a lógica; os docs validam o design. ### Por que Vercel para um site de portfólio sobre arquitetura AWS? O frontend é uma superfície de documentação estática, não parte da arquitetura sendo descrita. Usar o Vercel mantém o deploy do portfólio simples e separado dos padrões de workload AWS. É uma separação deliberada de responsabilidades — o site de docs não precisa rodar na mesma stack que documenta. ### O que 'bilíngue' significa na prática para este repositório? O README, a documentação de arquitetura e o site de portfólio ao vivo são mantidos em inglês e português. Isso reflete meu contexto de trabalho no Brasil e em times internacionais, e torna a referência acessível a arquitetos falantes de português que são mal atendidos por conteúdo AWS exclusivamente em inglês. ## Para quem é e quando usar Este repositório é útil em três cenários. Primeiro, se você é um arquiteto de soluções AWS projetando uma plataforma de IA agêntica e precisa de um ponto de partida documentado que cubra segurança, observabilidade, confiabilidade e custo — não apenas invocação de modelo — os ADRs e o diagrama de arquitetura fornecem uma baseline defensável para adaptar. Segundo, se você está avaliando um candidato ou fornecedor que afirma expertise em AWS e IA, este é o tipo de artefato que separa arquitetos que pensaram nas restrições de produção daqueles que apenas executaram demos. Terceiro, se você está aprendendo arquitetura de IA enterprise na AWS, a combinação de testes Python funcionais, um modelo de ameaças e uma lente Well-Architected aplicada a workloads agênticos é um ponto de partida mais sólido do que a maioria dos tutoriais públicos. O que não é: um módulo IaC pronto para produção que você implanta hoje. É uma referência e um blueprint. O código de infraestrutura está implícito nos ADRs e padrões, não fornecido como Terraform ou CDK prontos para aplicar. Se você precisa desse próximo passo, a arquitetura documentada aqui fornece as decisões de design necessárias para implementá-la c ## Links - [GitHub Repository — fernandofatech/aws-agentic-ai-reference-architecture](https://github.com/fernandofatech/aws-agentic-ai-reference-architecture) - [Live Portfolio Site — agentic-ai.moretes.com](https://agentic-ai.moretes.com) - [Amazon Bedrock — AWS Documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) - [Amazon Bedrock Guardrails — AWS Documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) - [Model Context Protocol (MCP) — Anthropic](https://modelcontextprotocol.io/) - [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html) - [Mermaid Live Editor — diagram viewer](https://mermaid.live) ## Links - [GitHub repository](https://github.com/fernandofatech/aws-agentic-ai-reference-architecture) - [Homepage](https://agentic-ai.moretes.com)