FEC Campaign Finance AI Agent

Results are based on FEC public data. Always verify important findings with official FEC sources.

Inside This Agentic Solution

Live Agent Flow Ask a question to watch

💬Question

🛡️Input Guard

🧠Root Agent

Tools

🔍Tables

🛡️SQL Check

⚡BigQueryMCP

📋SchemaMCP

Sub-Agents

📊Charts

🌐Research

🔒Output Guard

✅Answer

You're looking at a live AI Agent — not a chatbot. A chatbot generates text from what it was trained on. An agent can reason, plan, and take action — like querying a real database, verifying facts on the web, or creating a chart.

This app is built using the Agentic AI pattern: an LLM brain surrounded by tools, knowledge, guardrails, and sub-agents that work together to deliver trustworthy answers. Here's how each piece works — with this app as the live example.

🤖 Agents in This Solution

Root Agent

FEC Campaign Finance Agent

The "boss" agent. Receives your question, decides which tools to use, writes SQL, and orchestrates the entire workflow. Built on Google Gemini 2.5 Flash via Vertex AI.

Sub-Agent

Visualization Agent

When data benefits from a chart, the root agent delegates to this sub-agent. It creates interactive Plotly charts — bar charts, pie charts, line graphs — directly from query results.

Sub-Agent

Research Verification Agent

Fact-checks answers using Google Search. Adds news context, historical comparisons, and flags discrepancies between data and public sources.

💡 Key Concept: In an agentic solution, you can have multiple specialized agents that collaborate — each with its own instructions and tools. The root agent decides when to delegate.

🛠️ Tools — How Agents Take Action

Unlike chatbots that only generate text, agents use tools to interact with the real world. Each tool is a function the agent can call. Here are the tools in this solution:

🔍

list_relevant_tables

Searches the semantic knowledge base to find which FEC tables match your question. Returns table names, column descriptions, join recipes, and glossary matches.

🛡️

execute_safe_query

A security gate. Before any SQL runs, this tool validates it — blocks dangerous operations (DELETE, DROP, etc.), enforces LIMIT, and ensures read-only access.

⚡

execute-query MCP

Runs validated SQL against Google BigQuery — 284 tables of FEC campaign finance data spanning 1980–2026.

📋

list-tables / describe-table MCP

Inspect available tables and their schemas directly from BigQuery — so the agent can discover new data on the fly.

📊

create_visualization

Generates interactive Plotly.js chart specifications from data — bar charts, pie charts, line graphs rendered right in your browser.

🌐

Google Search

The research agent searches the web to verify facts and add real-world context to data answers.

🔌 MCP — Model Context Protocol

Some tools above are labeled MCP. MCP is an open standard that lets an AI agent connect to external services through a consistent interface — like a USB port for AI.

MCP Server

BigQuery MCP Server

This solution runs a BigQuery MCP server as a subprocess. It exposes execute-query, list-tables, and describe-table as standardized tools. The agent doesn't need to know BigQuery internals — it just calls MCP tools, and the server handles authentication, execution, and response formatting.

💡 Why MCP matters: Swap the BigQuery server for a Postgres or Snowflake MCP server, and the agent works with a different database — no agent code changes needed.

✅ Evals — Testing That the Agent Works

How do you know an AI agent gives correct answers? You use evaluations — predefined test cases that verify the agent's behavior.

Eval Suite

ADK Evaluation Framework

This solution has an eval suite (evals/fec_agent_evals.json) that tests: Does the agent find the right tables? Does it write correct SQL? Does it handle edge cases? Does it stay on-topic? Run with make eval.

Unit Tests

79+ Automated Tests

Traditional tests verify each component independently — SQL validation, guardrails, semantic search, callbacks — without calling any AI model or cloud service.

💡 Key Concept: Evals are critical for production agents. Unlike regular software where tests are pass/fail, agent evals assess quality of reasoning, tool selection, and answer accuracy.

📚 Business Logic — The Agent's Knowledge

An agent is only as good as the knowledge you give it. This solution uses two key files to encode domain expertise:

YAML

Semantic Layer (fec_metadata.yaml)

A curated knowledge base with 16 table definitions, column descriptions, 12 table relationships, 8 pre-built join recipes, a glossary of political terms, and query patterns. This is what makes the agent understand FEC data without hallucinating table names.

Markdown

Agent Instructions (agent_instruction.md)

The agent's "playbook" — written in plain English. Tells the agent: how to join tables, which year to default to, how to handle party codes (DEM vs DFL), when to create charts, and step-by-step examples for common questions.

💡 This is the secret sauce: The YAML + Markdown approach means domain experts can update the agent's knowledge without writing code. Change the YAML, and the agent immediately knows about new tables or business rules.

⚙️ Configuration & Deployment Files

Two key documentation files keep the solution maintainable:

Cloud

CLAUDE.md

A comprehensive technical guide for AI coding assistants — architecture, commands, patterns, gotchas, and conventions. Ensures any developer (human or AI) follows the same practices.

GitHub

copilot-instructions.md

GitHub Copilot-specific instructions that live in .github/. Encodes project conventions — import paths, testing commands, deployment rules — so AI-assisted development stays consistent.

🚀 Why Agentic vs. Traditional Chatbot?

🤖 Chatbot

Generates text from training data
Can't access live databases
One-shot responses
May hallucinate data
No tool use or planning

🚀 AI Agent

Plans multi-step workflows
Queries real data in real-time
Uses tools and sub-agents
Verifiable, traceable results
Guardrails enforce safety

🏗️ Solution Stack

Google ADK Gemini 2.5 Flash Vertex AI BigQuery MCP Protocol FastAPI Python 3.12 Cloud Run Docker SSE Streaming Plotly.js