# karmendra8386/agentic-ai-aws-reference architecture

> Architecture diagram of the GitHub repository karmendra8386/agentic-ai-aws-reference, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karmendra8386/agentic-ai-aws-reference
- Repository: https://github.com/karmendra8386/agentic-ai-aws-reference

## Overview

This repository is a production-reference architecture for agentic AI on AWS, implemented as a deliberately incomplete CDK starter. The documented user flow is Users → API Gateway → Lambda orchestrator → Bedrock AgentCore, with IAM identity, models, storage, and observability supporting it. Separate reference branches cover model promotion, data obfuscation, regression evaluation, and governance. The sampled CDK defines infrastructure stubs rather than an operational agent; links for documented but unsampled capabilities rely on the README, not inspected implementations.

Main entry points: [`README.md`](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md) (Bedrock AgentCore), [`cdk/stacks/agent_stack.py`](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py) (Agent IAM role)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_api["API Gateway<br/>[agent_stack.py]"]
  node_orchestrator["Lambda orchestrator<br/>[README.md]"]
  node_agentcore["Bedrock AgentCore<br/>[README.md]"]
end

subgraph group_identity["Identity and access"]
  node_agent_role["Agent IAM role<br/>[agent_stack.py]"]
  node_approver["Human approval role<br/>[agent_stack.py]"]
end

subgraph group_data_models["Data and models"]
  node_models["Bedrock models<br/>[README.md]"]
  node_model_lifecycle["Model lifecycle<br/>[README.md]"]
  node_kms["Data encryption key<br/>[agent_stack.py]"]
  node_raw_bucket[("Raw data lake<br/>[agent_stack.py]")]
  node_curated_bucket[("Curated data lake<br/>[agent_stack.py]")]
  node_obfuscation["PII obfuscation<br/>[README.md]"]
end

subgraph group_assurance["Evaluation and governance"]
  node_regression["Regression evaluation<br/>[README.md]"]
  node_logs[("Turn logs and traces<br/>[agent_stack.py]")]
  node_governance["Governance dashboards<br/>[README.md]"]
end

node_users(("Users"))

node_users -->|"send requests"| node_api
node_api -->|"routes requests"| node_orchestrator
node_orchestrator -->|"invokes runtime"| node_agentcore
node_agentcore -->|"assumes identity"| node_agent_role
node_agentcore -->|"uses models"| node_models
node_agent_role -->|"permits invocation"| node_models
node_kms -->|"encrypts"| node_raw_bucket
node_kms -->|"encrypts"| node_curated_bucket
node_obfuscation -->|"prepares data for"| node_curated_bucket
node_curated_bucket -->|"grants read access"| node_agent_role
node_model_lifecycle -->|"evaluates and promotes"| node_models
node_regression -->|"tests behavior"| node_agentcore
node_agentcore -->|"records turns"| node_logs
node_logs -->|"feeds observability"| node_governance
node_agentcore -->|"requests approval"| node_approver

click node_api "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py"
click node_orchestrator "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md"
click node_agentcore "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md"
click node_agent_role "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py"
click node_approver "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py"
click node_models "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md"
click node_model_lifecycle "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md"
click node_kms "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py"
click node_raw_bucket "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py"
click node_curated_bucket "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py"
click node_obfuscation "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md"
click node_regression "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md"
click node_logs "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py"
click node_governance "https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_orchestrator,node_agentcore,node_users toneBlue
class node_agent_role,node_approver toneAmber
class node_models,node_model_lifecycle,node_kms,node_raw_bucket,node_curated_bucket,node_obfuscation toneMint
class node_regression,node_logs,node_governance toneRose
```

## Components

### Agent runtime

- [API Gateway](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py): `cdk/stacks/agent_stack.py`
- [Lambda orchestrator](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md): `README.md`
- [Bedrock AgentCore](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md): `README.md`

### Identity and access

- [Agent IAM role](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py): `cdk/stacks/agent_stack.py`
- [Human approval role](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py): `cdk/stacks/agent_stack.py`

### Data and models

- [Bedrock models](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md): `README.md`
- [Model lifecycle](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md): `README.md`
- [Data encryption key](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py): `cdk/stacks/agent_stack.py`
- [Raw data lake](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py): `cdk/stacks/agent_stack.py`
- [Curated data lake](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py): `cdk/stacks/agent_stack.py`
- [PII obfuscation](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md): `README.md`

### Evaluation and governance

- [Regression evaluation](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md): `README.md`
- [Turn logs and traces](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/cdk/stacks/agent_stack.py): `cdk/stacks/agent_stack.py`
- [Governance dashboards](https://github.com/karmendra8386/agentic-ai-aws-reference/blob/main/README.md): `README.md`

### Other components

- **Users**

## Connections

- Users → API Gateway: send requests (evidence: `README.md`)
- API Gateway → Lambda orchestrator: routes requests (evidence: `README.md`)
- Lambda orchestrator → Bedrock AgentCore: invokes runtime (evidence: `README.md`)
- Bedrock AgentCore → Agent IAM role: assumes identity (evidence: `cdk/stacks/agent_stack.py`)
- Bedrock AgentCore → Bedrock models: uses models (evidence: `README.md`)
- Agent IAM role → Bedrock models: permits invocation (evidence: `cdk/stacks/agent_stack.py`)
- Data encryption key → Raw data lake: encrypts (evidence: `cdk/stacks/agent_stack.py`)
- Data encryption key → Curated data lake: encrypts (evidence: `cdk/stacks/agent_stack.py`)
- PII obfuscation → Curated data lake: prepares data for (evidence: `README.md`)
- Curated data lake → Agent IAM role: grants read access (evidence: `cdk/stacks/agent_stack.py`)
- Model lifecycle → Bedrock models: evaluates and promotes (evidence: `README.md`)
- Regression evaluation → Bedrock AgentCore: tests behavior (evidence: `README.md`)
- Bedrock AgentCore → Turn logs and traces: records turns (evidence: `README.md`)
- Turn logs and traces → Governance dashboards: feeds observability (evidence: `README.md`)
- Bedrock AgentCore → Human approval role: requests approval (evidence: `cdk/stacks/agent_stack.py`)
