FinSavant: Dazbo's Google Cloud FinOps Intelligence

An agentic FinOps solution for Google Cloud Platform (GCP) created by Dazbo that empowers Cloud Platform Engineers and FinOps Practitioners to manage, understand, and optimise cloud spend across their entire organisation.

Table of Contents

• Features
• Associated Articles
• Target Audience
• Success Metrics
• Project Structure
• Requirements
• Quick Start
• Commands
• Local Development & Testing Flow
  • Run as Standalone Services (Hot-Reloading)
  • Step 1: Initialise Dependencies
  • Step 2: Run the Application
  • Run as a Single Docker Container
  • Step 3: Run Tests & Quality Gates
  • Interactive Notebook Prototyping
• CI/CD & Deployment Flow
  • GitHub Actions Pipelines
• IAM Permissions & Validation
• Technical Architecture
• Useful Links & References
• License

Features

• Cost Exploration & Forecasting: BQ billing data analysis.
• Zombie Asset Sweeps: CAI-based scans of unattached disks and idle IPs.
• AI-powered Rightsizing Recommendations: Gemini Cloud Assist and Developer Knowledge grounded best practices.

For detailed functional specifications, refer to the Product Requirement Document.

Associated Articles

This repository is associated with a multi-part series of articles documenting the design, implementation, and deployment of FinSavant:

1. Goals, Architecture, and Tech Stack: Capabilities, project goals, target architecture, technology stack, and design decisions.
2. Dev Environment Setup with Google Antigravity, ADK, Agents CLI, MCP & Skills
3. Building the dynamic UI with A2UI
4. Authentication with IAP, Terraform, and CI/CD
5. Observing, Evaluating & Tuning Our Agent with Gemini Enterprise Agent Platform

Target Audience & Success Metrics

For details on user personas, organizational scopes, and key success metrics, see the Product Requirement Document.

Project Structure

smart-gcp-finops/
├── agent/                # ADK agent package Runtime Package (ADK Agent)
│   ├── finops_agent/          # Root agent
│   │   ├── app_utils/             # CAI, BQ tools, credential & cache helpers
│   │   ├── agent.py               # Root agent definitions & tool routing
│   │   ├── deploy_to_agent_runtime.py   # Deploys agent to Agent Runtime
│   │   ├── agent_runtime_app.py   # Bootstrapper for remote Agent Runtime
│   │   └── requirements.txt   # Dynamically generated at deploy time
│   ├── .env              # Agent specific environment vars
│   ├── agents-cli-manifest.yaml   # ADK Agent CLI manifest to support lifecycle
│   ├── Dockerfile             # For deploying agent to Agent Runtime
│   └── pyproject.toml         # Agent runtime dependencies
├── bff/                  # Backend-for-Frontend (API)
│   ├── Dockerfile             # UI/BFF-only Dockerfile
│   └── fast_api_app.py        # BFF FastAPI
├── deployment/           # Infrastructure & Setup
│   └── terraform/             # TF IaC
├── docs/                 # Project documentation
│   ├── images/                # Diagrams and architectural visual assets
│   ├── DESIGN.md              # Visual identity, components, and UI design
│   ├── PRODUCT.md             # Product requirements, specifications, and success metrics
│   ├── architecture-and-walkthrough.md # Solution blueprints, ADRs, and component data flows
│   ├── authentication-and-costs.md # Authentication model (Vertex AI vs API key) and cost drivers
│   └── testing.md             # Testing strategy and verification instructions
├── frontend/             # React UI frontend
│   ├── src/                   # Application source code
│   └── index.html             # Homepage
├── notebooks/            # Jupyter notebooks for prototyping and evaluation
│   └── adk_app_testing.ipynb  # Interactive playground for testing local and remote runs
├── scripts/              # Env setup and other utility scripts
├── tests/                # Unit and integration test suites
├── .agents/              # Workspace Gemini configuration (e.g. MCP settings)
├── .github/              # GitHub Actions workflows and CI/CD
├── .env                  # Root environment vars (dev setup, unified container)
├── .envrc                # Automatically launch when entering this directory
├── .gitignore            # Exclude from git
├── Dockerfile            # Configuration for the unified development image
├── Makefile              # Centralised developer convenience commands
├── GEMINI.md             # Development agent context & guidelines
├── LICENSE               # Standard open-source license file
├── pyproject.toml        # Root project configuration / dependencies
├── README.md             # Developer documentation homepage
└── TODO.md               # TODO list

Dependency Management

[!IMPORTANT]
This repository maintains two separate pyproject.toml files:

