Amazon Bedrock AgentCore - Automated Full-Stack Deployment

Starter template for deploying AI agents with Amazon Bedrock AgentCore. Complete infrastructure scaffolding with authentication, API, and web interface - deployment automated in one command.

The example agent is built with the Strands Agents framework and includes calculator and weather tools to demonstrate tool integration. The focus is on deployment automation - you can easily swap the agent implementation or extend its capabilities.

Architecture

Flow: 1. Browser loads React app from CloudFront/S3 2. User authenticates with Cognito, receives JWT token 3. Browser calls AgentCore directly with JWT Bearer token 4. AgentCore validates JWT and processes agent requests

Quick Start

Cloud Deployment

Prerequisites

• AWS CLI v2.31.13 or later installed and configured (Installation Guide)
• Check your version: aws --version
• AgentCore support was added in AWS CLI v2.31.13 (January 2025)
• Node.js 22+ installed
• AWS credentials configured with permissions for CloudFormation, Lambda, S3, ECR, CodeBuild, API Gateway, Cognito, and IAM via:
• aws configure (access key/secret key)
• AWS SSO: aws sso login --profile <profile-name>
• Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
• No Docker required! (CodeBuild handles container builds)

⚠️ Important: Region Requirements

Amazon Bedrock AgentCore is only available in specific AWS regions.

Before deploying, verify AgentCore availability in your target region by checking the AWS AgentCore Regions Documentation.

One-Command Deploy

Windows (PowerShell):

.\deploy-all.ps1

macOS/Linux (Bash):

chmod +x deploy-all.sh scripts/build-frontend.sh
./deploy-all.sh

Platform Notes: - Windows users: Use the PowerShell script (.ps1) - macOS/Linux users: Use the bash script (.sh) - Both scripts perform identical operations and produce the same infrastructure - If you prefer PowerShell on macOS: brew install --cask powershell then run pwsh deploy-all.ps1

Time: ~10 minutes (most time is CodeBuild creating the container image)

Done! Your app is live at the CloudFront URL shown in the output.

Architecture Note: This demo uses a simple architecture where the React frontend calls AgentCore directly with JWT authentication.

Test Your App

1. Open the CloudFront URL from deployment output
2. Click "Sign In" in the header
3. Create an account:
4. Click "Sign up"
5. Enter your email and password (min 8 chars, needs uppercase, lowercase, digit)
6. Check your email for verification code
7. Enter the code to confirm
8. You'll be automatically signed in
9. Enter a prompt: "What is 42 + 58?"
10. See the response from the agent

Try these prompts: - "What's the weather like today?" - "Calculate 123 * 456" - "What is 2 to the power of 10?"

Local Development Mode

For rapid development without AWS deployment:

Prerequisites: - Python 3.8+ with pip - Node.js 18+ with npm - AWS credentials configured with permissions for Bedrock model invocation. The default example invokes Anthropic Claude Haiku 4.5, model id global.anthropic.claude-haiku-4-5-20251001-v1:0.

Start Local Development:

macOS/Linux:

chmod +x dev-local.sh
./dev-local.sh

Windows (PowerShell):

.\dev-local.ps1

This will: 1. Create a Python virtual environment and install agent dependencies 2. Install frontend dependencies 3. Start the AgentCore agent locally on http://localhost:8080 4. Start the frontend dev server on http://localhost:5173 5. Configure the frontend to call the local agent (no authentication required)

Local Development Features: - ✅ Frontend hot reload (Vite dev server) - ✅ Fast agent restart cycle (no deployment needed) - ✅ Authentication with Cognito is bypassed - ✅ Same agent code as production - ✅ Rapid iteration without AWS deployment

How Local Development Works: - python strands_agent.py starts your agent as a regular Python process - app.run() in strands_agent.py creates HTTP server on localhost:8080 (via bedrock-agentcore library) - Frontend sends POST requests to /api/invocations - Agent executes directly in Python, calls AWS Bedrock APIs - No Docker, no containers needed - just Python + web server

Development Workflow: - Frontend changes (frontend/ files): Hot reload automatically via Vite - Agent changes (agent/ files): Restart required - Ctrl+C then re-run script

Note: Agent restart takes ~10 seconds vs ~10 minutes for production deployment.

Stack Architecture

Stack Name	Purpose	Key Resources
AgentCoreInfra	Build infrastructure	ECR Repository, CodeBuild Project, IAM Roles, S3 Bucket
AgentCoreAuth	Authentication	Cognito User Pool, User Pool Client
AgentCoreRuntime	Agent runtime with built-in auth	AgentCore Runtime with Cognito JWT Authorizer, Lambda Waiter
AgentCoreFrontend	Web UI	S3 Bucket, CloudFront Distribution, React App with Auth

