🧬 Agentic AI Well Architected

⚡Executive Summary

Agentic AI Well Architected is an interactive demo application that teaches agentic AI best practices on AWS through side-by-side comparisons. Follow the story of AnyCompany building SupportBot - a GenAI-powered customer support assistant - from first prototype to enterprise product. Each of the 20 pillars tackles a different challenge, showing a naive approach alongside an AWS best-practice implementation with live Amazon Bedrock calls. Covers 4 layers (Model, Guardrail, Orchestration, Platform), 6 foundation models, Bedrock Guardrails with Automated Reasoning (35 formal logic rules), RAG with Knowledge Bases, multi-agent orchestration via Strands Agents, AgentCore primitives (Gateway, Memory, Policy, Evaluation, Observability), SSO authentication via Cognito, and full audit logging. All infrastructure defined in CDK.

📋Situation

The Industry-Wide Problem

Enterprise teams adopting generative AI and agentic patterns face a steep learning curve. AWS offers powerful primitives - Bedrock models, Guardrails, Knowledge Bases, AgentCore (Gateway, Memory, Policy, Evaluation, Observability) - but understanding when and how to apply each one requires deep expertise. Teams either skip best practices entirely (shipping unsafe, unobservable prototypes) or spend months reading documentation without seeing the real-world impact of each decision.

The Learning Gap

• Theory vs. Practice: Documentation explains what each service does, but not what happens when you skip it - teams need to see the naive approach fail before the best practice clicks
• Isolated Examples: Each AWS service has standalone samples, but no single application shows how prompt engineering, guardrails, RAG, agents, authentication, policy, evaluation, and observability work together end-to-end
• No Measurable Comparison: Without side-by-side execution, teams cannot quantify the difference in quality, cost, latency, and safety between naive and well-architected approaches
• Security Blind Spots: Prompt injection, missing RBAC, no content filtering, and unverified factual claims are common in prototypes but hard to demonstrate without a controlled environment
• AgentCore Adoption Barrier: Gateway, Memory, Policy, Evaluation, and Observability are powerful but unfamiliar - teams need working examples, not just API references
• No Continuous Narrative: Existing demos are disconnected one-offs. Real architecture decisions compound - a choice in prompt engineering affects security, which affects reliability, which affects observability

🎯Task

The Challenge: Making Best Practices Tangible

The goal was to build a comprehensive interactive tutorial where every pillar of agentic AI architecture is demonstrated through side-by-side comparison - send the same prompt through a naive implementation and a best-practice implementation, see both results in real time, and understand exactly what changed and why it matters.

• 20 Pillars Across 4 Layers: Cover Model, Guardrail, Orchestration, and Platform concerns with a continuous narrative following AnyCompany's SupportBot from prototype to production
• 77 Pre-configured Scenarios: Story-driven prompts that continue the same narrative across pillars, so users see how decisions in one area affect others
• Side-by-Side Execution: Dual-panel UI showing naive (left) vs. best-practice (right) responses with token counts, latency, cost, and quality analysis for every call
• 6 Foundation Models: Claude Sonnet 4, Claude Haiku 4.5, Nova Premier, Nova Pro, Nova Lite, and Nova Micro with per-model cost tracking
• Live Bedrock Calls: Real-time streaming via ConverseStream API - not canned responses - so users see actual model behavior
• Guardrails with Automated Reasoning: Content filtering (topic denial, PII redaction, prompt attack detection) plus formal logic verification using 35 S-expression rules for AWS service limits
• RAG with Knowledge Bases: Grounded responses from internal company documents with source citations vs. parametric-only hallucinations
• Multi-Agent Orchestration: Strands Agents SDK with Agent-as-Tool pattern - orchestrator delegates to specialist agents (metrics, security, cost) with per-tool trace metrics
• AgentCore Primitives: Working implementations of Gateway (managed MCP), Memory (semantic facts, session summaries, user preferences), Policy (Cedar authorization), Evaluation (LLM-as-a-Judge), and Observability (OpenTelemetry tracing)
• Enterprise Authentication: Cognito with MidWay SSO (OIDC federation) - parameter-driven, disabled by default, enabled via cdk deploy -c auth=Y
• Full Audit Trail: Every user action (login, navigation, prompt execution) logged to DynamoDB with timestamps, both responses, metadata, and AI-generated analysis

⚙️Action

The Architecture

Full-stack serverless application on AWS integrating Bedrock models, Guardrails, Knowledge Bases, Strands Agents, and multiple AgentCore primitives:

                     CloudFront (CDN)
                    /                \
                   /                  \
         S3 (React SPA)         API Gateway HTTP API
                                      |
                                API Lambda (Node.js)
                               /    |     |    \     \
                      Bedrock  Guardrails  KB  Strands  DynamoDB
                     Converse  (Content + (S3  Agent    (Audit
                      API      Auto-Reason)Vectors)Lambda  Logs)
                                                  |
                                            S3 (Agent Results)

