Smart Gcp Finops

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](#features)
• [Associated Articles](#associated-articles)
• [Target Audience](#target-audience)
• [Success Metrics](#success-metrics)
• [Project Structure](#project-structure)
• [Requirements](#requirements)
• [Quick Start](#quick-start)
• [Commands](#commands)
• [Local Development & Testing Flow](#local-development--testing-flow)
• [Run as Standalone Services (Hot-Reloading)](#run-as-standalone-services-hot-reloading)
• [Step 1: Initialise Dependencies](#step-1-initialise-dependencies)
• [Step 2: Run the Application](#step-2-run-the-application)
• [Run as a Single Docker Container](#run-as-a-single-docker-container)
• [Step 3: Run Tests & Quality Gates](#step-3-run-tests--quality-gates)
• [Interactive Notebook Prototyping](#interactive-notebook-prototyping)
• [CI/CD & Deployment Flow](#cicd--deployment-flow)
• [GitHub Actions Pipelines](#github-actions-pipelines)
• [IAM Permissions & Validation](#iam-permissions--validation)
• [Technical Architecture](#technical-architecture)
• [Useful Links & References](#useful-links--references)
• [License](#license)

Features

• BigQuery Billing Integration: Direct access to BigQuery billing exports for cross-project cost analysis.
• BigQuery ADK Integration: Native dataset and table schema awareness using ADK's native BigQueryToolset with local query caching.
• Natural Language Chat Interface: A React-based UI allowing users to query billing data and infrastructure state in plain English.
• FinOps Dashboard: A centralised view for cost trends, anomaly reports, and optimisation progress.
• Zombie Resource Detection & Audit: Proactively identifies cost waste such as unattached persistent disks using Cloud Asset Inventory. Correlates billing spikes with historical configuration changes.
• Multi-Project Analysis: Ability to scope analysis to specific projects, billing accounts, or the entire Google Cloud Organisation.
• AI-powered Forecasting: Predict future cloud consumption and budget requirements using historical data.
• Automated Anomaly Detection: Proactively identify unusual billing spikes and cost inefficiencies.
• Actionable Recommendations: Combine billing insights with architectural best practices for high-impact cost optimisation.

[](https://youtu.be/zs_IRUxIx4E)

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

• Cloud Platform Engineers: Managing infrastructure and resource lifecycle.
• FinOps Practitioners: Dedicated teams responsible for cloud financial governance.
• GCP Organisation Admins: Overseeing cost and compliance across a large-scale cloud footprint.

Success Metrics

• Spend Reduction %: Target reduction in unoptimised spend.
• Anomaly Detection Speed: Minimise MTTD (Mean Time to Detect) for billing outliers.
• Forecasting Accuracy: High precision in projected budget versus actual realisation.

Project Structure

smart-gcp-finops/
├── .env                  # Root environment vars (dev setup, unified container)
├── app/                  # Standalone Agent Runtime Package (ADK Agent)
│   ├── finops_agent/          # Core ADK agent python package
│   │   ├── 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 (FastAPI Web App)
│   ├── Dockerfile             # UI/BFF-only Dockerfile (TBD)
│   └── fast_api_app.py        # Serves UI, proxies queries, and manages SSE streams
├── deployment/           # Infrastructure & CI/CD (Terraform IaC)
│   └── terraform/             # Centralised IaC for Prod & Staging
├── docs/                 # System-wide architecture and design documentation
│   ├── images/                # Diagrams and architectural visual assets
│   ├── DESIGN.md              # Visual identity, components, and design tokens
│   ├── architecture-and-walkthrough.md # Solution blueprints, ADRs, and component data flows
│   └── testing.md             # Testing strategy and verification instructions
├── frontend/             # Single Page Application (React + Vite + Stitch)
│   ├── 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
├── .gemini/              # Gemini configuration (MCP settings)
├── .github/              # GitHub Actions workflows and CI/CD
├── Dockerfile            # Configuration for the unified development image
├── Makefile              # Centralised developer command pipeline
├── GEMINI.md             # Developer context & guidelines
├── pyproject.toml        # Root developer environment configuration
├── README.md             # Developer documentation homepage
└── TODO.md               # TODO list

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

| Command | Description | | -------------------- | ----------------------------------------------------------------- | | make install | Install dependencies using uv | | make playground | Launch local development environment (ADK Dev UI) | | make run-backend | Run the Backend BFF Server locally (runs agent locally unless AGENT_RUNTIME_ID is set) | | make run-frontend | Launch the Vite Dev Server for the React UI | | make lint | Run backend code quality checks (ruff, codespell, ty) | | make test-ui | Run frontend compiler and lint checks (TypeScript, ESLint) | | make test | Run unit and integration tests (pytest) | | make build | Shortcut to build the unified production container image locally | | make docker-build | Build the unified production container image (React + FastAPI) locally | | make docker-run | Run the built container locally (runs agent locally by default; set DOCKER_AGENT_RUNTIME_ID to proxy) | | make run | Shortcut for make docker-run to run the container locally | | make tf-plan | Initialise Terraform and plan infrastructure deployment | | make tf-apply | Initialise Terraform and apply deployment configuration | | make deploy-agent-runtime | Deploy backend agent code to Gemini Enterprise Agent Runtime | | make get-agent-runtime-id | Retrieve the deployed Agent Runtime ID (resource URN) | | make deploy-cloud-run | Deploy BFF container to Cloud Run using Cloud Build. Pass LOG_LEVEL=DEBUG to enable debugging |

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:

``bash make run-backend ``

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

``bash 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:

``bash make lint ``

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

``bash make test-ui ``

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

``bash make test ``

Interactive Notebook Prototyping

An interactive notebook is available at [adkapptesting.ipynb](notebooks/adkapptesting.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](docs/testing.md#interactive-testing-via-jupyter-notebook).

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:

``env LOG_LEVEL=DEBUG ``

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

``bash 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](.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](.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](deployment/README.md).

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 and projects, the querying developer's account (and the deployed application service account) must have the appropriate Cloud Asset Inventory permissions.

Please refer to the [IAM Permissions & Validation](deployment/README.md#iam-permissions--validation) section in the Deployment README for:

• The validation command to verify your user's permissions.
• gcloud commands to grant missing roles at the Organisation, Folder, or Project level.
• Helper bash scripts to bulk-bind permissions to all projects or standalone (orphaned) projects linked to your billing account.

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, a

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: derailed-dash
• Source: derailed-dash/smart-gcp-finops
• License: MIT
• Homepage: https://medium.com/google-cloud/finsavant-part-1-building-an-agentic-finops-platform-with-google-adk-a2ui-and-gemini-enterprise-248f59cea3a0

Install and usage instructions live in the source repository linked above.