Skip to content

Latest commit

 

History

History
144 lines (115 loc) · 5.41 KB

README.md

File metadata and controls

144 lines (115 loc) · 5.41 KB

AWS AgentCore CDK Demo

A production-ready reference architecture for deploying AI agents on AWS Bedrock AgentCore using the AWS CDK. This project demonstrates how to build, deploy, and operate an AI agent with MCP (Model Context Protocol) tool integration, OAuth2 authentication, and CloudWatch monitoring.

The demo deploys a Weather Assistant agent that uses Open-Meteo's free API to answer weather questions - but the infrastructure patterns apply to any agent use case.

Architecture

┌─────────────────────────────────────────────────────────┐
│                     AWS Account                          │
│                                                          │
│  ┌──────────────┐   ┌──────────────┐  ┌──────────────┐ │
│  │   Cognito     │   │  AgentCore   │  │  Monitoring   │ │
│  │  User Pool    │   │              │  │  CloudWatch   │ │
│  │  + OAuth2     │──▶│  Gateway     │  │  Dashboard    │ │
│  │  Clients      │   │  (MCP)       │  │  + Alarms     │ │
│  └──────────────┘   │      │       │  └──────────────┘ │
│                      │      ▼       │                    │
│                      │  MCP Runtime │                    │
│                      │  (Weather    │                    │
│                      │   Tools)     │                    │
│                      │      │       │                    │
│                      │      ▼       │                    │
│                      │  Agent       │                    │
│                      │  Runtime     │                    │
│                      │  (Strands)   │                    │
│                      └──────────────┘                    │
└─────────────────────────────────────────────────────────┘

Three-Stack Architecture

Stack Purpose
Cognito OAuth2 authentication (User Pool, M2M client credentials)
AgentCore Gateway + MCP Runtime (tools) + Agent Runtime (Strands agent)
Monitoring CloudWatch dashboard, SNS alarms (error rate, latency, 5xx)

Prerequisites

  • AWS Account with Bedrock AgentCore access
  • AWS CLI configured with credentials
  • Node.js 18+ and npm
  • Docker (for building container images)
  • Python 3.12+ (for the demo script)
  • CDK CLI: npm install -g aws-cdk

Quick Start

1. Install Dependencies

cd infra
npm install

2. Bootstrap CDK (first time only)

npx cdk bootstrap -c env=dev

3. Build and Test

npm run build
npm run test:unit

4. Deploy

npx cdk deploy --all -c env=dev

5. Try It Out

# Get the Agent Runtime ARN from stack outputs
export AGENT_RUNTIME_ARN=$(aws cloudformation describe-stacks \
  --stack-name AcDemoAgentCoreStack-dev \
  --query 'Stacks[0].Outputs[?OutputKey==`AgentRuntimeArn`].OutputValue' \
  --output text)

# Ask a weather question
python scripts/ask-weather.py "What's the weather in Tel Aviv?"

Project Structure

.
├── infra/                          # CDK Infrastructure
│   ├── bin/agentcore-demo.ts       # CDK app entry point
│   ├── lib/
│   │   ├── config/
│   │   │   ├── constants.ts        # Resource naming conventions
│   │   │   └── environments.ts     # Environment configs (dev/prod)
│   │   └── stacks/
│   │       ├── cognito-stack.ts    # OAuth2 authentication
│   │       ├── agentcore-stack.ts  # Runtime + Gateway + MCP
│   │       └── monitoring-stack.ts # CloudWatch dashboards & alarms
│   └── test/
│       ├── unit/                   # CDK unit tests
│       └── e2e/                    # End-to-end tests
├── mcpServer/                      # MCP Tools (Docker container)
│   ├── Dockerfile
│   ├── requirements.txt
│   └── src/
│       ├── server.py               # FastMCP server
│       └── tools/
│           └── weather_tools.py
├── agent/                          # Agent Runtime (Docker container)
│   ├── Dockerfile
│   ├── pyproject.toml
│   └── src/
│       ├── server.py               # BedrockAgentCoreApp entrypoint
│       ├── agent.py                # Strands weather agent
│       └── gateway_client.py        # OAuth2 MCP Gateway client
├── scripts/
│   └── ask-weather.py              # Demo CLI script
├── LICENSE
└── README.md

Customization

To adapt this demo for your own agent:

  1. Replace MCP tools: Edit mcpServer/src/tools/ with your own tool implementations
  2. Update agent logic: Modify agent/src/agent.py with your system prompt and agent configuration
  3. Add resources: If your agent needs S3, databases, etc., add new stacks following the existing patterns

Cleanup

cd infra
npx cdk destroy --all -c env=dev

License

MIT