Skip to content

Commit 3c251ae

Browse files
krokokokrokoko
authored
Merge pull request #166 from NataliaTarasovaNatoshir/bedrock-agent-python-ui-wrapper
stack to add api and frontend layer to a bedrock agent
2 parents 631913b + 9d68d82 commit 3c251ae

File tree

29 files changed

+5325
-0
lines changed

29 files changed

+5325
-0
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ This repo provides samples to demonstrate how to build your own Generative AI so
1919
|[Contract Compliance Analysis](samples/contract-compliance-analysis/)| This project automates the analysis of contracts by splitting them into clauses, determining clause types, evaluating compliance against a customer's legal guidelines, and assessing overall contract risk based on the number of compliant clauses. This is achieved through a workflow that leverages Large Language Models via Amazon Bedrock. | Backend + Frontend | Python for Backend, TypeScript (React) for Frontend |
2020
|[RFP Answers with GenAI](samples/rfp-answer-generation/)| This project provides guidance on how you can use Knowledge Bases for Amazon Bedrock with custom transformations to create draft answers for Request for Proposal (RFP) documents, streamlining the answer of new potential contracts. This is achieved through a workflow that leverages Large Language Models via Amazon Bedrock. | Backend + Frontend | Python for Backend, TypeScript (React) for Frontend |
2121
| [Code Expert](samples/code-expert/) | This project addresses the scalability limitations of manual code reviews by leveraging artificial intelligence to perform expert code reviews automatically. It leverages the [Bedrock Batch Step Functions CDK construct](https://github.com/awslabs/generative-ai-cdk-constructs/blob/main/src/patterns/gen-ai/aws-bedrock-batch-stepfn/README.md). | Backend | Python for Backend and Demo, TypeScript for CDK |
22+
|[Bedrock Agent UI Wrapper](samples/bedrock-agent-ui-wrapper/)| This sample provides a CDK construct that creates an API layer and frontend application for Amazon Bedrock Agents. It includes authentication with Amazon Cognito, agent trace streaming, and can be deployed locally or on ECS Fargate. | API layer + Frontend | Python|
23+
2224

2325
## Contributing
2426

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
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
12+
cdk.context.json

‎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: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
#
2+
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
5+
# with the License. A copy of the License is located at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
10+
# OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
11+
# and limitations under the License.
12+
#
13+
14+
15+
#!/usr/bin/env python3
16+
import os
17+
import aws_cdk as cdk
18+
import yaml
19+
from yaml.loader import SafeLoader
20+
from cdk_nag import AwsSolutionsChecks
21+
22+
from infra.capsule_stack import CapsuleStack
23+
24+
with open(os.path.join(os.path.dirname(__file__), "config.yml"), encoding="utf-8") as f:
25+
stack_config = yaml.load(f, Loader=SafeLoader)
26+
27+
app = cdk.App()
28+
env = cdk.Environment(account=os.getenv("CDK_DEFAULT_ACCOUNT"), region=os.getenv("CDK_DEFAULT_REGION"))
29+
30+
CapsuleStack(scope=app, construct_id=stack_config["stack_name"], config=stack_config, env=env)
31+
cdk.Aspects.of(app).add(AwsSolutionsChecks())
32+
33+
app.synth()

0 commit comments

Comments
 (0)