Sample Strands Agents Chat

🤖 Strands Agents Chat

A full-stack AI chat application powered by Amazon Bedrock, Strands Agents, and Bedrock AgentCore

[](https://aws.amazon.com/) [](https://python.org/) [](https://reactjs.org/) [](https://typescriptlang.org/)

---

📸 Screenshots

---

✨ Features

This is a sample application that serves as a base implementation for chat applications utilizing Strands Agents.

🏗️ Simple Architecture - Clean, maintainable codebase with serverless scalability

🎨 Rich UI/UX - Polished chat interface with intuitive user experience

🔧 Extensible with Strands Agents - Ready for customization with MCP, A2A, Multi Agents, Bedrock AgentCore, and more

🖼️ Gallery Mode - Visual gallery for viewing and managing uploaded images and files

📱 Responsive Design - Optimized for both desktop and mobile usage

> 💡 Perfect Starting Point: If you want to build a governance-enabled, self-hosted, high-functionality generative AI chat application on AWS, using this application as your base implementation is an excellent starting point.

---

🏛️ Architecture

---

🛠️ Built-in Tools

| Tool | Description | Technology | |------|-------------|------------| | 💬 Multi-modal Chat | Support for images, videos, and documents | Amazon Bedrock | | 🧠 Deep Reasoning | Advanced AI reasoning for complex problem solving | Amazon Bedrock | | 🎨 Image Generation | AI-powered image creation | Nova Canvas MCP | | 📚 AWS Documentation Search | Search and access AWS documentation | AWS Documentation MCP | | 🔍 Web Search | Real-time web search capabilities | Tavily API | | 💻 CodeInterpreter | Execute and analyze code in real-time | Bedrock AgentCore | | 🌐 Web Browser | Browse web pages and analyze content | Bedrock AgentCore |

---

🚀 Deployment Guide

Step 1: (Optional) Create Tavily API Key Secret

Click to expand Tavily API setup instructions

1. Open AWS Secrets Manager
2. Click "Store a new secret"
3. Select "Other type of secret"
4. Choose "Plaintext" and paste your Tavily API Key
5. Create the secret and copy the Secret ARN

Step 2: (Required) Configure Parameters

# Navigate to CDK directory
cd cdk

# Install dependencies
npm ci

# Copy the parameter template
cp parameter.template.ts parameter.ts

# Edit parameter.ts with your configuration
# Note: If tavilyApiKeySecretArn is null, web search tool will be disabled

Step 3: (Required) Deploy with CDK

# Bootstrap CDK (run once per AWS account/region)
npx cdk bootstrap

# Deploy all stacks
npx cdk deploy --all --require-approval never

🎉 Access your application using the WebUrl from the deployment output!

---

💻 Development

Frontend Development

For frontend development, you can run the development server locally while connecting to your deployed backend:

# Navigate to web directory
cd web

# Install dependencies
npm ci

# Start development server
npm run dev

The development server will:

• 🚀 Start at http://localhost:5173
• 🔗 Automatically import necessary values from the StrandsChat stack output
• 🔄 Enable hot reload for rapid development

Pre-commit Checks

Before committing your changes, ensure code quality by running the pre-check script:

# Run pre-commit checks
./pre_check.sh

This script will validate your code formatting, run tests, and ensure everything is ready for commit.

---

⚙️ Customization

🛡️ WAF Configuration (Access Restrictions)

The WAF settings are defined in cdk/lib/waf-stack.ts. Customize this file to modify security rules.

> Default behavior: Allows access from all IP addresses and countries

IP Restriction Example:

// Modify IP addresses in waf-stack.ts (line 15)
const allIpv4 = new wafv2.CfnIPSet(this, 'AllowedIpv4Set', {
  name: 'StrandsChatIpv4',
  scope: 'CLOUDFRONT',
  ipAddressVersion: 'IPV4',
  addresses: ['192.168.1.0/24', '10.0.0.0/8'], // Replace with your allowed IP ranges
});

GEO Restriction Example:

// Add country-based rule to the rules array in waf-stack.ts (line 34)
{
  name: 'GeoRestriction',
  priority: 1,
  action: { allow: {} },
  statement: {
    geoMatchStatement: {
      countryCodes: ['US', 'JP', 'CA'], // Allow only these countries
    },
  },
  visibilityConfig: {
    cloudWatchMetricsEnabled: true,
    metricName: 'GeoRestriction',
    sampledRequestsEnabled: true,
  },
},

> Country Codes: Use ISO 3166-1 alpha-2 country codes (e.g., 'US' for United States, 'JP' for Japan)

🔐 Disable Cognito Signup

If you want to disable the Cognito signup functionality and restrict user registration:

Backend Configuration:

1. Open cdk/lib/strands-chat-stack.ts
2. Find the UserPool configuration
3. Change selfSignUpEnabled from true to false

// In strands-chat-stack.ts (line 66-78)
const userPool = new UserPool(this, 'UserPool', {
  selfSignUpEnabled: false, // Change from true to false
  signInAliases: {
    username: false,
    email: true,
  },
  passwordPolicy: {
    requireUppercase: true,
    requireSymbols: true,
    requireDigits: true,
    minLength: 8,
  },
});

Frontend Configuration:

1. Open web/src/components/AuthWithUserPool.tsx
2. Add the hideSignup={true} option to the `` component

// In AuthWithUserPool.tsx (line 75)

          
            Strands Chat
          
        
      );
    },
  }}>

> Note: After making these changes, redeploy the CDK stack for backend changes to take effect.

---

🏗️ Technology Stack

| Layer | Technology | Purpose | |-------|------------|---------| | Frontend | React 19 + TypeScript + Tailwind CSS | Modern, responsive UI | | Backend | Python 3.13 + FastAPI + Strands Agents | AI-powered API | | Infrastructure | AWS CDK + Lambda + DynamoDB + S3 | Serverless architecture | | AI/ML | Amazon Bedrock + Claude | Advanced language models | | Authentication | AWS Cognito | Secure user management |

---

📁 Project Structure

├── 🐍 api/           # Python FastAPI backend
├── ☁️ cdk/           # AWS CDK infrastructure
├── ⚛️ web/           # React frontend application
└── 📖 README.md      # Project documentation

Security

See [CONTRIBUTING](/CONTRIBUTING.md#security-issue-notifications) for more information.

License

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aws-samples
• Source: aws-samples/sample-strands-agents-chat
• License: MIT-0

Install and usage instructions live in the source repository linked above.