• Root pyproject.toml: Governs the BFF (Backend-for-Frontend) container, serving FastAPI, Uvicorn, and client SDKs on Cloud Run.
• Agent agent/pyproject.toml: Governs the standalone ADK (Agent Development Kit) agent environment deployed to the managed Vertex AI Agent Runtime.

• Agent agent/pyproject.toml: Governs the standalone ADK (Agent Development Kit) agent environment deployed to the managed Vertex AI Agent Runtime.

Developers must maintain and synchronise both files when adding or updating shared dependencies (such as google-adk, google-genai, or google-cloud-asset). After modifying either pyproject.toml, run uv lock in the project root to update the workspace-wide uv.lock file.

Requirements

Before you begin, ensure you have:

• uv: Python package manager (Python 3.13+)
• Google Cloud SDK: Authenticated with your GCP project
• Terraform: For infrastructure deployment
• make: Build automation tool

Quick Start

Install required packages and launch the local development environment:

make install && make playground

Commands

Local Development & Testing Flow

The application can be run locally in two different ways:

1. Standalone Services (recommended for active development): Runs the React frontend and FastAPI backend as separate, hot-reloading processes.
2. Unified Docker Container: Runs the entire application (compiled React assets + FastAPI backend) inside a single local Docker container, replicating the production environment.

Run as Standalone Services (Hot-Reloading)

To run the React frontend and FastAPI backend locally as standalone services, follow this developer workflow:

Step 1: Initialise Dependencies

Install both the backend Python package dependencies (uv sync) and the React frontend package dependencies (npm install) automatically in one step:

make install

Step 2: Run the Application

You will need two separate terminal sessions to run both servers concurrently with hot-reloading:

• Terminal 1 (Backend): Spin up the FastAPI Backend BFF on http://localhost:8000:

  make run-backend
  

• Terminal 2 (Frontend): Spin up the Vite dev server on http://localhost:5173:

  make run-frontend
  

Open your browser and navigate to http://localhost:5173. The frontend automatically proxies all /api and /events queries to the backend.

Run as a Single Docker Container

Alternatively, you can run the entire unified container (which bundles both the compiled React frontend and the FastAPI backend) locally using Docker:

# Build the unified container image locally
make docker-build

# Run the container locally in fallback mode (executes agent locally in-container)
make docker-run

# Run the container locally in remote proxy mode (connects to remote Agent Runtime):
make docker-run DOCKER_AGENT_RUNTIME_ID=$(AGENT_RUNTIME_ID)

This launches the application on http://localhost:8000, running exactly as it would on Cloud Run.

Step 3: Run Tests & Quality Gates

Before committing any changes to git, verify both the backend and frontend are healthy:

• Backend Linting & Types: Run ruff linting/formatting and ty static typing checks:

  make lint
  

• Frontend Linting & Compile: Run eslint checks and compile the production bundle to verify zero TypeScript errors:

  make test-ui
  

• Unit & Integration Tests: Execute backend pytest coverage checks:

  make test
  

Interactive Notebook Prototyping

An interactive notebook is available at adk_app_testing.ipynb for testing the agent in a sandbox environment. This allows:

• Local Testing: Instantiating the agent logic locally within the project virtual environment.
• Remote Testing (Agent Runtime): Interacting with the deployed Gemini Enterprise Agent Runtime.
• Remote Testing (Cloud Run): Triggering the deployed uvicorn server/SSE streaming interface.

For full usage instructions, refer to the Testing Guide.

Debug Logging

FinSavant is pre-configured with detailed debug logs to trace remote session creation, agent queries, and incoming event payloads.

To enable full debug logging in local development or deployed Cloud Run instances:

• Local Development: Set the environment variable in your local .env file:

  LOG_LEVEL=DEBUG
  

• Deployed Environments: Redeploy the Cloud Run BFF passing the LOG_LEVEL make variable:

  make deploy-cloud-run LOG_LEVEL=DEBUG
  

  This updates the container's environment variables and outputs logs to Google Cloud Logging at the DEBUG level.

CI/CD & Deployment Flow

FinSavant utilises a decoupled GitHub Actions pipeline to enforce a strict quality gate before releasing code to Production. The architecture splits the application into two deployed targets:

1. Agent Logic (Gemini Enterprise Agent Runtime): Managed serverless environment hosting the agent's Python code, callbacks, and tools.
2. BFF + UI (Cloud Run): A lightweight container hosting the static React assets and a FastAPI thin proxy layer.

GitHub Actions Pipelines

