ClickShop demonstrates the architectural evolution of agentic systems through three production-grade implementations. Built for AWS re:Invent 2025 (DAT309 Chalk Talk), this project showcases scaling patterns from a weekend MVP to enterprise-scale multi-agent orchestration with semantic search capabilities.

⚠️ Educational Use Only: This demonstration is designed for learning purposes and illustrates production patterns without production-level error handling, monitoring, or security hardening.

A live-streaming shopping platform that evolved from 50 orders/day to 50,000 orders/day through three architectural iterations—demonstrating how thoughtful design enables exponential scaling without complete rewrites.

from mcp import stdio_client, StdioServerParameters from strands.tools.mcp import MCPClient mcp_client = MCPClient(lambda: stdio_client( StdioServerParameters( command="uvx", args=[ "awslabs.postgres-mcp-server@latest", "--resource_arn", "arn:aws:rds:region:account:cluster:cluster-id", "--secret_arn", "arn:aws:secretsmanager:region:account:secret:secret-name", "--database", "postgres", "--region", "us-west-2", "--readonly", "True" ] ) ))

# Vector embedding generation and similarity search CREATE INDEX ON products USING hnsw (embedding vector_cosine_ops); # Natural language search: "comfortable running shoes" # Matches semantically similar products, not just keywords

Required:

• Python 3.11+
• AWS Account with Amazon Bedrock access
• Claude Sonnet 4.5 model access in Bedrock
• AWS CLI configured with credentials

Recommended:

• Familiarity with agentic frameworks (Strands, LangChain)
• Understanding of Model Context Protocol (MCP)
• Basic PostgreSQL and vector search knowledge

# Clone repository git clone <REPOSITORY_URL> cd sample-dat309-agentic-workflows-aurora-mcp/clickshop-demo # Run automated setup ./scripts/setup.sh # Activate virtual environment source venv/bin/activate # macOS/Linux # venv\Scripts\activate # Windows # Configure AWS credentials cp .env.example .env # Edit .env with your AWS credentials and region # Verify installation python -m demos.run_demo

# .env file structure AWS_ACCESS_KEY_ID=your_access_key AWS_SECRET_ACCESS_KEY=your_secret_key AWS_REGION=us-west-2 BEDROCK_MODEL_ID=global.anthropic.claude-sonnet-4-5-20250929-v1:0

python -m demos.run_demo

Select from the interactive menu to run any architecture demonstration.

python -m demos.phase_1_single_agent

Demonstrates:

• Basic agentic loop with ReAct pattern
• Chain of Thought (CoT) reasoning
• Sequential tool execution
• Direct database access patterns
• Manual connection management

python -m demos.phase_2_agent_mcp

Demonstrates:

• MCP server integration for database abstraction
• RDS Data API for serverless compute
• IAM-based authentication
• Tool auto-discovery from MCP servers
• Read-only database operations via MCP

python -m demos.phase_3_multi_agent

Demonstrates:

• Supervisor pattern for agent orchestration
• Specialized agents with single responsibilities
• Semantic search with pgvector (0.8.0+)
• Parallel agent execution
• HNSW vector indexing for similarity search

clickshop-demo/ ├── requirements.txt # Python dependencies ├── .env.example # Environment variable template │ ├── demos/ # Demo implementations │ ├── run_demo.py # Main entry point with interactive menu │ ├── phase_1_single_agent.py # Monolithic agent (50 orders/day) │ ├── phase_2_agent_mcp.py # MCP integration (5K orders/day) │ └── phase_3_multi_agent.py # Multi-agent (50K orders/day) │ ├── lib/ # Core library modules │ └── aurora_db.py # Database operations and utilities │ ├── scripts/ # Automation scripts │ └── setup.sh # Environment setup │ └── data/ # Static data └── products.json # Product catalog 

# Verify AWS credentials aws sts get-caller-identity # Verify Bedrock access aws bedrock list-foundation-models --region us-west-2 # Test Bedrock model invocation aws bedrock-runtime invoke-model \ --model-id global.anthropic.claude-sonnet-4-5-20250929-v1:0 \ --body '{"anthropic_version":"bedrock-2023-05-31","max_tokens":100,"messages":[{"role":"user","content":"Hello"}]}' \ --region us-west-2 \ output.json

# Recreate virtual environment rm -rf venv python3.11 -m venv venv source venv/bin/activate pip install -r requirements.txt --upgrade

# Verify MCP server installation uvx awslabs.postgres-mcp-server@latest --version # Test MCP server connectivity uvx awslabs.postgres-mcp-server@latest \ --resource_arn "arn:aws:rds:region:account:cluster:cluster-id" \ --secret_arn "arn:aws:secretsmanager:region:account:secret:secret-name" \ --database "postgres" \ --region "us-west-2" \ --readonly "True"

Supercharging Vector Search with pgvector 0.8.0 on Aurora PostgreSQL
Deep dive into pgvector 0.8.0 improvements including HNSW indexing, scalar quantization, and performance optimizations for semantic search workloads.

Supercharging AWS Database Development with MCP Servers
Guide to using Model Context Protocol servers for building AI agent applications with standardized database access patterns.

1. Start Monolithic, Evolve Deliberately
   Begin with a single agent to validate product-market fit. Introduce complexity only when metrics demonstrate the need.

2. Abstract Early, Scale Later
   Introduce MCP for database abstraction before scaling bottlenecks emerge. Protocol-driven design enables horizontal scaling.

3. Specialize Agents by Responsibility
   Multi-agent systems should follow Single Responsibility Principle. Each agent should have one clear purpose with dedicated tools.

4. Use Supervisor Pattern for Orchestration
   Complex workflows require a supervisor agent that delegates to specialists rather than monolithic agents handling everything.

• Semantic Search: pgvector with HNSW indexing dramatically improves search relevance and reduces latency
• Parallel Execution: Supervisor pattern enables concurrent agent operations for sub-second response times
• Connection Pooling: MCP servers handle connection lifecycle, eliminating manual pool management
• IAM Authentication: Credential management via AWS IAM reduces operational overhead

• Use IAM roles and policies for database access (no hardcoded credentials)
• Implement least-privilege access patterns for each agent/tool
• Enable audit logging for all agent actions
• Use AWS Secrets Manager for credential rotation

# Core Framework python>=3.11 strands-framework>=1.0.0 boto3>=1.34.0 # Database psycopg3>=3.1.0 psycopg3-binary>=3.1.0 # Vector Search (Phase 3) sentence-transformers>=2.2.0 pgvector>=0.8.0 # MCP Protocol (Phase 2, 3) mcp>=0.1.0 # Utilities python-dotenv>=1.0.0 rich>=13.7.0