Catforce Data Agents Demo

This repository demonstrates how to build GenAI agents using the Agent Development Kit (ADK) and Model Context Protocol (MCP). It simulates a "Catforce" environment—a mock CRM for cats—where agents can assist with support cases and general cat queries.

It consists of two main components:

• Catforce Agent (/agents): An ADK-based agent that intelligently routes user requests. It can query internal enterprise data in BigQuery (e.g., support cases from hungry cats) and leverage external tools for general knowledge.
• MCP Server (/mcp): A FastMCP server that provides specialized tools to the agent, such as calculating cat age in human years, fetching cat facts, and placing mock orders for supplies.

Prerequisites

These instructions assume you are using a command-line interface (CLI), such as Google Cloud Shell or a local terminal with the gcloud CLI installed and configured.

• Google Cloud Project with billing enabled.
• gcloud CLI installed and configured.
• Python 3.11 or higher.

Setup Environment Variables

Set your Google Cloud Project ID as an environment variable to easily use it in subsequent commands:

export PROJECT_ID=$(gcloud config get-value project)
# Or manually: export PROJECT_ID=your-project-id

1. Set up MCP Server

1. Navigate to the mcp directory:

   cd mcp

2. Create a service account for the MCP server:

   gcloud iam service-accounts create mcp-server-sa --display-name="MCP Server Service Account"

3. Deploy the MCP server to Cloud Run:

   gcloud run deploy cats-mcp-server \
     --service-account=mcp-server-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --no-allow-unauthenticated \
     --region=us-west1 \
     --source=.

   • When prompted, select "Y" to allow creating a new Artifact Registry Docker repository.

Making changes to the MCP server

To update the MCP server:

1. Modify /mcp/server.py.
2. Re-deploy using the same command as above from the mcp directory.

2. Set up BigQuery Tables

Run the following command to create the necessary BigQuery tables:

curl https://gist.githubusercontent.com/Lsubatin/edd240158ce4a9d786d2b66cfb1d0648/raw/d73b50998db3b8e72366e8b7aa40912bae6bb8f4/create_tables.sql | sed "s/<<your_project>>/${PROJECT_ID}/g" | bq query --nouse_legacy_sql

3. Set up and run Agent

1. Navigate to the agent directory:

   cd ../agents/catforce-agent/

2. Set the MCP_SERVER_URL environment variable by fetching it from Cloud Run:

   export MCP_SERVER_URL=$(gcloud run services describe cats-mcp-server --region=us-west1 --format='value(status.url)')/mcp

3. Create a .env file:

   cat <<EOF > .env
   GOOGLE_GENAI_USE_VERTEXAI=1
   GOOGLE_CLOUD_PROJECT=${PROJECT_ID}
   GOOGLE_CLOUD_LOCATION=us-central1
   MODEL="gemini-2.5-flash"
   MCP_SERVER_URL=${MCP_SERVER_URL}
   EOF

4. Run the agent:

   cd ..
   uv run adk web

5. Open the provided local URL (e.g., http://127.0.0.1:8000) in your browser.

6. Try asking questions like:

   • If I'm 3 in cat years, how many human years is that? (uses MCP)
   • Give me a fun cat fact (uses MCP)
   • How long does a domestic shorthair cat live? (uses Wikipedia)
   • Are there any cats in the cases table who are complaining about food? What's the ID? (calls BigQuery)