Project Structure

project-root/
├── agent/                     # Agent runtime code
│   ├── strands_agent.py       # Agent implementation (Strands framework)
│   ├── requirements.txt       # Python dependencies
│   ├── Dockerfile             # ARM64 container definition
│   └── .dockerignore          # Docker ignore patterns
│
├── cdk/                       # Infrastructure as Code
│   ├── bin/
│   │   └── app.ts             # CDK app entry point
│   ├── lib/
│   │   ├── infra-stack.ts     # Build infrastructure (ECR, IAM, CodeBuild)
│   │   ├── runtime-stack.ts   # AgentCore runtime + API
│   │   └── frontend-stack.ts  # CloudFront + S3
│   ├── cdk.json               # CDK configuration
│   ├── tsconfig.json          # TypeScript configuration
│   └── package.json           # CDK dependencies
│

├── frontend/                  # React app (Vite)
│   ├── src/
│   │   ├── App.tsx            # Main UI component with auth
│   │   ├── AuthModal.tsx      # Login/signup modal
│   │   ├── auth.ts            # Cognito authentication logic
│   │   ├── agentcore.ts       # Direct AgentCore invocation
│   │   └── main.tsx           # React entry point
│   ├── dist/                  # Build output (gitignored)
│   └── package.json           # Frontend dependencies
│
├── scripts/
│   ├── build-frontend.ps1     # Builds React app with AgentCore ARN injection (Windows)
│   └── build-frontend.sh      # Builds React app with AgentCore ARN injection (macOS/Linux)
│
├── deploy-all.ps1             # Main deployment orchestration (Windows)
├── deploy-all.sh              # Main deployment orchestration (macOS/Linux)
├── dev-local.ps1              # Local development mode (Windows)
├── dev-local.sh               # Local development mode (macOS/Linux)
└── README.md                  # This file

How It Works

Deployment Flow

The deploy-all.ps1 script orchestrates the complete deployment:

1. Verify AWS credentials (checks AWS CLI configuration)
2. Check AWS CLI version (requires v2.31.13+ for AgentCore support)
3. Check AgentCore availability (verifies service is available in your configured region)
4. Install CDK dependencies (cdk/node_modules)
5. Install frontend dependencies (frontend/node_modules, includes amazon-cognito-identity-js)
6. Create placeholder frontend build (for initial deployment)
7. Bootstrap CDK environment (sets up CDK deployment resources in your AWS account/region)
8. Deploy AgentCoreInfra - Creates build pipeline resources:
9. ECR repository for agent container images
10. IAM role for AgentCore runtime
11. S3 bucket for CodeBuild sources
12. CodeBuild project for ARM64 builds
13. Deploy AgentCoreAuth - Creates authentication resources:
    • Cognito User Pool (email/password)
    • User Pool Client for frontend
    • Password policy (min 8 chars, uppercase, lowercase, digit)
14. Deploy AgentCoreRuntime - Deploys agent with built-in auth:
    • Uploads agent source code to S3
    • Triggers CodeBuild via Custom Resource
    • Lambda waiter polls CodeBuild (5-10 minutes)
    • Creates AgentCore runtime with built-in Cognito JWT authentication
15. Build frontend with AgentCore ARN and Cognito config, then deploy AgentCoreFrontend:
    • Retrieves AgentCore Runtime ARN and Cognito config from stack outputs
    • Builds React app with injected configuration
    • S3 bucket for static hosting
    • CloudFront distribution with OAC
    • Deploys React app with authentication UI

Request Flow

1. User signs in via Cognito (email verification required)
2. Frontend receives JWT access token from Cognito
3. User enters prompt in React UI
4. Frontend sends POST directly to AgentCore /runtimes/{arn}/invocations with JWT Bearer token
5. AgentCore validates JWT token with Cognito (built-in authentication)
6. AgentCore executes agent in isolated container (microVM)
7. Agent processes request using Strands framework + Anthropic Claude Haiku 4.5
8. Response returned directly to frontend

Key Components

1. Authentication (AgentCoreAuth stack)

• Cognito User Pool for user management
• Email-based authentication with verification
• Password policy: min 8 chars, uppercase, lowercase, digit
• Frontend integration via amazon-cognito-identity-js
• JWT tokens automatically included in API requests
• Sign in/sign up modal with email confirmation flow
• JWT Bearer Token Authentication: Implements AgentCore's built-in JWT authorization (see JWT Authentication Guide)

