aws-agentic-ai-reference-architecture
AWS reference architecture for production agentic AI — security, observability, and DevSecOps.
git clone https://github.com/fernandofatech/aws-agentic-ai-reference-architecture.gitA bilingual, production-grade reference architecture for agentic AI workloads on AWS, covering Amazon Bedrock, MCP tool gateways, guardrails, identity, observability, and Well-Architected DevSecOps pipelines — built as a portfolio-quality blueprint for enterprise solution architects.
Why this exists
Most AI demos stop at a chat interface. They prove a model can respond — they do not prove the system can operate safely at scale inside a regulated enterprise. That gap is exactly what this repository addresses.
I built this to document and validate an AWS architecture that answers the hard questions: How do you enforce responsible-AI policies programmatically? How do you give an agent access to tools without opening an uncontrolled blast radius? How do you trace a multi-step reasoning chain back to a specific invocation for audit purposes? How do you contain costs when token consumption is non-deterministic?
The answers are encoded here as architecture decision records (ADRs), a threat model, a Mermaid diagram, and working code — not slides. The frontend is a lightweight static site deployed on Vercel that surfaces the documentation as a live portfolio artifact. The Python layer contains the testable logic: guardrail enforcement, tool allow-listing, and agent runtime patterns. Together they form a reference you can fork, adapt, and defend in a design review.
Architecture qualities
System architecture overview
Request flow from an end-user through the agentic runtime, tool gateway, knowledge base, and back — with guardrails and observability at every layer.
- End User · or App
- Static Portfolio · Vercel Deploy
- AWS IAM · Identity Broker
- Bedrock · Guardrails
- Agent · Orchestrator
- Amazon Bedrock · Foundation Model
- MCP Tool · Gateway
- Bedrock Knowledge · Bases / OpenSearch
- CloudWatch + X-Ray · + OpenTelemetry
- EventBridge · Audit / HITL
How the repository is structured
The repo has three distinct layers that work together but can be understood independently.
Python core (/ root): This is where the testable architecture logic lives. The package is installable with pip install -e . and the test suite runs with pytest. This layer encodes the agent runtime patterns — guardrail enforcement, tool allow-listing, retry/circuit-breaker logic — as Python modules you can inspect, extend, and validate in CI without an AWS account.
Frontend (/frontend): A dependency-light static site built with HTML, CSS, and JavaScript. It is the public-facing portfolio surface hosted at agentic-ai.moretes.com via Vercel. It renders the architecture documentation, diagrams, and ADRs in a readable form. Build it with npm ci && npm run build; linting is enforced before build.
Documentation (/docs): Architecture decision records, the threat model, and the Mermaid diagram source (docs/diagrams/architecture.mmd) live here. The diagram is the canonical visual reference — if you want to understand the system at a glance, start there.
Operations (OPERATIONS.md): GitFlow branching strategy, Vercel secret management, and the security pipeline configuration are documented here. The CI pipeline includes security checks that run on every pull request, keeping the codebase aligned with DevSecOps practices rather than treating security as a post-deployment concern.
Installation and local usage
- 1
Clone the repository
Clone locally and move into the project root. You will need Python 3.9+ and Node.js 18+ available on your PATH.
- 2
Install the Python package and run tests
Install the package in editable mode and run the test suite. No AWS credentials are required for the unit tests — the architecture logic is validated locally.
- 3
Build the frontend
Move into the frontend directory, install dependencies with npm ci (clean install, respects lockfile), run the linter, then build the static site. The output is ready for Vercel deployment.
- 4
Review the architecture diagram
Open docs/diagrams/architecture.mmd in any Mermaid-compatible viewer (GitHub renders it natively, or use the Mermaid Live Editor). This is the canonical visual reference for the system design.
- 5
Read OPERATIONS.md for CI/CD and secrets setup
OPERATIONS.md documents the GitFlow branching model, how to configure Vercel environment secrets, and the security pipeline steps. Follow this before pushing to a fork or setting up your own deployment.
# 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.mmdOn the MCP Tool Gateway
The Model Context Protocol (MCP) tool gateway is one of the less-obvious but more important design decisions here. Rather than giving the agent open access to AWS APIs or external services, all tool calls are routed through a controlled gateway that enforces an allow-list. This means a compromised or hallucinating model cannot invoke arbitrary actions — it can only call tools that have been explicitly permitted for that agent's scope. Combined with IAM least-privilege on the gateway itself, this is the primary blast-radius containment mechanism for the agentic layer.
Common questions
Do I need an AWS account to explore this repository?
No. The Python test suite and the frontend build run entirely locally. The architecture documentation and diagrams are static. You only need AWS credentials if you intend to deploy the actual infrastructure described in the ADRs.
Is this a deployable IaC project or a reference/documentation project?
It is primarily a reference architecture — the value is in the documented decisions, patterns, and testable logic, not in a one-click deploy. Think of it as the blueprint and rationale you would produce before writing CDK or Terraform. The Python modules validate the logic; the docs validate the design.
Why Vercel for a portfolio site about AWS architecture?
The frontend is a static documentation surface, not part of the architecture being described. Using Vercel keeps the deployment of the portfolio itself simple and separate from the AWS workload patterns. It is a deliberate separation of concerns — the docs site does not need to run on the same stack it documents.
What does 'bilingual' mean in practice for this repo?
The README, architecture documentation, and the live portfolio site are maintained in both English and Portuguese. This reflects my work context across Brazil and international teams, and makes the reference accessible to Portuguese-speaking architects who are underserved by English-only AWS content.
Who this is for and when to use it
This repository is useful in three scenarios. First, if you are an AWS solutions architect designing an agentic AI platform and need a documented starting point that covers security, observability, reliability, and cost — not just model invocation — the ADRs and architecture diagram give you a defensible baseline to adapt. Second, if you are evaluating a candidate or vendor who claims AWS and AI expertise, this is the kind of artifact that separates architects who have thought through production constraints from those who have only run demos. Third, if you are learning enterprise AI architecture on AWS, the combination of working Python tests, a threat model, and a Well-Architected lens applied to agentic workloads is a more grounded starting point than most public tutorials. What it is not: a production-ready IaC module you deploy today. It is a reference and a blueprint. The infrastructure code is implied by the ADRs and patterns, not provided as ready-to-apply Terraform or CDK. If you need that next step, the architecture documented here gives you the design decisions you would need to implement it correctly.