A full-stack conversational AI starter kit built with Amazon Bedrock AgentCore, Strands Agents SDK, FastAPI, and htmx. This project is used for rapid prototyping of agentic applications. It accelerates proof-of-concept development with built-in telemetry capture, usage analytics, and cost projections.

Building AI agents is exciting, but understanding their usage, results, and cost profile is critical before scaling. This starter provides:

• Ready-to-deploy agent with memory persistence, guardrails, and tool support
• Built-in usage analytics tracking every token, tool call, and model invocation
• User feedback capture for each response to understand usefulness
• Cost projections to forecast production spending from PoC usage patterns
• Real-time streaming for responsive user experience
• Customizable foundation to change models, add tools, and extend functionality

• 🤖 AI-powered conversational agent with short-term (STM) and long-term memory (LTM)
• ⚡ Streaming chat with embedded memory viewer
• 📊 Admin dashboard with usage analytics and cost tracking
• 💰 Cost projections based on actual usage patterns
• 👍 User feedback with sentiment ratings and comments
• 🛡️ Guardrails analytics with violation tracking and content filtering
• 📝 Prompt templates for quick access to pre-defined prompts
• ☁️ Containerized deployment using Amazon ECS Express Mode
• 🧠 AI Agents powered by Amazon Bedrock AgentCore using the Strands Agents SDK
• 🔐 Secure authentication via Amazon Cognito

The built-in admin dashboard (/admin) provides comprehensive usage analytics:

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│     Browser     │      │   ECS Express   │      │   Guardrails    │      │    AgentCore    │
│  Chat + Admin   │◀────▶│    (Fargate)    │◀────▶│   (Bedrock)     │◀────▶│     Runtime     │
│                 │ SSE  │    FastAPI      │      │                 │      │  Strands Agent  │
└─────────────────┘      └─────────────────┘      └─────────────────┘      └─────────────────┘
        │                       │                                           │           │
        │                       ▼                                           │           ▼
        │                ┌─────────────────┐                                │   ┌───────────────┐
        │                │    DynamoDB     │                                │   │    Bedrock    │
        │                │  Usage/Feedback │                                │   │ Choice of LLM │
        │                └─────────────────┘                                │   └───────────────┘
        ▼                                                                   ▼
┌─────────────────┐                                                 ┌─────────────────┐
│     Cognito     │                                                 │    AgentCore    │
│      Auth       │                                                 │     Memory      │
└─────────────────┘                                                 └─────────────────┘

Install CDK CLI globally:

npm install -g aws-cdk

Note: Docker is not required locally - all container builds are handled by AWS CodeBuild.

• AWS Account with a Default VPC
• IAM permissions with access to Bedrock, Bedrock AgentCore, ECS, Cognito, ECR, DynamoDB, Secrets Manager

1. Clone the repository:

   git clone https://github.com/aws-samples/sample-strands-agentcore-starter
   cd sample-strands-agentcore-starter

2. Install CDK dependencies:

   cd cdk
   npm install

3. Deploy all stacks:

   ./deploy-all.sh --region <aws-region-id>

4. Create a test user (add --admin for admin access):

   cd ../chatapp/deploy
   ./create-user.sh your-email@example.com YourPassword123@ --admin

5. Wait for ECS deployment (4-6 minutes), then access the URL shown in the deployment output.

The deployment creates:

• Cognito User Pool for authentication
• DynamoDB tables for usage analytics, feedback, and guardrails
• Bedrock Guardrail for content filtering
• Bedrock Knowledge Base with S3 Vectors
• AgentCore Memory with LTM strategies
• AgentCore Runtime with the deployed agent
• ECS Express Mode service for the ChatApp

./deploy-all.sh [options]

Options:
  --region <region>    AWS region (default: us-east-1)
  --profile <profile>  AWS CLI profile to use
  --dry-run            Show what would be deployed without deploying

The CDK deployment creates 4 consolidated CloudFormation stacks:

Deployment order: Foundation → Bedrock → Agent → ChatApp

The CDK stacks support deploying to multiple regions in the same AWS account. IAM roles are automatically suffixed with the region name to avoid conflicts.

# Deploy to us-east-1
./deploy-all.sh --region us-east-1

# Deploy to eu-west-1 (same account)
./deploy-all.sh --region eu-west-1

# List all stacks
npx cdk list

# Deploy a specific stack
npx cdk deploy htmx-chatapp-Foundation

# View stack differences before deploying
npx cdk diff

# Synthesize CloudFormation templates
npx cdk synth

# View stack outputs
cat cdk-outputs.json

To update the application after code changes:

cd cdk
./deploy-all.sh --region <aws-region-id>

To update only the ChatApp (faster for UI changes):

cd cdk
npx cdk deploy htmx-chatapp-ChatApp --require-approval never

For local development, you need to sync environment variables from your deployed CDK stacks.

Prerequisites: CDK stacks must be deployed first (./deploy-all.sh).

cd chatapp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Sync .env from AWS Secrets Manager (auto-populates all values)
./sync-env.sh --region <aws-region-id>

# Or with DEV_MODE (bypasses Cognito authentication)
./sync-env.sh --region <aws-region-id> --dev-mode

