‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

פיתוח ופריסה של סוכני AI באמצעות Gemini ושרת MCP של BigQuery ב-Cloud Run

1. מבוא

מה תלמדו

איך ליצור סוכן AI באמצעות הערכה לפיתוח סוכנים (ADK) עם Gemini ב-Agent Platform.
איך מעניקים לסוכני AI גישה לנתונים מובְנים ב-BigQuery באמצעות שרת BigQuery MCP.

‫Cloud Run היא פלטפורמת מחשוב מנוהלת ללא שרת, שמאפשרת להריץ אפליקציות ושירותים בקונטיינרים בלי לנהל את התשתית הבסיסית.

‫Agent Development Kit‏ (ADK) היא מסגרת קוד פתוח לפיתוח סוכנים, שמאפשרת ליצור, לנפות באגים ולפרוס סוכני AI מהימנים בהיקף ארגוני.

‫BigQuery הוא מחסן נתונים (data warehouse) ארגוני מנוהל ללא שרת, שמאפשר לכם לאחסן, לשלוח שאילתות ולנתח מערכי נתונים עצומים.

Model Context Protocol‏ (MCP) הוא תקן שקובע איך מודלים גדולים של שפה (LLM) ואפליקציות או סוכני AI מתחברים למקורות נתונים חיצוניים. שרתי MCP מאפשרים להשתמש בכלים, במשאבים ובהנחיות שלהם כדי לבצע פעולות ולקבל נתונים מעודכנים משירות לקצה העורפי שלהם. ‫BigQuery MCP Server מספק לסוכני ה-AI שלכם דרך ישירה ומאובטחת לניתוח נתונים ב-BigQuery. שרת ה-MCP המנוהל במלואו מסיר את עלויות התקורה של הניהול, ומאפשר לכם להתמקד בפיתוח סוכנים חכמים.

2. הגדרה ודרישות

מתחילים בהגדרת פרויקט ברירת מחדל ואזור Cloud Run:

# set the project
gcloud config set project YOUR_PROJECT_ID

מחליפים את YOUR_PROJECT_ID במזהה הפרויקט ב-Google Cloud.

# set Cloud Run region
gcloud config set run/region CLOUD-RUN-REGION

מחליפים את CLOUD-RUN-REGION באחד מהאזורים שנתמכים על ידי Cloud Run.

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

# Cloud Project Id and Cloud Run region
export GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT:-$(gcloud config get-value project -q)}"
export GOOGLE_CLOUD_REGION="${GOOGLE_CLOUD_REGION:-$(CR_REGION=$(gcloud config get-value run/region -q 2>/dev/null); echo "${CR_REGION:-us-central1}")}"
# Gemini API in Agent Platform
export GOOGLE_GENAI_USE_ENTERPRISE="True" # Use Agent Platform
export GOOGLE_CLOUD_LOCATION="global" # Use global Gemini API endpoint

מפעילים את ממשקי ה-API שנדרשים ל-Codelab הזה. יכול להיות שיעברו 2-3 דקות עד שהשינויים ב-API ייכנסו לתוקף.

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. יצירת סוכן נתונים באמצעות ערכה לפיתוח סוכנים (ADK)

כתיבת קוד לסוכן

בטרמינל של Cloud Shell או בטרמינל המקומי, יוצרים ספריית בסיס לאפליקציה מבוססת-הסוכן:

mkdir data_agent

פותחים את Cloud Shell Editor או כלי אחר לעריכת טקסט, ויוצרים את הקובץ agent.py בספרייה data_agent:

data_agent/
    agent.py

agent.py

import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

import google.auth
from google.auth.transport.requests import Request

# Fetch Application Default Credentials (ADC)
# to use as agent's own identity for accessing BigQuery MCP Server
_application_default_credentials, project_id = google.auth.default()
_request = Request()
_application_default_credentials.refresh(_request)

# Retrieve Google Cloud project to use.
project_id = os.getenv("GOOGLE_CLOUD_PROJECT", project_id)
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set.")

# Builds authentication headers for MCP Server requests,
# and refreshes credentials if needed.
def _adc_auth_header_provider(context = None) -> dict[str, str]:
    if not _application_default_credentials.valid:
        _application_default_credentials.refresh(_request)

    return {
        "Authorization": f"Bearer {_application_default_credentials.token}",
        "x-goog-user-project": project_id
    }

# Initialize the MCP Toolset with the connection parameters
bigquery_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        tool_filter=[
            'get_dataset_info',
            'list_table_ids',
            'get_table_info',
            # Using readonly is a security measure to prevent accidental data modification.
            'execute_sql_readonly',
        ]
    ),
    header_provider=_adc_auth_header_provider # Auth header provider function
)

# Configure the agent

system_instruction = f"""
You are a helpful assistant that can answer questions about data in BigQuery.
To answer the user's question, use data you have access to by using tools `list_table_ids` and `get_table_info`.
Your data is in `bigquery-public-data.new_york_citibike` dataset (Citi Bike trips and stations in the NYC area.)

Plan of action:
0. ALWAYS start by analyzing dataset.
1. Analyze your data, investigate schema and dimensions by querying distrinct values of columns using `execute_sql_readonly`.
   Output information about tables, columns, their data types and sets of values (for dimensions).
   Note which columns can be joined or used in aggregations/filters, and what type conversion may be needed for joining or aggregating.
   DO NOT MAKE ASSUMPTIONS ABOUT DATA (structure, type, values, relationships) BASED ON YOUR PRIOR KNOWLEDGE. ALWAYS VERIFY YOUR ASSUMPTIONS.
2. Understand and interpret the user's question.
3. Formulate a plan to answer the user's question.
4. Write a SQL query to retrieve relevant data in necessary form.
   This is where you must pay extra attention to column types and dimensions' sets of values.
5. Retrieve data by generating BigQuery SQL and using `execute_sql_readonly`.
   Always use Dry Run to verify SQL correctness.
   Use `{project_id}` to run BigQuery queries (`project_id` parameter of `execute_sql_readonly`).

Do not use LaTeX in your responses. When giving a final answer, use Markdown.
"""

