Skip to content

Commit 9254716

Browse files
NataliaTarasovaNatoshirNataliaTarasovaNatoshir
committed
stack to add api and frontend layer to a bedrock agent
1 parent 74182fd commit 9254716

File tree

29 files changed

+5216
-0
lines changed

29 files changed

+5216
-0
lines changed

‎samples/bedrock-agent-ui-wrapper/.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
*.swp
2+
package-lock.json
3+
__pycache__
4+
.pytest_cache
5+
.venv
6+
*.egg-info
7+
.streamlit
8+
9+
# CDK asset staging directory
10+
.cdk.staging
11+
cdk.out

‎samples/bedrock-agent-ui-wrapper/README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
2+
# 📦 Welcome to Capsule!
3+
4+
This is a stack to wrap a Bedrock Agent for simple applications.
5+
6+
- **It provides:**
7+
- constructs for an API layer between your Bedrock Agent and your Frontend layer
8+
- frontend layer to jumpstart a simplistic app either hosted locally or on ECS Fargate
9+
10+
Capsule stacks support streaming of the agent traces and authentication with Amazon Cognito
11+
12+
![homepage](images/streamlit_homepage.png)
13+
![chat](images/streamlit_chat.png)
14+
15+
## 🎯 When Should You Use Capsule?
16+
17+
Already have an Amazon Bedrock agent? Capsule helps you transform it into a production-ready chat application with:
18+
19+
- 🔌 **Ready-to-Use API Layer**: Pre-built constructs for seamless communication between Bedrock Agent and frontend
20+
- 🎯 **Flexible Deployment Options**: Run locally or deploy to ECS Fargate with one command
21+
- 🔒 **Built-in Security**: Integrated Amazon Cognito authentication
22+
- 📊 **Real-time Agent Traces**: Built-in streaming support for agent debugging and monitoring
23+
- 🎨 **Customizable UI**: Streamlit-based interface that you can modify to match your needs
24+
25+
Use Capsule when you need to:
26+
27+
1. **Deploy Your Existing Bedrock Agent as a Chat App**: Transform your agent into a secure, production-ready chat interface in minutes
28+
2. **Stream Agent Responses in Real-Time**: Leverage GraphQL subscriptions for WebSocket-style streaming of chat interactions
29+
3. **Secure Your Agent**: Get pre-configured Cognito authentication and API protection out of the box
30+
4. **Debug Agent Behavior**: Built-in agent trace streaming for quick troubleshooting in chat conversations
31+
32+
Perfect for teams who have a Bedrock Agent and want to quickly deploy it as a chat application without dealing with infrastructure setup and API design.
33+
34+
## 💡 Use Case Examples
35+
36+
### Customer Service Bot
37+
Deploy a customer service agent with:
38+
- Custom branding and UI
39+
- Secure authentication for support staff
40+
- Real-time conversation monitoring
41+
42+
### Document Analysis Assistant
43+
Create an AI assistant that:
44+
- Processes uploaded documents
45+
- Provides insights and summaries
46+
- Maintains conversation context
47+
48+
### Internal Knowledge Base Agent
49+
Build a corporate knowledge assistant with:
50+
- Secure access control
51+
- Custom prompt suggestions
52+
- Integration with internal systems
53+
54+
55+
# How to deploy the stack?
56+
This section describes how to build and deploy the application in an AWS account.
57+
58+
## 1. Prerequisites
59+
- **AWS Account:**
60+
- Make sure you have access to an AWS account and installed the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
61+
on your local host.
62+
- We suggest to configure a named profile to send request to the target account more
63+
easily: `aws configure --profile [profile-name]`
64+
- **Python**:
65+
- This solutions used the Python SDK of the AWS CDK to describe the architecture.
66+
- Use Python ^3.12
67+
- **The AWS CDK**:
68+
- The AWS CDK requires a Node.js runtime.
69+
- [Install](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_install)
70+
the AWS CDK using Node Package Manager: `npm install -g aws-cdk`
71+
- **Docker**:
72+
- Deploying this CDK application involves building Dockerfiles and
73+
therefore requires a [Finch](https://runfinch.com/docs/managing-finch/macos/installation/) or Docker installed and virtual machine running.
74+
75+
## 2. Clone the repository
76+
Clone the project repository to the location of your choice
77+
78+
## 3. Create, activate and set up the Python virtual environment
79+
Navigate to the project folder and run the following commands (MacOS, Linux)
80+
81+
This project uses [Poetry](https://python-poetry.org/) library for Python packaging
82+
and dependency management. Install Poetry if you don't have it already
83+
```bash
84+
pip install poetry
85+
```
86+
87+
Create and activate the Python virtual environment:
88+
```bash
89+
poetry shell
90+
```
91+
92+
Install project dependencies
93+
```bash
94+
poetry install
95+
```
96+
97+
For information, here are a few useful Poetry commands:
98+
99+
* `poetry add <package-name>` adds a package to [pyproject.toml](pyproject.toml)
100+
and update [poetry.lock](poetry.lock)
101+
* `poetry remove <package-name>` removes a package to [pyproject.toml](pyproject.toml)
102+
and update [poetry.lock](poetry.lock)
103+
104+
Do not manually modify the file `pyproject.toml` if you wish to update the project
105+
dependencies. Refer to Poetry's documentation for the full list of [commands](https://python-poetry.org/docs/cli/).
106+
107+
## 4. Configure the stack
108+
Open the `config.yaml` file located at the project's root. This files gathers the
109+
configuration of the CDK application and therefore of the deployed architecture.
110+
111+
Modify this file as required:
112+
113+
* Provide your agent credentials (agent_id and agent_alias_id). If you leave them empty - a "dummy" Bedrock Agent will be created for you for testing purposes
114+
* Configure UI deployment. If you set `deploy_on_fargate: true` - UI will be hosted on ECS Fargate behind a Cloudfront distribution. Otherwise set `deploy_on_fargate: false`, you will be able to access UI by hosting the streamlit app locally
115+
116+
## 5. Bootstrap the CDK environment
117+
If you never deployed an application in the targeted AWS Region of the selected AWS
118+
account, you first need to initialize ("bootstrap") the environment.
119+
120+
More concretely, when you bootstrap a CDK environment, the CDK will create a few resources
121+
it needs to operate (S3 bucket and ECR repository to store the stack's assets, a few
122+
IAM roles assumed for different tasks, etc.).
123+
124+
Bootstrap your account by running the following command:
125+
126+
```bash
127+
cdk bootstrap --profile [profile-name]
128+
```
129+
130+
## 6. Deploy the CDK application
131+
Since deploying the application involves building Dockerfiles, make sure a Docker/Finch
132+
daemon is running on your host.
133+
134+
Deploy the stack by running the following command:
135+
136+
```bash
137+
cdk deploy --profile [profile-name]
138+
```
139+
140+
## Important: Configuring Cognito URLs for Fargate Deployment
141+
142+
When deploying on Fargate, you need to configure the Cognito authentication URLs. Follow these steps:
143+
144+
### A. Get the URLs from Stack Output
145+
After stack deployment completes, locate and copy two values from the stack outputs:
146+
- `CognitoCallbackUrl`
147+
- `CognitoLogoutUrl`
148+
149+
![Stack output showing Cognito URLs](images/Stack_Output.png)
150+
151+
### B. Navigate to Cognito Settings
152+
In the AWS Console:
153+
1. Go to Amazon Cognito
154+
2. Select the latest `CAPSULE-api-userpool`
155+
3. Click on "App integration" tab
156+
4. Under "App clients", find the Capsule App client
157+
5. Click "Edit"
158+
159+
![Navigating Cognito settings](images/Cognito_1.png)
160+
161+
### C. Update URLs
162+
In the console:
163+
1. Click Add another URL and paste the `CognitoCallbackUrl` into "Allowed callback URLs"
164+
2. Click Add another URL paste the `CognitoLogoutUrl` into "Allowed sign-out URLs"
165+
3. Click "Save changes"
166+
167+
![Adding callback and sign-out URLs](images/Cognito_2.png)
168+
169+
### D. Wait for Changes
170+
Allow 1-2 minutes for the changes to propagate before accessing your app.
171+
172+
> ⚠️ Note: Your app won't authenticate properly until these URLs are configured correctly.
173+
174+
175+
## 7. Try out your app!
176+
Talk with your agent:
177+
178+
* Add your app users to the created Cognito Pool
179+
* If you chose UI deployment on Fargate, go to the `AppUrl` in the stack output parameters
180+
* Alternatively, host streamlit UI locally:
181+
* Create secrets file for streamlit `streamlit_app/.streamlit/secrets.toml`
182+
* Fill in secrets with values from the stack output:
183+
```bash
184+
COGNITO-APP-CLIENT-ID = "<YOUR COGNITO APP CLIENT ID>"
185+
COGNITO-DOMAIN-PREFIX = "<YOUR COGNITO DOMAIN PREFIX>"
186+
APPSYNC-API-ENDPOINT = "<YOUR APPSYNC API ENDPOINT>"
187+
AWS-REGION = "<YOUR AWS REGION>"
188+
REDIRECT_URI = "http://localhost:8501"
189+
LOGOUT_URI = "http://localhost:8501"
190+
```
191+
* Run your streamlit app (from the project root folder)
192+
```bash
193+
cd streamlit_app
194+
streamlit run app.py
195+
```
196+
197+
## 8. Configure your app UI
198+
* The starting implementation is very basic in terms of messages formatting. Make sure to add formatting or filtering for the trace messages: adjust `format_messages` method in `streamlit_app/app.py` according to your needs
199+
* In general, change `streamlit_app/app.py` for any UI changes like adding logos, changing prompt suggestions, etc
200+
* If you need to use additional logic in your app, for example, add presigned url generation for retrieved documents - adjust your UI in `streamlit_app/app.py` and add corresponding appsync mutations in `infra/frontend_construct/frontend_fargate_construct.py`

‎samples/bedrock-agent-ui-wrapper/RESOURCES.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Resources Created by the Solution
2+
3+
This document provides a comprehensive list of all AWS resources created by this solution.
4+
5+
## Compute Resources
6+
- **ECS Fargate Cluster**
7+
- Task Definition
8+
- Fargate Service
9+
- Container running Streamlit application
10+
- CloudWatch Log Group for container logs
11+
12+
## Networking
13+
- **VPC Resources**
14+
- VPC with 2 Availability Zones
15+
- Public Subnets
16+
- Private Subnets
17+
- NAT Gateway
18+
- Internet Gateway
19+
- Route Tables
20+
- Network ACLs
21+
22+
- **Load Balancer**
23+
- Application Load Balancer
24+
- ALB Target Group
25+
- ALB Listener (Port 80)
26+
27+
- **Security Groups**
28+
- ALB Security Group
29+
- ECS Fargate Service Security Group
30+
31+
## Authentication & Authorization
32+
- **Amazon Cognito**
33+
- User Pool
34+
- User Pool Client
35+
- User Pool Domain
36+
37+
## API & GraphQL
38+
- **AWS AppSync**
39+
- GraphQL API
40+
- API Schema
41+
- API Resolvers
42+
- WebSocket API Endpoint
43+
44+
## Storage & Secrets
45+
- **AWS Secrets Manager**
46+
- AppSync Endpoint Secret
47+
- Cognito App Client Secret
48+
- Cognito Domain Prefix Secret
49+
- Region Secret
50+
- Redirect URI Secret
51+
- Logout URI Secret
52+
53+
## AI/ML
54+
- **Amazon Bedrock**
55+
- Bedrock Agent
56+
- Agent Actions
57+
- Agent Schema
58+
59+
## IAM Resources
60+
- **IAM Roles**
61+
- ECS Task Role
62+
- ECS Task Execution Role
63+
- AppSync Service Role
64+
- Bedrock Agent Role
65+
66+
- **IAM Policies**
67+
- Task Role Policies
68+
- Task Execution Role Policies
69+
- AppSync Service Role Policies
70+
- Bedrock Agent Role Policies
71+
72+
## Logging & Monitoring
73+
- **CloudWatch**
74+
- Container Log Groups
75+
- ALB Access Logs
76+
- VPC Flow Logs
77+
- Metric Alarms (if configured)
78+
79+
## Resource Naming Convention
80+
All resources are prefixed with the stack name and construct ID for easy identification:
81+
- Stack Name: `{stack-name}`
82+
- Construct ID: `{construct-id}`
83+
84+
## Resource Dependencies
85+
- VPC is required for ECS Fargate and ALB deployment
86+
- Cognito User Pool is required for authentication
87+
- AppSync API depends on Cognito for authorization
88+
- Secrets Manager secrets are used by the ECS tasks
89+
- Bedrock Agent depends on the AppSync API for integration
90+
91+
## Clean Up
92+
When destroying this solution through CDK, all resources will be removed except:
93+
1. CloudWatch Log Groups
94+
2. Any manually created resources not part of the CDK stack
95+
96+
## Notes
97+
- Some resources may incur costs even when not actively used
98+
- NAT Gateway is deployed in a single AZ to minimize costs
99+
- ALB is internet-facing and restricted to CloudFront IPs

‎samples/bedrock-agent-ui-wrapper/app.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
2+
#!/usr/bin/env python3
3+
import os
4+
import aws_cdk as cdk
5+
import yaml
6+
from yaml.loader import SafeLoader
7+
from cdk_nag import AwsSolutionsChecks
8+
9+
from infra.capsule_stack import CapsuleStack
10+
11+
with open(os.path.join(os.path.dirname(__file__), "config.yml"), encoding="utf-8") as f:
12+
stack_config = yaml.load(f, Loader=SafeLoader)
13+
14+
app = cdk.App()
15+
env = cdk.Environment(account=os.getenv("CDK_DEFAULT_ACCOUNT"), region=os.getenv("CDK_DEFAULT_REGION"))
16+
17+
CapsuleStack(scope=app, construct_id=stack_config["stack_name"], config=stack_config, env=env)
18+
cdk.Aspects.of(app).add(AwsSolutionsChecks())
19+
20+
app.synth()

0 commit comments

Comments
 (0)