# Run locally
uvicorn app.main:app --reload --port 8080

• Chat: http://localhost:8080
• Admin: http://localhost:8080/admin

DEV_MODE: When enabled, Cognito authentication is bypassed and requests use a default dev-user-001 user ID. This is useful for rapid iteration without needing to log in. Set DEV_USER_ID in .env to customize the user ID.

Manual .env setup: If you prefer manual configuration, copy .env.example to .env and fill in values. The secret htmx-chatapp/config in AWS Secrets Manager contains all required values.

To destroy all CDK-managed resources:

cd cdk
./destroy-all.sh --region <aws-region-id>

Options:

./destroy-all.sh [options]

Options:
  --region <region>    AWS region (default: us-east-1)
  --profile <profile>  AWS CLI profile to use
  --yes                Auto-confirm all prompts (DANGEROUS)
  --dry-run            Show what would be destroyed without destroying

sample-strands-agentcore-starter/
├── agent/                        # AgentCore agent
│   ├── my_agent.py               # Agent definition
│   ├── tools/                    # Agent tools
│   └── requirements.txt
│
├── chatapp/                      # Chat and Admin UI
│   ├── app/
│   │   ├── main.py               # FastAPI application
│   │   ├── admin/                # Usage analytics module
│   │   ├── auth/                 # Cognito authentication
│   │   ├── agentcore/            # AgentCore client
│   │   ├── storage/              # Data storage services
│   │   ├── routes/               # Chat and Admin API routes
│   │   ├── models/               # Data models
│   │   └── templates/            # UI templates
│   ├── deploy/
│   │   └── create-user.sh        # User creation script
│   └── requirements.txt
│
├── cdk/                          # CDK Infrastructure
│   ├── lib/
│   │   ├── foundation-stack.ts   # Auth, Storage, IAM, Secrets
│   │   ├── bedrock-stack.ts      # Guardrail, KB, Memory
│   │   ├── agent-stack.ts        # ECR, CodeBuild, Runtime
│   │   └── chatapp-stack.ts      # ECS Express Mode
│   ├── deploy-all.sh             # Full deployment script
│   └── destroy-all.sh            # Full cleanup script
│
└── README.md

The system tracks usage metrics for cost analysis:

• Input/Output Tokens: Per invocation token counts
• Model ID: Which model was used
• Latency: Response time in milliseconds
• Tool Usage: Call counts, success/error rates per tool
• Guardrails Violations: Per filter type, user, and session

The dashboard calculates projected monthly costs using:

projected_monthly = (total_cost / days_in_period) * 20

Uses 20 business days for realistic production estimates.

Add tools in agent/tools/ and register them in my_agent.py.

Update the model ID in chatapp/app/static/js/chat.js and add pricing to chatapp/app/admin/cost_calculator.py.

The UsageRepository class in chatapp/app/admin/repository.py provides query methods that can be extended for custom analytics.

The agent includes a Bedrock Knowledge Base for semantic search over curated documents. When configured, the agent prioritizes Knowledge Base results before falling back to web search.

The Knowledge Base is automatically created during CDK deployment. It creates:

• S3 bucket for source documents
• S3 Vectors bucket and index for embeddings
• Bedrock Knowledge Base with Titan Embed Text v2
• Data source connecting the KB to the S3 bucket

1. Upload documents to S3:

   # Get the source bucket name from CDK outputs
   SOURCE_BUCKET=$(cat cdk/cdk-outputs.json | jq -r '."htmx-chatapp-Bedrock".SourceBucketName')
   
   # Upload documents to the documents/ prefix
   aws s3 cp my-document.pdf s3://${SOURCE_BUCKET}/documents/
   aws s3 cp my-folder/ s3://${SOURCE_BUCKET}/documents/ --recursive

2. Sync/Ingest documents:

   # Get the Knowledge Base ID and Data Source ID from CDK outputs
   KB_ID=$(cat cdk/cdk-outputs.json | jq -r '."htmx-chatapp-Bedrock".KnowledgeBaseId')
   DS_ID=$(aws bedrock-agent list-data-sources --knowledge-base-id $KB_ID --query "dataSourceSummaries[0].dataSourceId" --output text)
   
   # Start ingestion job
   aws bedrock-agent start-ingestion-job \
     --knowledge-base-id $KB_ID \
     --data-source-id $DS_ID
   
   # Check ingestion status
   aws bedrock-agent list-ingestion-jobs \
     --knowledge-base-id $KB_ID \
     --data-source-id $DS_ID

The Knowledge Base supports:

• PDF (.pdf)
• Plain text (.txt)
• Markdown (.md)
• HTML (.html)
• Microsoft Word (.doc, .docx)
• CSV (.csv)

When the agent receives a query:

1. The agent first searches the Knowledge Base for relevant context
2. If relevant results are found (score >= min_score), the agent uses that context
3. If no relevant results are found, the agent falls back to web search or URL fetcher

This prioritization ensures domain-specific knowledge takes precedence over general web content.

See CONTRIBUTING for more information.

This library is licensed under the MIT-0 License. See the LICENSE file.