• Continuous Integration (Staging):
  • Trigger: Automatic on pushes or merges to the main branch. (Pull requests against branches only run linting, unit, and integration tests to ensure code health, but do not deploy anything to GCP).
  • Actions: The .github/workflows/staging.yaml workflow automatically packages and deploys the agent logic to the staging Agent Runtime (finops-admin-dev), extracts the resulting AGENT_RUNTIME_ID, builds the unified container image, and deploys it to the Staging Cloud Run BFF with the correct engine ID.
• Verification: Verify the staging environment to ensure all agent tools, BigQuery MCP connections, and React component renders function correctly.
• Manual Gate (Production):
  • Trigger: Manual trigger ("workflow dispatch") in GitHub Actions.
  • Actions: The .github/workflows/deploy-to-prod.yaml workflow deploys the agent to the production Agent Runtime (finops-admin-prd), extracts the production ID, and deploys the BFF container to Production Cloud Run.

For details on network variables, service accounts, and Terraform variable propagation, refer to the Deployment README.

Accessing the Environments

IAP is enabled. Access the deployments via their respective custom domain URLs:

• Staging / Dev Endpoint: https://smart-finops-dev.just2good.co.uk/
• Production Endpoint: https://smart-finops.just2good.co.uk/

IAM Permissions & Validation

For the agent and the executive dashboard to discover GCP resources, query active recommendations, and run cost audits, the querying developer's account (and the deployed application service account) must have the appropriate IAM roles and enabled APIs across all target projects and the organization.

Please refer to the IAM Permissions & Validation section in the Deployment README for:

• The Consolidated IAM Setup Script to apply Organization-level (Cloud Asset Viewer, Recommender Exporter, Recommender Viewer) and Project-level (Recommender Viewer, Cloud Asset Viewer) bindings in one block for users and service accounts.
• Required API activation checklist (cloudresourcemanager.googleapis.com, recommender.googleapis.com, geminicloudassist.googleapis.com, cloudaicompanion.googleapis.com) on standalone/scratch projects.
• Gemini Cloud Assist troubleshooting and manual roles configuration.
• The validation command to verify your user's permissions.

Technical Architecture

• Orchestration: Built with Google ADK for robust multi-agent orchestration, session context management, and telemetry.
• APIs: Google Cloud Assist API, Google Developer Knowledge API, and Cloud Asset Inventory.
• Data Layer: Direct semantic schema access to BigQuery via native ADK BigQueryToolset and cached SQL query execution.
• Infrastructure: GCS-backed remote state for consistent multi-environment management managed via Terraform.
• Frontend: React (TypeScript) built with Stitch for high information density, utilising Agent-to-UI (A2UI) to dynamically render rich components like tables and charts.
• Security Boundary & Row-Level Filtering: Identity-Aware Proxy (IAP) natively integrated with Cloud Run for enterprise-grade authentication. The FastAPI BFF extracts the user's identity from the x-goog-authenticated-user-email header, resolves project/org IAM permissions, and wraps all BigQuery queries in a subquery to enforce strict row-level security.
• Hybrid Execution: Supports two run modes:
  • Remote Execution Mode: The BFF acts as a stateless proxy to the remote agent running on the Google Agent Runtime.
  • Local Fallback Mode: If no remote runtime ID is configured, the BFF loads the agent locally inside the container, running the ADK engine using developer Application Default Credentials (ADC).
• Deployment: Unified Container architecture (bundling compiled React assets + FastAPI) hosted on Google Cloud Run.

For a detailed breakdown of authentication options (Vertex AI vs. GEMINI_API_KEY) and system cost drivers, refer to the Authentication & Cost Model Guide.

Useful Links & References

Dazbo's Portfolio & Publications

• Dazbo's Portfolio
• Using Google IAP with Cloud Run without a Load Balancer (Dazbo on Medium)
• FinSavant Video Demo (YouTube)

Gemini Enterprise Agent Platform & ADK

• Gemini Enterprise Agent Platform Overview
• Agent Runtime (ADK Hosting)
• ADK Agent Building Guide
• Agents CLI Documentation
• ADK BigQuery Tool Integration
• Agent Registry Overview
• GEAP Memory Bank
• Agent Gateway Documentation
• Model Armor Security Overview
• GEAP Observability & Telemetry
• Agent Evaluations

Google Cloud Services & APIs

• Cloud Run Overview
• Identity-Aware Proxy (IAP) Overview
• Google Cloud Assist
• Cloud Asset Inventory (CAI) API
• Developer Knowledge MCP Server

GCP Billing & FinOps

• Google Cloud FinOps Hub
• BigQuery Billing Exports Setup

License

This project is licensed under the MIT License - see the LICENSE file for details.