aws-agentic-ai-reference-architecture

Most AI demos stop at the chat UI. It works in the video, it works in the meeting, and the question nobody asks is the one that matters: who operates this agent at 2 AM when it loops calling the same tool for the fortieth time?

This repository grew out of that question. After years operating platforms in regulated environments, I learned that an agent in production is not a model with access to functions — it's a distributed system with a non-deterministic component in the middle. It needs what every other distributed system needs: bounded retries, a circuit breaker, a fallback path, an audit trail, a cost ceiling and a human with veto power.

The goal here is not an installable product. It's a blueprint: the design, the decisions recorded as ADRs, the threat model, the review against the Well-Architected pillars and the pipeline that validates all of it on every commit. Someone arriving to design an agent platform on AWS finds the skeleton ready to adapt — and, more importantly, finds the reasoning behind each choice, which is what actually gets lost when a project changes hands.

The published version at agentic-ai.moretes.com is the reading surface; the repository is the source, with the diagram in docs/diagrams/architecture.mmd and the documentation in docs/architecture.md.

Identity boundary: nothing reaches the agent without passing the identity broker, and nothing leaves the agent toward an internal system without a credential scoped to that call. This separates two questions that usually get conflated — "may this user talk to the agent?" and "may this agent call this API on behalf of this user?". A single execution role for all traffic answers both with "yes" and eliminates the isolation.

Guardrails ahead of the runtime: Bedrock Guardrails evaluates the inbound prompt and the outbound response. Keeping that step outside the agent's code means the responsible-AI policy is auditable as configuration, not as emergent behavior hidden in a system prompt.

MCP Tool Gateway with an allow-list: the agent doesn't discover tools; it receives a list. Every tool invocation emits its own telemetry, which answers the most common incident question — "what exactly did the agent do?" — without reconstructing the reasoning from the model's log.

EventBridge for what is asynchronous: human approval and audit trails don't fit the synchronous cycle of a request. Emitting an event and letting the agent wait for the verdict is what allows a human to decide without holding a connection open.

What separates this design from a demo is the part that only shows up when something fails. Bounded retries and a circuit breaker on every model and tool call: an agent with no iteration ceiling consumes tokens indefinitely, and the breaker is what keeps one degraded tool from taking the rest down. A fallback model strategy: when the primary model answers with throttling or unavailability, routing drops to a second model instead of returning an error to the user. Human escalation as a first-class path, not a caught exception.

On cost, the rule is the same as on any platform I spent years operating: what hurts is not the first month's bill — it's the cost of maintaining, auditing and fixing over years. That's why the design carries a token budget per request and per period, model routing by task complexity and caching of responses and retrieved context. None of the three is new; the difference is treating them as part of the architecture, with a metric and an alarm, rather than as an optimization for later.

All of it is recorded in ADRs, a threat model and a review against the Well-Architected pillars, and the CI pipeline runs the checks on every commit. GitFlow, Vercel secrets and the security pipeline details live in OPERATIONS.md.