AgentCore + Strands Agents Starter Application

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.

Why This Starter?

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

Key Features

🤖 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

Admin Dashboard

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

📊 Dashboard Overview /admin

Total tokens, invocations, estimated costs
Top users and tools by usage
Model breakdown with per-model costs
Projected monthly cost
Feedback and guardrails summary

🔢 Token Analytics /admin/tokens

Token usage breakdown by model
Input vs output distribution
Cost per model comparison
Time-range filtering

👥 User Analytics /admin/users

Per-user token usage and session counts
Search users by ID
Drill-down to individual sessions
Sorted by total tokens

📋 Session Details /admin/sessions/{id}

Complete session token usage
Tools invoked with success/error rates
Individual invocation records
Model and latency information

👍 Feedback Analytics /admin/feedback

Thumbs up/down on responses
Optional comments on negative feedback
Filter by sentiment and date range
Drill-down to conversation context

🛡️ Guardrails Analytics /admin/guardrails

Violation tracking by filter type
Filter strength and confidence levels
Source breakdown (input vs output)
Expandable violation details

🔧 Tool Analytics /admin/tools

Call counts per tool
Success/error rates
Average execution times

📝 Prompt Templates /admin/templates

Create reusable prompt templates
Edit title, description, and prompt text
Templates appear in chat UI dropdown
Default "Capabilities" template included

Architecture

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│     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      │
└─────────────────┘                                                 └─────────────────┘

Prerequisites

Tool	Minimum Version	Purpose
Python	3.11+	Backend development
AWS CLI	2.x	AWS resource management
Docker	20.x	Container builds

AWS Requirements

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

Quick Start

Clone the repository

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

Install agent dependencies

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

Run the setup.sh to deploy agent and chat app resources. Answer the following when prompted:
- Path or Press Enter to use detected dependency file: requirements.txt
  - Press Enter
- Execution role ARN/name (or press Enter to auto-create):
  - Press Enter
- Configure OAuth authorizer instead? (yes/no) [no]:
  - Press Enter
- Configure request header allowlist? (yes/no) [no]:
  - Press Enter
- MemoryManager initialization
  - Your choice: Enter the number for the chat_app_mem resource. This should be 1 unless you already had memory resources.

./setup.sh --region <aws-region-id>

./setup.sh [options]

Options:
  --region <region>         AWS region (default: us-east-1)
  --skip-agent              Skip agent deployment (use existing)
  --skip-chatapp            Skip chatapp deployment

Create a test user (add --admin for admin access)

cd chatapp/deploy
./create-user.sh [email protected] YourPassword123@ --admin

The setup script will:

Deploy the agent to AgentCore Runtime (creates memory with LTM strategies)
Create Cognito User Pool and app client
Set up IAM roles for ECS
Store secrets in AWS Secrets Manager
Deploy the ChatApp to ECS Express Mode

Wait for ECS Service Deployment to complete. Monitor the deployment process on the AWS Console.

⚠️ This will take 4-6 minutes.

Step-by-Step Setup

If you prefer to deploy components individually:

1. Deploy the Agent

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

# Deploy agent with Short-term and Long-term Memory
./deploy.sh

This creates:

AgentCore Memory with semantic, summary, and user preference strategies
AgentCore Runtime with the deployed agent
Configuration saved to .bedrock_agentcore.yaml

2. Deploy the ChatApp

cd chatapp

# Set up Cognito (creates user pool and client)
cd deploy
./setup-cognito.sh

# Create a test user (add --admin for admin access)
./create-user.sh [email protected] YourPassword123@ --admin

# Set up IAM roles
./setup-iam.sh

# Create secrets in AWS Secrets Manager
./create-secrets.sh
cd ..

# Deploy to ECS Express Mode
./deploy.sh

3. Local Development

For local development without deploying to ECS:

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

# Copy example env and fill in values from agent deployment
cp .env.example .env
# Edit .env with values from agent/.bedrock_agentcore.yaml

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

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

Updating Deployments

Update Agent

cd agent
./deploy.sh  # Redeploys with latest code

Update ChatApp

cd chatapp
./deploy.sh --update  # Updates existing ECS service

Delete ChatApp Deployment

cd chatapp
./deploy.sh --delete  # Removes ECS Express Mode service

Cleanup

To remove all AWS resources created by this starter, use the cleanup script:

./cleanup.sh --region <aws-region-id>

This deletes:

ECS Express Mode service and ECR repository
Secrets Manager secret
IAM roles (execution, task, infrastructure)
DynamoDB tables (usage, feedback, guardrails)
Bedrock Guardrail
Cognito User Pool
CloudWatch log groups and alarms
AgentCore agent runtime and memory
Local config files (optional)

Cleanup Options

./cleanup.sh [options]

Options:
  --region <region>  AWS region (default: us-east-1)
  --skip-agent       Skip agent/memory deletion
  --skip-chatapp     Skip chatapp resources deletion
  --dry-run          Show what would be deleted without deleting

Dry Run

Preview what will be deleted before running:

./cleanup.sh --region us-east-1 --dry-run

Environment Variables

Agent