Authentication:
  Browser → Cognito Hosted UI → MidWay SSO (OIDC) → Callback → Lambda token exchange → JWT session

AgentCore Primitives:
  Gateway (Managed MCP) → Memory (Semantic/Session/Preferences) → Policy (Cedar) → Evaluation (LLM Judge) → Observability (OTEL)

The 20 Pillars - 4 Layers

Model Layer How You Talk to the Model

Guardrail Layer Safety, Fairness, and Factual Accuracy

Orchestration Layer Connecting Models to Data, Tools, and Agents

Platform Layer Security, Identity, Governance, Evaluation, and Observability

Technology Stack

Automated Reasoning - 35 Formal Logic Rules

The Automated Reasoning pillar uses Bedrock's formal verification engine with 35 S-expression rules covering AWS service limits across 9 services. When the model claims "Lambda max timeout is 30 minutes," the guardrail flags it because the rule says 900 seconds (15 minutes). No statistical uncertainty, no false negatives - provable correctness.

• S3: Max object size (5 TB), bucket limits (100 default / 1000 max), multipart upload rules (10K parts, 5 MB min), single PUT max (5 GB)
• Lambda: Timeout (15 min max / 3 sec default), memory (128 MB - 10 GB), package sizes (50 MB compressed / 250 MB uncompressed), tmp storage (10 GB)
• SQS: Message size (256 KB), visibility timeout (30 sec default / 12 hr max), retention period (4 day default / 14 day max)
• DynamoDB: Item size (400 KB), consistency models, GSI limit (20), LSI limit (5), LSI creation constraint
• API Gateway: Integration timeout (29 sec), payload size (10 MB)
• SNS: Message size (256 KB)
• Kinesis: Record size (1 MB)
• Step Functions: Standard max duration (1 year), Express max duration (5 min)
• EFS: Elastic throughput auto-burst capability

Multi-Agent Orchestration

The Multi-Agent pillar demonstrates the Strands Agents SDK with the Agent-as-Tool pattern. An orchestrator agent delegates to 3 specialist agents, each with focused tools and constrained system prompts:

• Metrics Agent: get_service_metrics, get_error_logs, get_recent_deployments - surfaces CloudWatch data and deployment history
• Security Agent: analyze_iam_policies - evaluates IAM policy configurations for least-privilege violations
• Cost Agent: get_cost_breakdown - provides Cost Explorer data with S3 lifecycle and reserved capacity recommendations

Per-tool metrics (tokens, latency, cost) are tracked and returned for trace visualization in the UI. A ToolCallLimiter hook caps tool calls at 6 per agent to prevent runaway loops.

AgentCore Gateway - Managed MCP

The AgentCore Gateway pillar shows the difference between fragile local MCP subprocesses and a managed, production-grade MCP endpoint:

• Infrastructure: CDK provisions a Gateway, Gateway Target (Lambda-backed), and IAM roles automatically
• Authentication: SigV4-signed requests replace fragile subprocess stdin/stdout communication
• Scalability: Rate limiting, CloudWatch observability, and managed lifecycle instead of brittle child processes
• MCP Server Lambda: Wraps the AWS Documentation MCP Server for live doc search behind Gateway

AgentCore Memory - 3 Strategy Types

The Memory pillar demonstrates persistent agent memory with three strategy types, seeded with demo data via a CDK custom resource:

• Semantic Facts: Long-term factual memories extracted from conversations (infrastructure decisions, incident history, architecture patterns)
• Session Summaries: Short-term session summaries capturing key discussion points, namespaced per session ID
• User Preferences: Persistent user preferences for response format, coding language, and priorities

AgentCore Policy - Cedar Authorization

The Policy pillar demonstrates Cedar-based governance for agent actions:

• Cedar Policy Language: Declarative permit/forbid statements with principal (agent), action (invoke_model, query_kb, execute_tool), resource (model ARN, KB ID, tool name), and conditions
• Policy Engine per Domain: Separate engines for model access, data access, and tool permissions - each evaluating independently
• Platform-Layer Enforcement: Policies evaluated before agent action execution - even prompt injection bypass cannot override Cedar authorization
• Model Tiering: Cedar policies map agent roles to model tiers (Haiku for general, Sonnet for analysis, Opus for research) preventing cost overruns
• Least-Privilege Defaults: Deny-all baseline - new agents inherit zero permissions until Cedar policies explicitly grant access

AgentCore Evaluation - LLM-as-a-Judge

• Built-in Evaluators: Builtin.Helpfulness and Builtin.Correctness for standardized quality scoring
• Custom Evaluators: Domain-specific scoring criteria defined per use case
• On-Demand Mode: Synchronous evaluation for testing and CI/CD pipelines
• Online Mode: Continuous monitoring on sampled production traffic for quality regression detection
• Evaluation + Guardrails: Defense in depth - guardrails prevent bad output in real-time, evaluation detects subtle quality regressions after the fact

