adk-insurance-recommendation-agent

# Insurance Recommendation Agent This is an example project for an insurance recommendation agent powered by Google ADK. The system integrates FastAPI, Next.js, MCP Toolbox, PostgreSQL/pgvector, and Gemini/Vertex AI to demonstrate how to build an AI agent with product inquiry, FAQ semantic search, session memory, audit logging, PII protection, and real-time voice/image interaction capabilities. 👉 **Online Demo: [https://lastingyeh.github.io/adk-insurance-recommendation-agent/](https://lastingyeh.github.io/adk-insurance-recommendation-agent/)** The goal of this README is to help users quickly achieve three things: 1. Understand what problems this project solves. 2. Run the system locally. 3. Know which documents to refer to for in-depth architecture, testing, or deployment. ## Core Features - Google ADK Agent: Understands insurance needs, proactively asks questions, queries products, and generates recommended responses. - MCP Toolbox: Queries insurance products, recommendation rules, and FAQ knowledge base through controlled SQL tools. - FastAPI Backend: Provides REST API, SSE streaming response, and WebSocket real-time interaction. - Next.js Frontend: Provides insurance recommendation dialogue interface, Live mode, and Agent state visualization. - PostgreSQL + pgvector: Stores products, FAQs, sessions, audit logs, and vector data. - Multimodal Live Agent: Supports real-time voice, image, and interactive dialogue. - Security and Compliance Design: Includes JWT authentication, PII redaction, public state filtering, and audit hash chain. - Evaluation-Driven Development: Uses ADK evalsets to verify recommendation quality, security, session-aware behavior, and Live mode. - Cloud Deployment Ready: Provides Docker Compose, Cloud Run, and Terraform dev/staging/prod deployment entry. ## System Architecture  ```text 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 ```  ## Technical Composition | Category | Technology | | ---------------- | ------------------------------------ | | Agent Framework | Google ADK | | LLM / Multimodal Model | Gemini / Vertex AI | | Backend API | FastAPI, Uvicorn | | Frontend | Next.js 15, React 19, NextAuth.js | | Database | PostgreSQL, pgvector | | Tool Layer | MCP Toolbox for Databases | | Authentication | JWT, NextAuth | | Infrastructure | Docker Compose, Cloud Run, Terraform | | Testing and Evaluation | pytest, ADK eval, Locust | | Package Management | uv, npm | ## Project Directory ```text . ├── app/ # Backend Agent and FastAPI application │ ├── api/ # REST, SSE, WebSocket routes and data formats │ ├── app_utils/ # Telemetry and deployment auxiliary tools │ ├── prompts/ # Agent system prompt │ ├── security/ # Authentication, PII protection, and public state filtering │ ├── services/ # Agent execution, Live mode, Session, User, and Audit Log services │ ├── streaming/ # WebSocket upstream/downstream processing │ ├── tools/ # ADK session tools │ ├── agent.py # Agent factory and ADK app registration │ ├── config.py # Runtime settings │ └── container.py # Dependency container ├── db/ # Database schema, seed data, and MCP Toolbox settings ├── deployment/ # Terraform and deployment documents ├── docs/ # Architecture and feature documents ├── frontend/ # Next.js frontend application ├── scripts/ # Setup, data creation, and FAQ ingestion scripts ├── tests/ # Unit, integration, security, API, load, and eval tests ├── docker-compose.yml # Local container orchestration ├── Dockerfile.backend # Backend container image settings ├── Dockerfile.toolbox # Toolbox container image settings ├── Makefile # Main development command entry ├── pyproject.toml # Python project settings and dependencies └── .env.example # Environment variable template ``` ## Prerequisites Before local development, please install: - Python 3.12 - uv - Node.js 20 or later - npm - Docker and Docker Compose - Google Cloud credentials: required for Vertex AI, embedding, cloud deployment, or Toolbox semantic search Create a local environment configuration file: ```bash cp .env.example .env ``` Then modify `.env` according to your environment. ## Quick Start ### Method 1: Start using Docker Compose If you want to start the database, Toolbox, backend, and frontend at once, use this method. ```bash cp .env.example .env make up-build ``` After startup, you can open: ```text Frontend interface: http://localhost:3000 Backend API: http://localhost:8080 Health check: http://localhost:8080/healthz Readiness check: http://localhost:8080/readyz ``` Stop service: ```bash make down ``` View service logs: ```bash make logs ``` ### Method 2: Start services separately If you are developing the backend or frontend, use this method. ```bash cp .env.example .env make install-all make db-up make db-seed make db-ingest ``` Start backend: ```bash make run-fastapi ``` Start frontend in another terminal: ```bash make ui-install make ui-dev ``` Open: ```text Frontend interface: http://localhost:3000 Backend API: http://localhost:8080 ``` ## Environment Variables The application reads runtime settings from environment variables. Please use `.env.example` as a template. | Variable | Purpose | | -------------------------------- | --------------------------------------------------------- | | `GOOGLE_GENAI_USE_VERTEXAI` | Set to `1` to use Vertex AI. | | `GOOGLE_CLOUD_PROJECT` | Google Cloud project ID. | | `GOOGLE_CLOUD_LOCATION` | Google Cloud region, e.g., `us-central1`. | | `GOOGLE_API_KEY` | Google GenAI API key for local API key mode. | | `GOOGLE_APPLICATION_CREDENTIALS` | Credential file path for service account. | | `ADK_APP_NAME` | ADK application name, default is `app`. | | `DATABASE_URL` | Main database URL for container or deployment environment. | | `ADK_SESSION_DB_URI` | Database URL for ADK Session service. | | `ADK_MEMORY_MODE` | Set to `in_memory` for non-persistent session; default uses database. | | `MODEL_NAME` | Text recommendation model, default is `gemini-2.5-flash`. | | `LIVE_MODEL_NAME` | Multimodal model for WebSocket Live mode. | | `TOOLBOX_SERVER_URL` | MCP Toolbox server URL. | | `JWT_SECRET` | Backend JWT signing secret; use high-strength value in production. | | `NEXTAUTH_SECRET` | Frontend NextAuth secret; use high-strength value in production. | | `AUDIT_LOG_ENABLED` | Set to `1` to enable audit logging. | | `AUDIT_DB_PATH` | Database URL for audit log. | | `AUDIT_HASH_SALT` | Salt for audit hash chain and sensitive data hashing. | | `PII_REDACTION_ENABLED` | Set to `1` to enable PII redaction. | | `ENABLE_CLOUD_TRACING` | Enables sending traces to Google Cloud Trace. | | `ENABLE_CLOUD_LOGGING` | Enables sending logs to Google Cloud Logging. | | `BQ_ANALYTICS_DATASET` | Enables BigQuery Agent Analytics plugin. | ## Common Development Commands Most common tasks can be executed through Makefile. | Command | Description | | ------------------ | ----------------------------------------------------- | | `make help` | Displays available commands. | | `make install` | Creates Python 3.12 virtual environment and installs core dependencies. | | `make install-all` | Installs core, dev, eval, and GCP dependencies. | | `make sync` | Synchronizes Python dependencies. | | `make env-check` | Checks local tools and environment settings. | | `make db-up` | Starts local PostgreSQL and MCP Toolbox containers. | | `make db-setup` | Starts database, creates test user, and imports FAQ embeddings. | | `make run-fastapi` | Starts FastAPI backend on port 8080. | | `make ui-install` | Installs frontend dependencies. | | `make ui-dev` | Starts Next.js frontend on port 3000. | | `make up` | Starts all Docker Compose services. | | `make up-build` | Rebuilds and starts all Docker Compose services. | | `make down` | Stops Docker Compose services. | | `make logs` | Follows Docker Compose logs. | | `make clean` | Cleans Python cache and pytest cache. | | `make clean-all` | Cleans generated cache and local virtual environment. | ## API Overview The backend provides health checks, authentication, session management, Agent SSE streaming, and Live Agent WebSocket API. | Method | Path | Purpose | | -------- | -------------------------------------------------------- | -------------------------------------------- | | `GET` | `/healthz` | Basic health check. | | `GET` | `/readyz` | Check if Session store, Toolbox, etc. are ready. | | `POST` | `/auth/token` | Login and obtain JWT access token. | | `POST` | `/api/agent/run` | Run Agent and return streaming results via SSE. | | `GET` | `/apps/{app_name}/users/{user_id}/sessions` | List user sessions. | | `POST` | `/apps/{app_name}/users/{user_id}/sessions` | Create or initialize session. | | `GET` | `/apps/{app_name}/users/{user_id}/sessions/{session_id}` | Get a specific session. | | `DELETE` | `/apps/{app_name}/users/{user_id}/sessions/{session_id}` | Delete a specific session. | | `WS` | `/api/agent/live/ws/{session_id}` | Start a multimodal Live Agent session. | User, Session, and Agent endpoints require authentication. The frontend will obtain a token via `/auth/token` and send it to the backend in subsequent requests. ## Frontend The frontend is located in `frontend/` and uses Next.js and NextAuth. Common commands: ```bash make ui-install make ui-dev make ui-build ``` Important directories: - `frontend/app/`: Page routes and API proxy routes. - `frontend/components/`: Main UI components, including user mode, workbench, waveform, state tree, and timeline views. - `frontend/hooks/`: Audio, camera, screen capture, and Live Agent hooks. - `frontend/lib/`: Proxy, markdown, mock data, session storage, and auth recovery helpers. ## Database and MCP Toolbox Database-related files are located in `db/`. | File | Purpose | | --------------------- | --------------------------------------------- | | `db/schema.sql` | Main schema for products, recommendation rules, FAQs, and vector data. | | `db/audit_schema.sql` | Audit log schema. | | `db/seed.sql` | Seed data for local development. | | `db/tools.local.yaml` | Local MCP Toolbox tool definitions. | | `db/tools.cloud.yaml` | Cloud MCP Toolbox tool definitions. | MCP Toolbox provides controlled tools, including: - `search_medical_products` - `search_accident_products` - `search_family_protection_products` - `search_income_protection_products` - `get_product_detail` - `get_recommendation_rules` - `search_faq` Import FAQ embeddings: ```bash make db-ingest ``` ## Security and Compliance The project includes the following security and compliance features: - Use JWT authentication for backend API access. - Check user/session ownership at protected endpoints. - Perform PII redaction via `app/security/pii.py`. - Use public state filtering to prevent sensitive session data from being exposed to the frontend. - Record audit logs via `app/services/audit_log_service.py`. - Support audit hash chain for tamper-proof audit logs. - Allow configuration of audit retention and hashing salt. Replace local example secrets with actual values in production environments: ```text JWT_SECRET NEXTAUTH_SECRET AUDIT_HASH_SALT DATABASE_URL AUDIT_DB_PATH ``` Do not commit `.env`, service account keys, or generated secret files. ## Testing Run complete Python tests: ```bash make check ``` Run specific test groups: ```bash make test-api make test-security make test-audit ``` Tests cover unit, integration, API, security, load, and evaluation, primarily located in `tests/`. ## Evaluation ADK evalsets are located in `tests/eval/evalsets/`. Run default evaluation: ```bash make eval ``` Run all evaluations: ```bash make eval-all ``` Run specific evaluation groups: ```bash make eval-core make eval-extended make eval-safety make eval-session-aware make eval-live ``` Evaluations cover core recommendations, extended scenarios, safety behaviors, session-aware memory, and Live mode interactions. ## Deployment Deployment-related files are located in `deployment/`. | Path | Purpose | | ---------------------------------------------------- | --------------------------------------------- | | `deployment/docs/` | Deployment, CI/CD, and environment documentation. | | `deployment/terraform/bootstrap/` | Bootstrap resources for GitHub/Cloud Build. | | `deployment/terraform/dev/` | Dev environment Terraform. | | `deployment/terraform/staging/` | Staging environment Terraform. | | `deployment/terraform/prod/` | Production environment Terraform. | | `deployment/terraform/modules/agent_infrastructure/` | Shared infrastructure module. | Common deployment commands: ```bash 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 ``` Configure necessary GCP variables in `.env` before deployment: ```text GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_LOCATION ARTIFACT_REPOSITORY ENV_NAME GITHUB_OWNER GITHUB_REPO_NAME ``` ## FAQ ### Missing `.env` Create a copy from the template: ```bash cp .env.example .env ``` ### Backend not ready Check: ```text http://localhost:8080/readyz ``` If the readiness check fails, ensure PostgreSQL and MCP Toolbox are started: ```bash make db-up make toolbox-logs ``` ### Frontend cannot connect to backend Check the following variables: ```text NEXT_PUBLIC_API_URL FASTAPI_BASE_URL FASTAPI_BASE_URL_DOCKER NEXTAUTH_URL ``` Typically, use: ```text http://localhost:8080 ``` ### Login or authentication fails Confirm test users are created: ```bash make db-seed ``` Ensure `JWT_SECRET` and `NEXTAUTH_SECRET` are set consistently in backend and frontend. ### FAQ semantic search fails Confirm Google credentials are set and FAQ embeddings are imported: ```bash make db-ingest ``` ### Port is occupied Default ports: ```text Frontend: 3000 Backend: 8080 Toolbox: 5001 PostgreSQL: 5432 ``` Stop occupied services or adjust port variables in `.env`. ## Documentation Index - Backend architecture: `docs/features/backend-agent-design.md` - Frontend design: `docs/features/frontend.md` - Live streaming architecture: `docs/features/live-streaming-architecture.md` - MCP Toolbox and database tools: `docs/features/mcp-toolboxs.md` - Observability: `docs/features/obs.md` - Evaluation: `docs/features/evaluation.md` - Testing: `docs/features/testing.md` - Deployment guide: `deployment/docs/README.md` - Development and deployment plan: `deployment/docs/plan.md` - CI/CD instructions: `deployment/docs/cicd.md` - Workload Identity Federation setup: `deployment/docs/wif-setup.md` ## Contribution Before submitting changes, run: ```bash make check make test-security make eval ``` Code quality checks: ```bash make lint ``` If modifying Agent behavior, update or add evalsets in `tests/eval/evalsets/` to ensure recommendation quality and safety behaviors are verified. ## License Please add project license information here before releasing or distributing the repository. ## Disclaimer This project is for prototype design, AI technology demonstration, academic research, and cloud system architecture showcase only. All insurance recommendation results, rules, product terms, and premium calculations are fictional or for preliminary reference only and **should not be used directly in real financial or insurance business**. Actual insurance and consultation should be based on official product descriptions, policy documents, health declarations, and insurance company underwriting results.