Variable	Description
`BEDROCK_AGENTCORE_MEMORY_ID`	AgentCore Memory ID
`AWS_REGION`	AWS region

ChatApp

Variable	Required	Description
`COGNITO_USER_POOL_ID`	Yes	Cognito User Pool ID
`COGNITO_CLIENT_ID`	Yes	Cognito App Client ID
`COGNITO_CLIENT_SECRET`	Yes	Cognito App Client Secret
`AGENTCORE_RUNTIME_ARN`	Yes	AgentCore Runtime ARN
`MEMORY_ID`	Yes	AgentCore Memory ID
`USAGE_TABLE_NAME`	Yes	DynamoDB table for usage records
`FEEDBACK_TABLE_NAME`	Yes	DynamoDB table for feedback records
`GUARDRAIL_TABLE_NAME`	Yes	DynamoDB table for guardrail violations
`GUARDRAIL_ID`	No	Bedrock Guardrail ID for content filtering
`GUARDRAIL_VERSION`	No	Bedrock Guardrail version (default: DRAFT)
`GUARDRAIL_ENABLED`	No	Enable/disable guardrail evaluation (default: true)
`PROMPT_TEMPLATES_TABLE_NAME`	Yes	DynamoDB table for prompt templates
`APP_URL`	No	Application URL for callbacks
`AWS_REGION`	Yes	AWS region

Project Structure

sample-strands-agentcore-starter/
├── agent/                        # AgentCore agent
│   ├── my_agent.py               # Agent definition
│   ├── tools/                    # Agent tools
│   ├── deploy.sh                 # Deployment script
│   └── 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/                   # Deployment resources
│   ├── deploy.sh                 # Deployment script
│   └── requirements.txt
│
└── README.md

Cost Tracking

The system tracks usage metrics for cost analysis:

Captured Metrics

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

Default Models and Costs

Model	Input Tokens (per 1M)	Output Tokens (per 1M)
Amazon Nova 2 Lite	$0.30	$2.50
Amazon Nova Pro	$0.80	$3.20
Anthropic Claude Haiku 4.5	$1.00	$5.00
Anthropic Claude Sonnet 4.5	$3.00	$15.00
Anthropic Claude Opus 4.5	$5.00	$25.00

Monthly Projections

The dashboard calculates projected monthly costs using:

projected_monthly = (total_cost / days_in_period) * 20

Uses 20 business days for realistic production estimates.

Customization

Adding New Tools

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

Changing Models

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

Extending Analytics

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

Knowledge Base Integration

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

Setup

The Knowledge Base is automatically created during setup.sh. 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

Adding Documents to the Knowledge Base

Upload documents to S3:

# Get the source bucket name (created during setup)
SOURCE_BUCKET="${APP_NAME:-htmx-chatapp}-kb-${AWS_ACCOUNT_ID}-${AWS_REGION}"

# 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

Sync/Ingest documents:

# Get the Knowledge Base ID and Data Source ID
KB_ID=$(aws bedrock-agent list-knowledge-bases --query "knowledgeBaseSummaries[?name=='${APP_NAME:-htmx-chatapp}-kb'].knowledgeBaseId" --output text)
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

Supported Document Formats

The Knowledge Base supports:

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

KB Search Tool Configuration

The agent's Knowledge Base search tool can be configured via environment variables:

Variable	Default	Description
`KB_ID`	-	Knowledge Base ID (required to enable KB search)
`KB_MAX_RESULTS`	5	Maximum number of results to return
`KB_MIN_SCORE`	0.5	Minimum relevance score threshold (0.0-1.0)

How the Agent Uses the Knowledge Base

When the agent receives a query:

The agent first searches the Knowledge Base for relevant context
If relevant results are found (score >= min_score), the agent uses that context
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.

Manual KB Setup (Optional)

If you need to set up the Knowledge Base separately:

cd chatapp/deploy
./setup-knowledgebase.sh

This exports KB_ID which should be added to your agent's environment configuration.

Security

See CONTRIBUTING for more information.

License

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

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.kiro		.kiro
agent		agent
assets		assets
chatapp		chatapp
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
cleanup.sh		cleanup.sh
setup.sh		setup.sh

License

aws-samples/sample-strands-agentcore-starter

Folders and files

Latest commit

History

Repository files navigation

AgentCore + Strands Agents Starter Application

Why This Starter?

Key Features

Admin Dashboard

Architecture

Prerequisites

AWS Requirements

Quick Start

Step-by-Step Setup

1. Deploy the Agent

2. Deploy the ChatApp

3. Local Development

Updating Deployments

Update Agent

Update ChatApp

Delete ChatApp Deployment

Cleanup

Cleanup Options

Dry Run

Environment Variables

Agent

ChatApp

Project Structure

Cost Tracking

Captured Metrics

Default Models and Costs

Monthly Projections

Customization

Adding New Tools

Changing Models

Extending Analytics

Knowledge Base Integration

Setup

Adding Documents to the Knowledge Base

Supported Document Formats

KB Search Tool Configuration

How the Agent Uses the Knowledge Base

Manual KB Setup (Optional)

Security

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Languages

Packages