Authentication & Audit

• Parameter-Driven Auth: Cognito + MidWay SSO enabled via cdk deploy -c auth=Y, disabled by default for open access
• SSO Flow: Cognito Hosted UI → MidWay OIDC federation → authorization code → Lambda token exchange → JWT session in sessionStorage
• Audit Logging: Every user action (LOGIN, NAVIGATE_PILLAR, PROMPT_EXECUTED) logged to DynamoDB with EST timestamps, both responses (naive + best-practice), token/cost/latency metadata, and AI-generated analysis
• Multi-Tenancy: Custom tenantId and tenantTier attributes in Cognito for per-tenant RAG filtering and billing isolation

Key Design Decisions

📊Result

Key Capabilities

Frontend Experience

• Side-by-Side Chat UI: Dual-panel comparison - naive approach on the left, AWS best-practice on the right
• Real-Time Streaming: Bedrock ConverseStream API for immediate response display
• Per-Response Metrics: Token count, latency, and cost displayed for every response on both sides
• Trace Visualization: Nested agent delegation traces with per-tool metrics for multi-agent pillars
• Seed Data Tabs: Color-coded architecture diagrams, tool descriptions, and clickable document previews per pillar
• Landing Page: Story narrative, key stats, and all 20 pillar cards organized by layer
• Cloudscape Design System: AWS's open-source UI framework ensuring consistent, accessible design

Platform-Level Impact

• Experiential Learning: Users see the actual failure of naive approaches with live model calls - not hypothetical descriptions of what could go wrong
• End-to-End Coverage: Single application demonstrates the entire agentic AI stack from prompt engineering to observability, showing how each layer depends on the others
• AgentCore Adoption: Working implementations of Gateway, Memory, Policy, Evaluation, and Observability reduce the barrier to adopting these primitives in production systems
• Measurable Comparison: Token counts, latency, and cost metrics on every response let users quantify the ROI of each best practice
• Production-Ready Patterns: Authentication (Cognito + SSO), audit logging (DynamoDB), multi-tenancy, and CDK infrastructure can be lifted directly into production architectures
• Formal Verification Showcase: 35 Automated Reasoning rules across 9 AWS services demonstrate provable factual accuracy - a capability most teams don't know exists

🎥Demo Video

Watch the Agentic AI Well Architected application in action - explore how each pillar contrasts naive vs. best-practice approaches with live Amazon Bedrock calls:

💡Key Learnings & Best Practices

Architecture Insights

• Side-by-Side Teaches Better Than Slides: Users who see a prompt injection succeed against a naive implementation and fail against a hardened one internalize the lesson far more deeply than reading about it. Live failure is the most effective teacher
• Continuous Narrative Compounds Understanding: The SupportBot story across 20 pillars means each lesson builds on the previous one. Users see how a prompt engineering decision cascades through security, reliability, and cost - disconnected demos cannot teach this
• Formal Verification Surprises People: Most teams assume factual accuracy requires RAG or fine-tuning. Automated Reasoning with S-expression rules provides provable correctness - when it flags a wrong Lambda timeout, it's a mathematical proof, not a probabilistic guess
• Parameter-Driven Architecture Scales: Making authentication a CDK context parameter (not a code branch) means the same application serves open demos and enterprise deployments with zero code changes

AgentCore Insights

• Gateway Over Subprocesses: Managed MCP via AgentCore Gateway eliminates the fragility of local MCP subprocesses. SigV4 auth, rate limiting, and CloudWatch observability come free - and the managed lifecycle handles scaling
• Three Memory Strategies: Semantic facts, session summaries, and user preferences each serve different purposes. Combining all three gives agents genuine context awareness - they remember what happened, what was decided, and how the user prefers to work
• Cedar Policies as Defense in Depth: Even if a prompt injection bypasses the system prompt, Cedar policies at the platform layer still block unauthorized actions. The agent literally cannot invoke a model or tool that policy denies
• Evaluation + Guardrails Together: Guardrails prevent dangerous output in real-time; evaluation detects subtle quality regressions over time. Neither alone is sufficient - use both
• Agent-as-Tool Pattern: Specialist agents with constrained prompts and focused tools outperform monolithic agents. The orchestrator delegates based on intent; each specialist handles its domain without irrelevant context

Observability Insights

• Metrics Build Trust: Showing token counts, latency, and cost for every response - on both naive and best-practice sides - gives users quantifiable evidence that best practices are worth the effort
• Trace Visualization Demystifies Agents: Rendering nested agent delegation with per-tool metrics makes multi-agent orchestration understandable. Users can see exactly which specialist agent handled which part of the request and what it cost
• Audit Everything: Logging every user action (login, navigation, prompt execution) with both responses and AI-generated analysis creates a complete learning trail - invaluable for understanding which pillars and scenarios drive the most engagement