root_agent = LlmAgent(
    model="gemini-3.6-flash",
    name="data_agent",
    instruction=system_instruction,
    description="A helpful assistant that can answer questions using NYC Citibike data.",
    tools=[bigquery_toolset]
)

בנוסף, כדי לפרוס את ADK נדרשים __init__.py ו-requirements.txt:

ל-__init__.py צריך להיות ייבוא לסוכן.
requirements.txt רשימת יחסי תלות של Python: google-adk עבור ערכה לפיתוח סוכנים (ADK) ו-mcp עבור לקוח Model Context Protocol‏.

הפקודות האלה עוזרות לכם ליצור את __init__.py ואת requirements.txt:

echo "from . import agent" > data_agent/__init__.py
echo -e "google-adk==2.4.*\nmcp==1.29.*" > data_agent/requirements.txt

מבנה התיקיות הסופי צריך להיראות כך:

data_agent/
    __init__.py
    agent.py
    requirements.txt

איך מנסים את הסוכן באופן מקומי

הערכה לפיתוח סוכנים כוללת את כלי ה-CLI‏ adk – ממשק טרמינל אינטראקטיבי לבדיקת הסוכנים. האפשרות הזו שימושית לבדיקות מהירות, לאינטראקציות מתוסרטות ולצינורות עיבוד נתונים של CI/CD. אחת מהתכונות ש-ADK מספק היא adk web – ממשק אינטרנט של ADK – דרך פשוטה לפתח ולנפות באגים בסוכנים באופן אינטראקטיבי. ‫ADK Web לא מיועד לשימוש בפריסות ייצור, אבל הוא מאפשר לנסות את הסוכן בקלות רבה.

הפקודה הזו מפעילה את adk web שמתחיל שרת אינטרנט מקומי ביציאה 8080.

uv tool run --with "mcp==1.29.*" --from "google-adk[mcp]==2.4.*" adk web --allow_origins="*" --port 8080 .

אחרי שהשירות מתחיל לפעול, פותחים את דף האינטרנט המקומי של ADK: ‏http://localhost:8080/.

אם אתם משתמשים ב-Google Cloud Shell, לוחצים על הלחצן Web Preview (תצוגה מקדימה באינטרנט) תצוגה מקדימה של אתר ובוחרים באפשרות Preview on port 8080 (תצוגה מקדימה ביציאה 8080) בתפריט.

בממשק המשתמש באינטרנט של ADK, שואלים את הסוכן על הנתונים שיש לו גישה אליהם:

What data do you have?

הסוכן ישתמש בכלים של BigQuery MCP כדי לחקור את מערך הנתונים של citibike. הוא יציג לכם סקירה כללית של הטבלאות והשדות שזמינים במערך הנתונים של Citibike.

4. פריסת הסוכן ב-Cloud Run

הפקודה הזו תפרוס את הסוכן ב-Cloud Run באמצעות ADK CLI.

uv tool run --from google-adk==2.4.0 \
  adk deploy cloud_run \
      --with_ui \
      --project $GOOGLE_CLOUD_PROJECT \
      --region $GOOGLE_CLOUD_REGION \
      --service_name bq-data-agent \
      --app_name data_agent \
      data_agent \
      -- \
      --allow-unauthenticated \
      --max-instances 1 \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}"

התנסות בסוכן

השתמשנו באפשרות --with_ui לפריסת הסוכן שלנו. הסוכן נפרס באמצעות ממשק האינטרנט של ADK.

פותחים את כתובת ה-URL של הסוכן בדפדפן האינטרנט. הפקודה adk deploy החזירה את כתובת ה-URL, ואפשר גם לאחזר אותה באמצעות הפקודה gcloud run services:

gcloud run services describe bq-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'

תבקש מהסוכן להסיק מסקנות על סמך נתוני Citibike הזמינים:

We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

הסוכן צריך לעיין במערך הנתונים של Citibike באמצעות שרת ה-MCP של BigQuery, להריץ כמה שאילתות SQL ולהחזיר רשימה של 3 תחנות Citibike.

5. מעולה!

כל הכבוד, סיימתם את ה-Codelab!

מומלץ לעיין במסמכי התיעוד של Cloud Run.

מה נכלל

איך יוצרים סוכן AI באמצעות ערכה לפיתוח סוכנים (ADK) ו-Gemini
איך מחברים את הסוכן לשרת ה-MCP של BigQuery.
איך פורסים את הסוכן ב-Cloud Run.

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

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

אפשרות 1: מחיקת השירות

מחיקת שירות Cloud Run

gcloud run services delete bq-data-agent \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --quiet

אפשרות 2: מחיקת הפרויקט

כדי למחוק את הפרויקט כולו, עוברים אל Manage Resources (ניהול משאבים), בוחרים את הפרויקט שיצרתם בשלב 2 ולוחצים על Delete (מחיקה). אם תמחקו את הפרויקט, תצטרכו לשנות את הפרויקטים ב-Cloud SDK. כדי לראות את רשימת כל הפרויקטים הזמינים, מריצים את הפקודה gcloud projects list. אם אתם רוצים להשתמש בשורת הפקודה, אתם יכולים להשתמש גם בפקודה הזו:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}