יצירת סוכן לניתוח נתונים של Google Trends באמצעות BigQuery MCP

1. סקירה כללית

בשיעור Codelab הזה נסביר איך ליצור סוכן לניתוח נתונים של Google Trends באמצעות Google ADK. הסוכן הזה משתמש בשרת BigQuery MCP כדי לגלות באופן דינמי כלים שמריצים שאילתות במערך הנתונים הציבורי של Google Trends (bigquery-public-data.google_trends) ולהפעיל אותם.

מה תלמדו

• איך מגדירים פרויקט לפיתוח ADK.
• איך מפעילים ומשתמשים בשרתי MCP מנוהלים ל-BigQuery.
• איך ליצור סוכן שמשתמש בכלי MCP.
• איך מריצים את הסוכן באופן מקומי לצורך בדיקה.
• איך פורסים את הסוכן ב-Google Cloud Run.

הדרישות

• פרויקט ב-Google Cloud שהחיוב בו מופעל
• דפדפן אינטרנט כמו Chrome
• ‫Python 3.11 ואילך

שיעור ה-Codelab הזה מיועד למפתחים ברמת ביניים שיש להם היכרות מסוימת עם Python ו-Google Cloud.

השלמת ה-codelab הזה תיקח בערך 15-20 דקות.

העלות של המשאבים שנוצרו ב-codelab הזה צריכה להיות פחות מ-5$.

2. הגדרת הסביבה

יצירת פרויקט ב-Google Cloud

1. במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.
2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

מומלץ להשתמש ב-Google Cloud Shell ב-Codelab הזה. הוא מספק סביבת טרמינל עם Python ו-Google Cloud CLI שכבר מותקנים.

כדי להפעיל את Cloud Shell, לוחצים על הלחצן Activate Cloud Shell בחלק העליון של מסוף Google Cloud.

הגדרה של משתני סביבה

מגדירים את משתני הסביבה הבאים.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

הערה: ההגדרה GOOGLE_GENAI_USE_VERTEXAI=1 מכוונת את ה-ADK להשתמש ב-Vertex AI, תוך הסתמכות על Cloud IAM לאימות במקום על GEMINI_API_KEY.

אימות והגדרה של gcloud

נכנסים לחשבון Google, מגדירים את הפרויקט הפעיל ומגדירים את Application Default Credentials.

אם אתם משתמשים ב-Cloud Shell, אתם יכולים לדלג על השלב הזה.

gcloud auth login
gcloud auth application-default login

הערה: gcloud auth login מאמתת את הפקודות של gcloud CLI, ואילו gcloud auth application-default login מאמתת קוד אפליקציה מקומי.

מגדירים את הפרויקט בענן של Google:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

הפעלת ממשקי API נדרשים

מפעילים את ממשקי ה-API הנדרשים של Google Cloud עבור Cloud Run,‏ Artifact Registry,‏ BigQuery ו-Vertex AI.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       bigquery.googleapis.com \
                       aiplatform.googleapis.com

הפעלת MCP ל-BigQuery

צריך להפעיל במפורש את שרתי ה-MCP המנוהלים בפרויקט.

gcloud beta services mcp enable bigquery.googleapis.com

יצירת תיקיית פרויקט

מתחילים ביצירת תיקיית שורש לסוכן ותיקייה פנימית להטמעה של הסוכן.

mkdir google-trends-agent
cd google-trends-agent
mkdir google_trends

3. יצירת קוד הסוכן

יוצרים קובץ ריק בשם google_trends/__init__.py:

touch google_trends/__init__.py

לאחר מכן, יוצרים קובץ בשם google_trends/agent.py ומדביקים את הקוד הבא:

import os
import textwrap
import warnings
from datetime import date

import google.auth
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.auth.transport.requests import Request

# Suppress experimental ADK credential warnings
warnings.filterwarnings("ignore")

def get_agent_instruction(project_id: str) -> str:
    """Generates a clear and formatted prompt for the data analyst."""
    instruction = f"""
    # ROLE
    You are a Google Search Trends Analyst. Your mission is to provide clear answers using SQL data.

    # DATA CONSTRAINTS
    - BigQuery tool `execute_sql` requires explicit billing project mapping. Use: '{project_id}'.
    - Target dataset strictly: `bigquery-public-data.google_trends`

    # SCHEMA DISCOVERY (CRITICAL)
    1. DO NOT call `get_table_info` or `list_table_ids` (Triggers Permission Errors).
    2. Run `SELECT * FROM table LIMIT 0` via `execute_sql` for field definition mapping.

    # OUTPUT PRESENTATION
    - Render purely as a cleanly aligned Markdown table.
    - Use clear and descriptive headers for each column.
    - Remove conversational preambles. Output only the results.
    """
    return textwrap.dedent(instruction).strip()

def get_auth_headers() -> dict[str, str]:
    """Fetch auth headers for the project using Google Cloud Platform scopes."""
    credentials, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform"]
    )
    request = Request()
    credentials.refresh(request)

    return {"Authorization": f"Bearer {credentials.token}"}

def get_todays_date() -> str:
    """Returns today's date in YYYY-MM-DD format."""
    return date.today().isoformat()

# --- Application Initialization ---
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set")

mcp_headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
} | get_auth_headers()

# Configure BigQuery Tools via MCP
bq_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers=mcp_headers,
    )
)

