Inspiration

Every cloud console shows you that your bill went up. None of them tell you why.

To find the answer you have to open billing exports from three providers. They all use a different format. It takes hours in a spreadsheet, and you usually do it in the morning after the bill arrives.

Some tools do try to answer. But they give you a confident story from an LLM with nothing behind it. For a cost problem that is worse than useless. A wrong root cause sends an engineer to go and fix something that was never broken.

I wanted the opposite. An agent that has to show its proof.

What it does

You give CloudCause a billing period. It answers one question. Why did spending go up on AWS, Azure, or Google Cloud? It shows the evidence for the cause, and what a human should think about doing next.

The demo uses one month of fake billing data. I planted three problems in it, and I did not tell the system what they were. It found all three in about a minute.

  • GCP, $161.60, confidence 0.87. An exposed API key. Cloud Translation traffic started coming from new locations.
  • AWS, $126.00, confidence 0.65. A route change sent S3 traffic through a NAT Gateway. Data processing went up 909%.
  • Azure, $103.20, confidence 0.83. An orders-processor Function got stuck in a retry loop after a deploy.

Together that is $430.26, which is 69.5% above the baseline. 91% of the increase is explained. Every finding links to its evidence and to a billing rule with a version number. You can export the whole report as a PDF.

There are two rules the system never breaks.

Python does all the math. The agents think about causes. They never calculate money. An LLM that cannot do the sums cannot get them wrong.

It can only read. No tool in this system can delete, stop, resize, or change a cloud resource. The gateway /health returns read_only: true. Every worker /capabilities returns mutating_tools: []. Every suggestion is marked requires_human_approval: true.

How I built it, and why it is a Taskmaster

You press Investigate once. After that, nobody steers it.

First, plain Python measures the change and finds what matters. Then a Google ADK orchestrator gives one job to each cloud. Each cloud has its own specialist agent, and each agent is built on a different framework:

  • GCP: Google ADK (LlmAgent, FunctionTool, MCPToolset) with Gemini 3.5 Flash Lite
  • AWS: AWS Strands
  • Azure: Microsoft Agent Framework

I split the work by provider in fixed code, not with a model. The money should never depend on what a model thinks. But everything after that split is the agent's own choice. The orchestrator writes the questions. Then each agent picks its own path through 13 read-only get_* tools over MCP, plus some native tools. How many calls it makes, in what order, and when to stop is up to it. I did not script those steps.

Then every finding gets checked. If the evidence does not support it, it is thrown away before it reaches the report. Anything left unexplained is published as a leftover number instead of being hidden.

Under all of that: FOCUS 1.4 to normalise three different schemas, 51 billing rules with version numbers and official source links, FastAPI and SSE for live progress, a Next.js 16 frontend, and ReportLab for the PDF.

It runs on Google Cloud from Terraform, using only three services: Cloud Run for the frontend and gateway, Artifact Registry, and Cloud Build. It scales to zero when nobody uses it.

Challenges I ran into

Three frameworks, one budget. I wanted one rate limiter and one call budget for all three agents. Only ADK gives you per-call hooks (before_model_callback, after_model_callback, on_model_error_callback). Strands and Microsoft Agent Framework do not. So I had to wrap the HTTP layer underneath them to get the same behaviour.

A bug I only found after deploying. The three agents run at the same time and share one call budget. I had sized that budget for a single provider. So the first agent to start used all of it, and the other two dropped back to plain code. On the live service the AWS agent finished properly, the ADK agent raised AgentCallLimitExceeded (12/12), and the MAF agent returned nothing. The whole report quietly turned into agent_mode=stub. The fix was to size the budget for three agents running together, not for one.

Keeping the LLM away from the numbers. This sounds easy. It is not. It changes how you design every single tool, because a tool that returns raw rows invites the model to start adding them up.

Accomplishments that I am proud of

  • 51 billing rules, each with a version, an official source link, and a review date. A weekly job compares the provider docs against a saved copy and opens an issue when something changes.
  • 13 test scenarios that run on every push. No API keys, no network, no cost.
  • When a live agent fails, the report says so in its warnings. It does not pretend that everything worked.
  • 12 ADRs that record why I made each decision, including why I limited myself to three GCP services.

What I learned

Guardrails matter more than prompts. Almost all the work that makes this trustworthy sits around the model, not inside it. Checking the evidence. The read-only tool list. Treating resource names as untrusted text, so a resource called "ignore previous instructions" cannot do anything. The shared call budget.

What's next for CloudCause

Live cloud connectors are the real missing piece. providers/live.py is a placeholder that raises a clear error on purpose. Right now CloudCause works on fake data, saved scenarios, and real billing exports that you upload yourself (AWS CUR 2.0, Azure Cost Management, GCP billing export). The analysis is exactly the same either way. Only the way the data comes in is different. Connecting the three cost APIs is next, then saved history, then keeping each tenant's data apart.

Requirements checklist

  • Gemini 3.5 or newer: gemini-3.5-flash-lite, through the Gemini API.
  • Google agent framework: Google ADK, for the orchestrator and the GCP specialist.
  • Google Cloud infrastructure: Cloud Run, Artifact Registry, and Cloud Build.

Built With

  • artifact-registry
  • aws-strands
  • cloud-build
  • fastapi
  • gemini
  • google-adk
  • google-cloud-run
  • mcp
  • microsoft-agent-framework
  • nextjs
  • python
  • tailwind
  • terraform
  • typescript
Share this project:

Updates

Submission history