feat: Add BigQuery Agent Analytics Dashboard

Add a comprehensive monitoring dashboard for ADK agent behavior analytics
stored in BigQuery. The dashboard provides real-time insights into:

- Agent sessions and invocations
- LLM performance metrics (latency, tokens, TTFT)
- Tool usage and success rates
- Error tracking and analysis
- Latency analysis with percentiles (P50, P90, P95, P99)

Components:
- FastAPI backend with BigQuery queries
- Embedded HTML/JS frontend with Chart.js visualizations
- Data simulation script for testing
- Docker and Cloud Run deployment support

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: caohy1988

contributing/samples/bigquery_agent_analytics_demo/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""BigQuery agent analytics demo agent package."""
+
+from . import agent

contributing/samples/bigquery_agent_analytics_demo/agent.py

@@ -0,0 +1,131 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+"""Minimal agent wired to the BigQuery Agent Analytics plugin."""
+
+import os
+from typing import Dict
+from typing import List
+
+from google.adk import Agent
+from google.adk.apps import App
+from google.adk.models.google_llm import Gemini
+from google.adk.plugins.bigquery_agent_analytics_plugin import (
+    BigQueryAgentAnalyticsPlugin,
+    BigQueryLoggerConfig,
+)
+from google.adk.tools.function_tool import FunctionTool
+from google.adk.tools.google_search_agent_tool import (
+    GoogleSearchAgentTool,
+    create_google_search_agent,
+)
+
+PROJECT_ID = os.getenv("BQ_AGENT_ANALYTICS_PROJECT")
+DATASET_ID = os.getenv("BQ_AGENT_ANALYTICS_DATASET")
+TABLE_ID = os.getenv("BQ_AGENT_ANALYTICS_TABLE", "agent_events")
+
+# Default Vertex AI settings if env vars are not provided.
+os.environ.setdefault("VERTEXAI_PROJECT", "test-project-0728-467323")
+os.environ.setdefault("VERTEXAI_LOCATION", "us-central1")
+# google.genai expects these env vars to auto-switch to Vertex AI with ADC.
+os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "true")
+os.environ.setdefault("GOOGLE_CLOUD_PROJECT", "test-project-0728-467323")
+os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "us-central1")
+
+if not PROJECT_ID or not DATASET_ID:
+  raise ValueError(
+      "Set BQ_AGENT_ANALYTICS_PROJECT and BQ_AGENT_ANALYTICS_DATASET before "
+      "running this agent to enable BigQuery analytics logging."
+  )
+
+analytics_plugin = BigQueryAgentAnalyticsPlugin(
+    project_id=PROJECT_ID,
+    dataset_id=DATASET_ID,
+    table_id=TABLE_ID,
+    config=BigQueryLoggerConfig(
+        event_allowlist=[
+            "USER_MESSAGE_RECEIVED",
+            "LLM_REQUEST",
+            "LLM_RESPONSE",
+            "TOOL_STARTING",
+            "TOOL_COMPLETED",
+            "MODEL_RESPONSE",
+            "TOOL_CALL",
+            "TOOL_RESULT",
+            "ERROR",
+        ],
+        max_content_length=400,
+    ),
+)
+
+def pick_city(top_n: int = 3) -> List[str]:
+  """Return a short list of recommended cities."""
+  cities = ["Tokyo", "Paris", "New York", "Sydney", "Singapore", "Toronto"]
+  return cities[:top_n]
+
+def city_highlights(city: str) -> Dict[str, str]:
+  """Return quick highlights for a city."""
+  highlights = {
+      "Tokyo": "Sushi, Akihabara tech, efficient transit.",
+      "Paris": "Museums, pastries, walkable boulevards.",
+      "New York": "Broadway, diverse food, skyline views.",
+      "Sydney": "Harbour, beaches, outdoor cafes.",
+      "Singapore": "Hawker food, gardens, clean and safe.",
+      "Toronto": "CN Tower, neighbourhood food, waterfront.",
+  }
+  return {"city": city, "highlights": highlights.get(city, "Explore freely.")}
+
+def estimate_trip_budget(city: str, days: int, budget_per_day: float) -> Dict[str, str]:
+  """Rough budget calculator."""
+  total = days * budget_per_day
+  return {
+      "city": city,
+      "days": str(days),
+      "budget_per_day": f"${budget_per_day:,.0f}",
+      "estimated_total": f"${total:,.0f}",
+      "note": "Assumes lodging+food+local transit; adjust for flights.",
+  }
+
+city_tool = FunctionTool(pick_city)
+city_highlights_tool = FunctionTool(city_highlights)
+budget_tool = FunctionTool(estimate_trip_budget)
+
+gemini = Gemini(model="gemini-2.5-flash")
+search_agent = create_google_search_agent(model=gemini)
+google_search_tool = GoogleSearchAgentTool(agent=search_agent)
+
+root_agent = Agent(
+    name="bq_agent_analytics_demo",
+    model=gemini,
+    instruction=(
+        "You are a concise assistant. Prefer to use tools when asked for trip "
+        "ideas, highlights, or cost estimates. Keep answers short and "
+        "actionable."
+    ),
+    description="A minimal agent that logs events to BigQuery.",
+    tools=[
+        city_tool,
+        city_highlights_tool,
+        budget_tool,
+        google_search_tool,
+    ],
+)
+
+app = App(
+    name="bq_agent_analytics_demo",
+    root_agent=root_agent,
+    plugins=[analytics_plugin],
+)

contributing/samples/bigquery_agent_analytics_demo/dashboard/Dockerfile

@@ -0,0 +1,45 @@
+# Agent Analytics Dashboard Docker Image
+#
+# Build:
+#   docker build -t agent-analytics-dashboard .
+#
+# Run:
+#   docker run -p 8080:8080 \
+#     -e BQ_AGENT_ANALYTICS_PROJECT=your-project \
+#     -e BQ_AGENT_ANALYTICS_DATASET=your-dataset \
+#     -v ~/.config/gcloud:/root/.config/gcloud \
+#     agent-analytics-dashboard
+
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY app.py .
+COPY __init__.py .
+
+# Create non-root user for security
+RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
+USER appuser
+
+# Expose port
+EXPOSE 8080
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8080/api/health || exit 1
+
+# Run the application
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"]