# Initialize the LLM Agent
root_agent = LlmAgent(
    name="google_trends",
    model="gemini-3-flash-preview",
    tools=[get_todays_date, bq_tools],
    instruction=get_agent_instruction(project_id),
)

# Create the ADK App
app = App(name=root_agent.name, root_agent=root_agent)

4. הפעלת הסוכן

בשלב הזה, תגדירו סביבה וירטואלית מקומית של Python, תתקינו תלויות ותריצו את הסוכן כדי לאמת את ההתנהגות שלו במחשב (או ב-Google Cloud Shell).

• עוברים לתיקיית השורש של האפליקציה (google-trends-agent).
• יוצרים סביבה וירטואלית:

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

• מתקינים את חבילות Python הנדרשות:

pip install google-auth google-adk

נשתמש ב-ADK Web כדי לבדוק את הסוכן החדש שלנו.

לפיתוח ובדיקה מקומיים, מריצים את הפקודה הבאה:

adk web

כדי לפתח ולבדוק ב-Google Cloud Shell, מריצים את הפקודה הבאה:

adk web --allow_origins="*"

הפעולה הזו תפעיל את שרת האינטרנט של ADK. אפשר ליצור אינטראקציה עם הנציג באמצעות ממשק האינטרנט המקומי (בדרך כלל בכתובת http://localhost:8000).

הערה: אפשר גם להשתמש בפקודה הפשוטה יותר adk run google_trends כדי לבדוק את הסוכן.

הנה כמה הנחיות שאפשר לתת לסוכן:

• תראה לי את המגמות המובילות בארה"ב
• מהם מגמות החיפוש הפופולריות ביותר בצרפת החודש?
• מה היו 3 המגמות המובילות בקליפורניה בשבוע שעבר?
• מהן הטבלאות ב-BigQuery שיש לך גישה אליהן?
• תספר לי כל מה שאתה יודע על הטבלה top_trends

5. פריסה ב-Cloud Run

כדי לפרוס את הסוכן באופן מאובטח ב-Google Cloud Run, צריך לבצע את השלבים הבאים.

מתן הרשאות

ל-Cloud Run נדרשת הרשאה לגשת ל-Vertex AI ולהשתמש בכלים של BigQuery MCP.

# Get your project number automatically
PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format='value(projectNumber)')

# Vertex AI Access: To talk to the Gemini model
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/aiplatform.user"

# MCP & BigQuery: To execute tools and run SQL jobs
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.dataViewer"

יצירת קובץ Dockerfile

בשורש של הפרויקט (google-trends-agent), יוצרים קובץ בשם Dockerfile ומדביקים בו את התוכן הבא:

FROM python:3.11-slim
WORKDIR /app

# Create a non-root user
RUN adduser --disabled-password --gecos "" myuser
USER myuser
ENV PATH="/home/myuser/.local/bin:$PATH"

# Copy the agent folder into the container
COPY --chown=myuser:myuser google_trends/ /app/agents/google_trends/

# Install the python packages
RUN pip install google-auth google-adk

# Set environment variables
ENV GOOGLE_GENAI_USE_VERTEXAI=1

# Expose port
EXPOSE 8080

# Run ADK web server
CMD ["adk", "web", "--port=8080", "--host=0.0.0.0", "/app/agents"]

פריסת הסוכן

מריצים את הפקודה הבאה מהספרייה הבסיסית. הפעולה הזו תכניס את הסוכן לקונטיינר ותפרוס אותו ב-Cloud Run.

עוקבים אחרי פלט הפקודה. אחרי שהפריסה מסתיימת, מוצגת כתובת URL של השירות. תשתמשו בכתובת ה-URL הזו כדי לתקשר עם הנציג.

gcloud run deploy google-trends-agent \
  --source . \
  --region us-west1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}"

אימות מהיר

בסיום הפריסה, במסוף יוצג Service URL. פותחים את כתובת ה-URL הזו בדפדפן. יוצג אותו ממשק משתמש אינטראקטיבי שראיתם באופן מקומי, אבל עכשיו הוא פועל בענן.

אפשר גם לעקוב אחרי היומנים כדי לוודא שהכול פועל בצורה חלקה:

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=google-trends-agent" --limit 10

6. הסרת המשאבים

כדי להימנע מחיובים שוטפים, מוחקים את המשאבים שנוצרו במהלך ה-codelab הזה.

מוחקים את שירות Cloud Run:

gcloud run services delete google-trends-agent --region us-west1

אם יצרתם פרויקט במיוחד בשביל ה-Codelab הזה, אתם יכולים למחוק את הפרויקט כולו:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

אפשר גם למחוק את כל הקבצים שקשורים ל-codelab הזה:

deactivate
cd ..
rm -rf google-trends-agent

7. מזל טוב

מעולה! יצרתם ופרסתם בהצלחה סוכן לניתוח נתונים של Google Trends.

מה למדתם

• איך משתמשים ב-MCP כדי להרחיב את היכולות של הסוכן באופן דינמי
• איך יוצרים סוכני LLM ומפעילים אותם באמצעות Google ADK
• איך פורסים ומשנים את קנה המידה של סוכנים ב-Cloud Run

השלבים הבאים

• ניסיון לשנות את הסוכן כדי להריץ שאילתות במערכי נתונים שונים ב-BigQuery
• הוספת עוד כלים של MCP כדי להרחיב את היכולות של הסוכן

מסמכי עזר

• מסמכי תיעוד של ADK
• מדריך כלי ה-MCP
• BigQuery MCP
• מאמרי העזרה של Cloud Run