2. Agent (agent/strands_agent.py)

• Built with Strands Agents framework
• Uses Anthropic Claude Haiku 4.5
• Includes calculator and weather tools
• Wrapped with @BedrockAgentCoreApp decorator

3. Container Build

• ARM64 architecture (native AgentCore support)
• Python 3.13 slim base image
• Built via CodeBuild (no local Docker required)
• Automatic build on deployment
• Build history and logs in AWS Console

4. Lambda Waiter (Critical Component)

• Custom Resource that waits for CodeBuild completion
• Polls every 30 seconds, 15-minute timeout
• Returns minimal response to CloudFormation (<4KB)
• Ensures image exists before AgentCore runtime creation
• Why needed: CodeBuild's batchGetBuilds response exceeds CloudFormation's 4KB Custom Resource limit

5. Direct AgentCore Integration

• Frontend calls AgentCore directly using HTTPS
• JWT Bearer token authentication (Cognito access tokens)
• Built-in Cognito JWT authorizer in AgentCore runtime
• Session ID generation for request tracking

6. IAM Permissions

The execution role includes: - Bedrock model invocation - ECR image access - CloudWatch Logs & Metrics - X-Ray tracing - AgentCore Identity (workload access tokens)

7. Built-in Observability

• CloudWatch Logs: /aws/bedrock-agentcore/runtimes/strands_agent-*
• X-Ray Tracing: Distributed tracing enabled
• CloudWatch Metrics: Custom metrics in bedrock-agentcore namespace
• CodeBuild Logs: /aws/codebuild/bedrock-agentcore-strands-agent-builder

Manual Deployment

If you prefer to deploy stacks individually:

1. Bootstrap CDK (one-time setup)

cd cdk
npx cdk bootstrap --no-cli-pager

2. Deploy Infrastructure

cd cdk
npx cdk deploy AgentCoreInfra --no-cli-pager

3. Deploy Authentication

cd cdk
npx cdk deploy AgentCoreAuth --no-cli-pager

4. Deploy Runtime (triggers build automatically)

cd cdk
npx cdk deploy AgentCoreRuntime --no-cli-pager

Note: This will pause for 5-10 minutes while CodeBuild runs

5. Deploy Frontend

Windows (PowerShell):

$agentRuntimeArn = aws cloudformation describe-stacks --stack-name AgentCoreRuntime --query "Stacks[0].Outputs[?OutputKey=='AgentRuntimeArn'].OutputValue" --output text --no-cli-pager
$region = aws cloudformation describe-stacks --stack-name AgentCoreRuntime --query "Stacks[0].Outputs[?OutputKey=='Region'].OutputValue" --output text --no-cli-pager
$userPoolId = aws cloudformation describe-stacks --stack-name AgentCoreAuth --query "Stacks[0].Outputs[?OutputKey=='UserPoolId'].OutputValue" --output text --no-cli-pager
$userPoolClientId = aws cloudformation describe-stacks --stack-name AgentCoreAuth --query "Stacks[0].Outputs[?OutputKey=='UserPoolClientId'].OutputValue" --output text --no-cli-pager
.\scripts\build-frontend.ps1 -UserPoolId $userPoolId -UserPoolClientId $userPoolClientId -AgentRuntimeArn $agentRuntimeArn -Region $region
cd cdk
npx cdk deploy AgentCoreFrontend --no-cli-pager

macOS/Linux (Bash): ```bash AGENT_RUNTIME_ARN=$(aws cloudformation describe-stacks --stack-name AgentCoreRuntime --query "Stacks[0].Outputs[?OutputKey=='AgentRuntimeArn'].OutputValue" --output text --no-cli-pager) REGION=$(aws cloudformation describe-stacks --stack-name AgentCoreRuntime --query "Stacks[0].Outputs[?OutputKey=='Region'].OutputValue" --output text --no-cli-pager) USER_POOL_ID=$(aws cloudformation describe-stacks --stack-name AgentCoreAuth --query "Stacks[0].Outputs[?OutputKey=='UserPoolId'].OutputValue" --output text --no-cli-pager) USER_POOL_CLIENT_ID=$(aws cloudformation describe-stacks --stack-name AgentCoreAuth --query "Stacks[0].Outputs[?OutputKey=='UserPoolClientId'].OutputValue" --output text --no-cli-pager) ./scripts/build-frontend.sh "$USER_POOL_ID" "$USER_POOL_CLIENT_ID" "$AGENT_RUNTIME_ARN" "$REGION" cd cdk npx cdk deploy AgentCo