保險推薦 Agent

這是一個以 Google ADK 為核心的保險推薦 Agent 範例專案。系統整合 FastAPI、Next.js、MCP Toolbox、PostgreSQL/pgvector 與 Gemini/Vertex AI，示範如何建立具備產品查詢、FAQ 語意搜尋、會話記憶、稽核紀錄、PII 保護，以及即時語音/影像互動能力的 AI Agent。

👉 線上展示專案：https://lastingyeh.github.io/adk-insurance-recommendation-agent/

這份 README 的目標是讓使用者快速完成三件事：

1. 了解這個專案解決什麼問題。
2. 在本機把系統跑起來。
3. 知道要深入架構、測試或部署時該看哪些文件。

核心功能

• Google ADK Agent：理解保險需求、主動追問、查詢產品並產生推薦回覆。
• MCP Toolbox：透過受控 SQL 工具查詢保險產品、推薦規則與 FAQ 知識庫。
• FastAPI 後端：提供 REST API、SSE 串流回覆與 WebSocket 即時互動。
• Next.js 前端：提供保險推薦對話介面、Live mode 與 Agent 狀態視覺化。
• PostgreSQL + pgvector：儲存產品、FAQ、Session、Audit Log 與向量資料。
• Multimodal Live Agent：支援即時語音、畫面與互動式對話。
• 安全與合規設計：包含 JWT 驗證、PII redaction、public state filtering 與 audit hash chain。
• 評估驅動開發：使用 ADK evalsets 驗證推薦品質、安全性、session-aware 行為與 Live mode。
• 雲端部署準備：提供 Docker Compose、Cloud Run 與 Terraform dev/staging/prod 部署入口。

系統架構

Frontend (Next.js)
    |
    | REST / SSE / WebSocket
    v
FastAPI Backend
    |
    +-- Google ADK Runner
    |       |
    |       +-- Insurance Agent
    |       +-- Session tools
    |       +-- MCP Toolbox tools
    |
    +-- Session Service
    +-- User Service
    +-- Audit Log Service
    +-- Live Agent Service
    |
    v
PostgreSQL / pgvector
    |
    +-- Insurance products
    +-- Recommendation rules
    +-- FAQ knowledge
    +-- Session state
    +-- Audit logs

技術組成

專案目錄

.
├── app/                         # 後端 Agent 與 FastAPI 應用程式
│   ├── api/                     # REST、SSE、WebSocket 路由與資料格式
│   ├── app_utils/               # Telemetry 與部署輔助工具
│   ├── prompts/                 # Agent system prompt
│   ├── security/                # 驗證、PII 保護與 public state filtering
│   ├── services/                # Agent 執行、Live mode、Session、User 與 Audit Log 服務
│   ├── streaming/               # WebSocket upstream/downstream 處理
│   ├── tools/                   # ADK session tools
│   ├── agent.py                 # Agent factory 與 ADK app 註冊
│   ├── config.py                # 執行時設定
│   └── container.py             # Dependency container
├── db/                          # 資料庫 schema、seed data 與 MCP Toolbox 設定
├── deployment/                  # Terraform 與部署文件
├── docs/                        # 架構與功能文件
├── frontend/                    # Next.js 前端應用程式
├── scripts/                     # 設定、資料建立與 FAQ ingestion 腳本
├── tests/                       # Unit、integration、security、API、load 與 eval 測試
├── docker-compose.yml           # 本機容器編排
├── Dockerfile.backend           # 後端容器映像設定
├── Dockerfile.toolbox           # Toolbox 容器映像設定
├── Makefile                     # 主要開發指令入口
├── pyproject.toml               # Python 專案設定與依賴
└── .env.example                 # 環境變數範本

前置需求

本機開發前請先安裝：

• Python 3.12
• uv
• Node.js 20 或更新版本
• npm
• Docker 與 Docker Compose
• Google Cloud credentials：使用 Vertex AI、embedding、雲端部署或 Toolbox 語意搜尋時需要

先建立本機環境設定檔：

cp .env.example .env

接著依照你的環境修改 .env。

快速開始

方式一：使用 Docker Compose 啟動

如果你想一次啟動資料庫、Toolbox、後端與前端，建議使用這個方式。

cp .env.example .env
make up-build

啟動後可開啟：

前端介面：http://localhost:3000
後端 API：http://localhost:8080
健康檢查：http://localhost:8080/healthz
就緒檢查：http://localhost:8080/readyz

停止服務：

make down

查看服務紀錄：

make logs

方式二：分開啟動服務

如果你正在開發後端或前端，建議用這個方式。

cp .env.example .env
make install-all
make db-up
make db-seed
make db-ingest

啟動後端：

make run-fastapi

在另一個終端機啟動前端：

make ui-install
make ui-dev

開啟：

前端介面：http://localhost:3000
後端 API：http://localhost:8080

環境變數

應用程式會從環境變數讀取執行設定。請以 .env.example 為範本。

常用開發指令

大部分常見工作都可以透過 Makefile 執行。

API 概覽

後端提供健康檢查、驗證、Session 管理、Agent SSE 串流與 Live Agent WebSocket API。

