# Build Realtime Voice Agent on Amazon Bedrock
Amazon Bedrock

## Application Architecture

透過CloudFront存取Astra的Playground和後端服務。
Astra 服務呼叫以下服務：

* Amazon Transcribe:用於語音到文字的轉錄
* Amazon Bedrock:利用 Bedrock 中的基礎模型（FM）實現對話與翻譯功能
* Amazon Polly:將 Bedrock 產生的文字轉換為音訊
* Amazon SageMaker:支援自架 LLM 和 TTS 模型

## Prepare Prerequisites
### 創建 **[Agora](https://docs.agora.io/en/)** 帳號
* 進入Console頁面，創建一個 New Project

### 選擇 Amazon Bedrock 的 Model
* 需要先去 **[Amazon Bedrock console](https://us-west-2.console.aws.amazon.com/bedrock/home?region=us-west-2#/modelaccess)** 選擇 **Model Access** ，接著這次要選用 **"Mistral AI" model**


### Configure IAM User

1. Create IAM User and Access Key
* 打開 [IAM User console](https://console.aws.amazon.com/iam/home#/users)，點選右上角的 **Create User**

2. 輸入 User name，按 next
`
iam_user_voice_agent
`

3. Permissions options的部分選擇 **Attach policies directly**，接著在 Permissions policies 的部分選擇 **AdministratorAccess**

4. 在這個頁面之後，就可以直接按下 Create user

### Create access key for IAM User
在建立 IAM User 後，需要為IAM User配置一個access key，提供聊天前端頁面呼叫。

1. 所以先點選剛剛建立的 IAM User，進入管理頁面，然後在管理頁面點選 **Create access key**


2. 在 Access key best practices & alternatives 的部分選擇 **Other** ，之後點選next

3. 最後直接按下 Create access key ，接著就可以看到自己的 Access key，並可以按 **Download .csv file**，來把 Access key 存起來

## Deploy Astra Application
### Create EC2 Server
Amazon EC2 是 Amazon Web Services 的雲端伺服器

1. 在 EC2 的側欄選擇 "Instances" ，接著透過 "Launch instances" 來 create a new instance

2. OS 部分選擇 **Ubuntu**， Amazon Machine Image 的部分選擇 **Ubuntu Server 22.04 LTS (HVM)**

3. Instance type 的部分，選擇 **t3.xlarge**

4. 接著點選 **Create new key pair** 產生new key pair。
這會用在 Astra 的環境變數中，用來授權 Astra 呼叫 Bedrock 等服務。

5. Key pair name可以設為`voice_agent` ，然後就可以點下 Create key pair

6. 接下來要設定 **Network settings** ，點選右側的“Edit”，編輯網路設定。
確保檢查
* Auto-assign public IP 是否設定為 **Enable**
* Firewall (security groups)，選擇 **Create security group**
* **Security group name 有填寫名稱**，例如“voice-agent-SG”。

7. 在下面的 **Inbound Security Group Rules**，需要設定三條規則：
1. 預設情況下，應該已經有一條 Type為 **ssh Rules**
* Protocol 是否為 **TCP**
* Port range 是否為 **22**
* Source type 是否為 **Anywhere**
2. 接著按下 "Add security group rule" 新增 Type為 **Custom TCP**
* Protocol 是否為 **TCP**
* Port range 是否為 **3000**
* Source type 是否為 **Anywhere**
3. 接著按下 "Add security group rule" 新增 Type為 **Custom TCP**
* Protocol 是否為 **TCP**
* Port range 是否為 **8080**
* Source type 是否為 **Anywhere**

8. 最後在 **Configure storage** 的部分，將磁碟大小設為 30GB，最後按下 Launch instance

跳出這個畫面代表創建成功

9. 最後要記的在 Details Tab ，把 **Public IPv4 DNS**(public domain name) 複製下來

## Create CloudFront Distributions
1. 問題背景
* 瀏覽器的預設安全規則不允許在非 HTTPS 環境中啟用麥克風與攝影機。

* 部署到雲端時需設定 SSL/TLS 憑證 和 網域名稱。

2. 三種常見的 HTTPS 配置方式
1. ALB + ACM（適合正式環境）
* 使用 Application Load Balancer 接收 443 HTTPS 流量。
ALB 將流量轉發至：
HTTP:3000 的 target group（對應 Web 應用）
HTTP:8080 的 target group（可能是 API 或備援）
使用 AWS Certificate Manager（ACM）申請免費憑證。
網域名稱需綁定至 ALB。
2. CloudFront（適合快速測試環境）
* 為 EC2 的 3000 和 8080 分別建立兩個 CloudFront Distribution。
提供 HTTPS 憑證與網域。
適合單機測試、無需 ALB。
3. 自帶憑證 + Nginx（適合已有憑證的單機測試）
* 自行在 EC2 中設定 Nginx 提供 HTTPS。
Nginx 對外提供 HTTPS，內部轉發至 3000 / 8080。
需要將自有網域名稱解析至 EC2。

3. 本案例使用
選用 CloudFront Distribution 為 EC2 的 3000 / 8080 提供 HTTPS 憑證與網域名稱。

### Create CloudFront Distribution for Port 3000
1. 打開 [CloudFront console](https://console.aws.amazon.com/cloudfront/v4/home)

2. 去 Create distribution

3. **Origin domain** 就是把剛剛複製的 **Public IPv4 DNS** 貼在這裡，接這就跟著以下步驟去做設定

* **Description - optional** 的部分，可以根據 **HTTP port** 去做註記，這樣會比較好分辨

### Create CloudFront Distribution for Port 8080
1. Port 8080 的部分與 Port 3000 的設定大致相同，主要不同的地方有兩個：
* HTTP Port： astra-8080
* Name： 8080

2. 最後要記得複製 **8080的 distribution domain name**

## Log in to the EC2 Instance
### Logging in to the Instance
在 Log in 之前，需要先在 EC2 Instance 頁面確認Instance已完全啟動，狀態檢查顯示綠色。

### 1. Connecting via Local Terminal
1. 可以在 Details 的地方找到 **Public IPv4 address** ，並點選 open address 就可以 Connect

2. 首次連接時，可能會詢問 key pair 資訊是否正確。如果遇到這種情況，就輸入“yes”。如果連接成功，您應該會看到類似下面的介面。

### 2. Connecting via EC2 Instance Connect
1. 首先，先把要打開的 EC2 Instance 打勾，接著按下 Connect

2. 會跳出這個畫面，確認裡面的設定是否跟下圖相符，如果一樣就可以按 Connect

3. 接著也會跳到類似的視窗

## Deploy and Launch Astra Application
Astra 應用程式由前端和後端元件組成，會使用 Docker 啟動，所以我們首先需要安裝 Docker 和 Docker Compose，然後可以使用 Docker Compose 啟動 Astra 應用程式。
### Install Docker & Docker Compose
* 安裝指令如下：
1. 配置 apt 來源

    # Add Docker's official GPG key:
    sudo apt-get update
    sudo apt-get install ca-certificates curl
    sudo install -m 0755 -d /etc/apt/keyrings
    sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o     /etc/apt/keyrings/docker.asc
    sudo chmod a+r /etc/apt/keyrings/docker.asc

    # Add the repository to Apt sources:
    echo \
    "deb [arch=$(dpkg --print-architecture) signed-    by=/etc/apt/keyrings/docker.asc]     https://download.docker.com/linux/ubuntu \
    $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
    sudo apt-get update

2. 安裝最新的 Docker

    sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3. 驗證 Docker 安裝

    sudo docker run hello-world

4. 允許普通使用者執行 Docker

    # Create the docker group.
    sudo groupadd docker

    # Add your user to the docker group
    sudo usermod -aG docker $USER

    newgrp docker

    # verify 
    docker run hello-world

5. 安裝 Docker Compose

    sudo apt-get update
    sudo apt-get install docker-compose-plugin -y

    # verify
    docker compose version

### Deploy Astra Application
1. Clone the code locally

    cd ~
    git clone -b amazon-aio https://github.com/chen188/Astra.ai

2. 準備設定檔，且需要改兩個.env擋
In the project's root directory, execute the following commands to provide configuration files.

    cd ~/Astra.ai

    # Create .env from the example
    cp ./.env.example ./.env

    # Create property.json from the example
    cp ./agents/property.json.example ./agents/property.json

    # Create .env from example
    cp ./playground/.env.example ./playground/.env

3. After that, you need to modify the .env file in the project code root directory, adjusting the following configurations
1. 在 /Astra.ai 底下執行 `vim .env`
* 這裡主要就是要**把4個key填進去**，前兩個是剛剛辦 AGORA 時所存的 Key，後兩個是在建立 IAM 時，所存的 Key
* AGORA_APP_ID=<your-agora-app-id>
* AGORA_APP_CERTIFICATE=<your-agora-app-certificate>
* AWS_ACCESS_KEY_ID=<your-aws-access-key-id>
* AWS_SECRET_ACCESS_KEY=<your-aws-access-key>

        # Agora App ID and Agora App Certificate
        # required: this variable must be set
        AGORA_APP_ID=<your-agora-app-id>
        AGORA_APP_CERTIFICATE=<your-agora-app-certificate>

        # Extension: bedrock_llm
        # Extension: polly_tts
        # Extension: transcribe_asr
        AWS_ACCESS_KEY_ID=<your-aws-access-key-id>
        AWS_SECRET_ACCESS_KEY=<your-aws-access-key>

        # model id supported by Bedrock Converse API    
        AWS_BEDROCK_MODEL=us.amazon.nova-pro-v1:0

        AWS_REGION=us-west-2 # the Region you're using

2. 在 /Astra.ai/playground 底下執行 `vim .env`
* 這裡主要是要將 REQUEST_URL 改成剛剛複製 Port 8080 的 **distribution domain name** ，如下圖

4. 啟動應用程式

docker compose up

5. 正常啟動後，應該會看到類似以下內容的輸出：

Astra_agents_dev      | >> build agents
Astra_agents_dev      | cd agents && ./scripts/install_deps_and_build.sh linux x64 && mv bin/main bin/worker
Astra_agents_dev      | >> run server
Astra_agents_dev      | server/bin/api
Astra_agents_dev      | [GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
Astra_agents_dev      | 
Astra_agents_dev      | [GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
Astra_agents_dev      |  - using env:   export GIN_MODE=release
Astra_agents_dev      |  - using code:  gin.SetMode(gin.ReleaseMode)
Astra_agents_dev      | 
Astra_agents_dev      | [GIN-debug] GET    /                         --> app/internal.(*HttpServer).handlerHealth-fm (4 handlers)
Astra_agents_dev      | [GIN-debug] GET    /health                   --> app/internal.(*HttpServer).handlerHealth-fm (4 handlers)
Astra_agents_dev      | [GIN-debug] POST   /ping                     --> app/internal.(*HttpServer).handlerPing-fm (4 handlers)
Astra_agents_dev      | [GIN-debug] POST   /start                    --> app/internal.(*HttpServer).handlerStart-fm (4 handlers)
Astra_agents_dev      | [GIN-debug] POST   /stop                     --> app/internal.(*HttpServer).handlerStop-fm (4 handlers)
Astra_agents_dev      | [GIN-debug] POST   /token/generate           --> app/internal.(*HttpServer).handlerGenerateToken-fm (4 handlers)
Astra_agents_dev      | 2024/08/09 05:29:22 INFO server start port=8080 service=HTTP_SERVER

...

Astra_playground_dev  | > Astra-playground@0.1.0 start
Astra_playground_dev  | > next start
Astra_playground_dev  | 
Astra_playground_dev  |   ▲ Next.js 14.2.4
Astra_playground_dev  |   - Local:        http://localhost:3000
...