https://github.com/aws-samples/sample-strands-agents-chat
A full-stack AI chat application powered by Amazon Bedrock and Strands Agents
https://github.com/aws-samples/sample-strands-agents-chat
a2a agentcore ai-agents bedrock mcp multiagent serverless strands-agents
Last synced: 26 days ago
JSON representation
A full-stack AI chat application powered by Amazon Bedrock and Strands Agents
- Host: GitHub
- URL: https://github.com/aws-samples/sample-strands-agents-chat
- Owner: aws-samples
- License: mit-0
- Created: 2025-08-13T02:50:00.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-10-02T04:50:55.000Z (4 months ago)
- Last Synced: 2025-10-02T06:25:11.670Z (4 months ago)
- Topics: a2a, agentcore, ai-agents, bedrock, mcp, multiagent, serverless, strands-agents
- Language: TypeScript
- Homepage:
- Size: 1.57 MB
- Stars: 15
- Watchers: 2
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-strands-agents - Sample Strands Agents Chat - stack AI chat application powered by Amazon Bedrock, Strands Agents, and Bedrock AgentCore with complete web interface and cloud deployment capabilities | [aws-samples/sample-strands-agents-chat](https://github.com/aws-samples/sample-strands-agents-chat) | Examples | (Community Projects / For PyPI Packages)
README
# 🤖 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](https://console.aws.amazon.com/secretsmanager)
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
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
# 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:**
```typescript
// 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:**
```typescript
// 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`
```typescript
// 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
```tsx
// 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.