使用者、Session 與 Agent endpoint 都需要驗證。前端會透過 /auth/token 取得 token，並在後續請求中轉送給後端。

前端

前端位於 frontend/，使用 Next.js 與 NextAuth。

常用指令：

make ui-install
make ui-dev
make ui-build

重要目錄：

• frontend/app/：頁面路由與 API proxy routes。
• frontend/components/：主要 UI 元件，包含 user mode、workbench、waveform、state tree 與 timeline views。
• frontend/hooks/：audio、camera、screen capture 與 Live Agent hooks。
• frontend/lib/：proxy、markdown、mock data、session storage 與 auth recovery helpers。

資料庫與 MCP Toolbox

資料庫相關檔案位於 db/。

MCP Toolbox 提供的受控工具包含：

• search_medical_products
• search_accident_products
• search_family_protection_products
• search_income_protection_products
• get_product_detail
• get_recommendation_rules
• search_faq

匯入 FAQ embeddings：

make db-ingest

安全與合規

專案包含以下安全與合規設計：

• 使用 JWT 驗證後端 API 存取。
• 在受保護 endpoint 檢查 user/session ownership。
• 透過 app/security/pii.py 進行 PII redaction。
• 使用 public state filtering，避免敏感 session data 外洩到前端。
• 透過 app/services/audit_log_service.py 記錄 audit logs。
• 支援 audit hash chain，讓稽核紀錄具備防竄改檢查能力。
• 可設定 audit retention 與 hashing salt。

正式環境請務必替換本機範例 secret：

JWT_SECRET
NEXTAUTH_SECRET
AUDIT_HASH_SALT
DATABASE_URL
AUDIT_DB_PATH

不要提交 .env、service account key 或任何產生的 secret 檔案。

測試

執行完整 Python 測試：

make check

執行特定測試群組：

make test-api
make test-security
make test-audit

測試涵蓋 unit、integration、API、security、load 與 eval，主要位於 tests/。

評估

ADK evalsets 位於 tests/eval/evalsets/。

執行預設評估：

make eval

執行所有評估：

make eval-all

執行特定評估群組：

make eval-core
make eval-extended
make eval-safety
make eval-session-aware
make eval-live

評估範圍包含核心推薦、延伸情境、安全行為、session-aware memory 與 Live mode 互動。

部署

部署相關檔案位於 deployment/。

常用部署指令：

make tf-gen-config
make tf-plan ENV_NAME=dev
make tf-apply ENV_NAME=dev
make build-push
make gcp-deploy ENV_NAME=dev

部署前，請在 .env 設定必要的 GCP 變數：

GOOGLE_CLOUD_PROJECT
GOOGLE_CLOUD_LOCATION
ARTIFACT_REPOSITORY
ENV_NAME
GITHUB_OWNER
GITHUB_REPO_NAME

常見問題

缺少 .env

從範本建立：

cp .env.example .env

後端尚未就緒

檢查：

http://localhost:8080/readyz

如果 readiness check 失敗，確認 PostgreSQL 與 MCP Toolbox 已啟動：

make db-up
make toolbox-logs

前端連不到後端

檢查以下變數：

NEXT_PUBLIC_API_URL
FASTAPI_BASE_URL
FASTAPI_BASE_URL_DOCKER
NEXTAUTH_URL

本機瀏覽器通常使用：

http://localhost:8080

登入或驗證失敗

先確認測試使用者已建立：

make db-seed

也請確認 JWT_SECRET 與 NEXTAUTH_SECRET 在後端與前端設定一致。

FAQ 語意搜尋失敗

確認 Google credentials 已設定，並且 FAQ embeddings 已匯入：

make db-ingest

Port 已被占用

預設 port 如下：

前端：3000
後端：8080
Toolbox：5001
PostgreSQL：5432

請停止占用服務，或在 .env 中調整對應 port 變數。

文件索引

• 後端架構：docs/features/backend-agent-design.md
• 前端設計：docs/features/frontend.md
• 即時串流架構：docs/features/live-streaming-architecture.md
• MCP Toolbox 與資料庫工具：docs/features/mcp-toolboxs.md
• Observability：docs/features/obs.md
• Evaluation：docs/features/evaluation.md
• Testing：docs/features/testing.md
• 部署指南：deployment/docs/README.md
• 開發與部署計畫：deployment/docs/plan.md
• CI/CD 說明：deployment/docs/cicd.md
• Workload Identity Federation 設定：deployment/docs/wif-setup.md

貢獻方式

提交變更前，建議先執行：

make check
make test-security
make eval

程式品質檢查：

make lint

如果修改 Agent 行為，請同步新增或更新 tests/eval/evalsets/ 中的 evalset，讓推薦品質與安全行為可以被持續驗證。

授權

可自由使用、修改與散布程式碼，但若分享完整程式碼請註明出處喔 ^^。

免責聲明

本專案僅用於原型設計、AI 技術展示、學術研究與雲端系統架構示範。所有保險推薦結果、規則、商品條款與保費計算皆為虛構 or 僅供初步參考，不可直接用於真實金融或保險業務。實際投保與保險諮詢仍需以保險公司官方商品說明、要保書、健康告知書與保險公司核保結果為準。