שילוב של QueryData עם אפליקציה

במדריך הזה מוסבר איך להגדיר את QueryData ב-Cloud SQL ל-PostgreSQL ולהשתמש בו באמצעות Google Cloud המסוף, ואיך לשלב אותו באפליקציה. במאמר הזה מוסבר איך ליצור קובץ של קבוצת הקשר, ליצור קבוצת הקשר שמשתמשת בקובץ של קבוצת הקשר, להשתמש ב-MCP Toolbox כדי לקרוא ל-QueryData API כדי ליצור שאילתות SQL לשאלות בשפה טבעית ולשלב אותה באפליקציה.

מידע נוסף זמין במאמר סקירה כללית על QueryData.

מטרות

  • יוצרים טבלאות במסד הנתונים ומאכלסים אותן בנתונים.
  • יוצרים קובץ של קבוצת הקשר באמצעות סוכן הנדסת ההקשר.
  • יוצרים קבוצה של הקשרים ומעלים קובץ של קבוצת הקשרים.
  • בודקים את QueryData ויוצרים שאילתות SQL ב-Studio.
  • משלבים את QueryData עם האפליקציה באמצעות הכלי Gemini Data Analytics QueryData ב-MCP Toolbox.
  • הוספת ביסוס לתשובות של מודלים גדולים של שפה (LLM) באמצעות שאילתות לחיפוש ערכים.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

כדי ליצור הערכת עלויות בהתאם לשימוש החזוי, אתם יכולים להשתמש במחשבון התמחור.

משתמשים חדשים ב- Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

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

לפני שמתחילים

לפני שיוצרים קבוצת הקשרים, צריך לוודא שמתקיימות הדרישות המוקדמות הבאות.

הפעלת שירותים נדרשים

מפעילים את השירותים הבאים בפרויקט:

הכנת מכונה של Cloud SQL

מוודאים שיש לכם גישה למופע קיים של Cloud SQL או יוצרים מופע חדש. מידע נוסף מופיע במאמר יצירת מכונות ל-Cloud SQL.

כדי לבצע את ההדרכה הזו, צריך מסד נתונים במכונת Cloud SQL. למידע נוסף, קראו את המאמר בנושא יצירת מסד נתונים במכונת Cloud SQL

תפקידים והרשאות נדרשים

מתן הרשאה ל-executesql למופע Cloud SQL

כדי להעניק את ההרשאה executesql למכונת Cloud SQL ולהפעיל את Cloud SQL Data API, מריצים את הפקודה הבאה: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
מחליפים את מה שכתוב בשדות הבאים:
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫INSTANCE_ID: המזהה של מופע Cloud SQL.
כדי לבצע את השלבים במדריך הזה, צריך להיכנס אל Google Cloud ולאמת את מסד הנתונים באמצעות אימות IAM.

יצירת הסכימה והטבלאות flights ו-airports

בקטע הזה יוצרים את טבלאות מסד הנתונים flights ו-airports למדריך הזה.

  1. נכנסים לדף Cloud SQL במסוף Google Cloud .

    מעבר אל Cloud SQL

  2. בוחרים מופע מהרשימה.

  3. בתפריט הניווט, לוחצים על Cloud SQL Studio.

  4. נכנסים ל-Studio באמצעות אימות של ניהול זהויות והרשאות גישה (IAM).

  5. לוחצים על אימות. בחלונית Explorer מוצגת רשימה של האובייקטים במסד הנתונים.

  6. לוחצים על New SQL editor tab או על New tab כדי לפתוח כרטיסייה חדשה.

  7. כדי ליצור את הטבלה ואת הסכימה airports, מריצים את הצהרת ה-SQL הבאה:

    CREATE TABLE IF NOT EXISTS airports (
  id INT PRIMARY KEY,
  iata TEXT,
  name TEXT,
  city TEXT,
  country TEXT
  );

  8. יוצרים את הטבלה flights ואת הסכימה:

    CREATE TABLE IF NOT EXISTS flights (
  id INT PRIMARY KEY,
  airline VARCHAR(10),
  flight_number INT,
  departure_airport VARCHAR(5),
  arrival_airport VARCHAR(5),
  departure_time TIMESTAMP,
  arrival_time TIMESTAMP,
  departure_gate VARCHAR(10),
  arrival_gate VARCHAR(10)
);

מאכלסים את הטבלאות flights ו-airports

בקטע הזה, מאכלסים את הטבלאות flights ו-airports באמצעות סקריפטים של SQL שמופיעים כאן.

  1. מאכלסים את הטבלה airports.

  2. מאכלסים את הטבלה flights.

  3. מריצים את השאילתה הבאה כדי לוודא שהטבלאות מכילות נתונים:

    SELECT * FROM "public"."flights" LIMIT 10;
SELECT * FROM "public"."airports" LIMIT 10;

יצירת קבוצה של הקשרים ב-Studio

בקטע הזה, יוצרים קבוצת הקשר בשם flights-assistant. קבוצת ההקשר הזו לא כוללת קובץ של קבוצת הקשר שהועלה אליה.

  1. נכנסים לדף Cloud SQL במסוף Google Cloud .

    מעבר אל Cloud SQL

  2. בוחרים מופע מהרשימה.

  3. בתפריט הניווט, לוחצים על Cloud SQL Studio.

  4. נכנסים ל-Studio באמצעות אימות IAM.

  5. בחלונית Explorer, ליד Context sets, לוחצים על View actions.

  6. לוחצים על יצירת קבוצת הקשרים.

  7. בשדה Context set name, מזינים flights-assistant.

  8. לוחצים על יצירה.

בדיקת QueryData ב-Studio

בקטע הזה, תשתמשו בקבוצת ההקשר flights-assistant כדי לשאול שאלות בשפה טבעית וליצור שאילתת SQL. מכיוון שלא הועלה לקבוצת ההקשרים קובץ הגדרת הקשר, גם אחרי ששואלים שאלה עם הקשר כמו nighttime traffic, הכלי QueryData יוצר שאילתה לא אופטימלית.

  1. בחלונית Explorer, לצד קבוצת ההקשר, לוחצים על View actions (הצגת פעולות).
  2. לוחצים על בדיקת הגדרת ההקשר.
  3. בעורך השאילתות, לוחצים על יצירת SQL באמצעות QueryData עם: flights-assistant.

  4. מזינים את השאלה הבאה בשפה טבעית כדי ליצור שאילתת SQL, ולוחצים על יצירה.

    Find flights from SFO to JFK.

    בודקים את שאילתת ה-SQL. שימו לב שהפונקציה QueryData יוצרת את ה-SQL הנכון לשאלה הברורה הזו.

      SELECT
    *
  FROM
    "flights"
  WHERE
    "departure_airport" = 'SFO' AND "arrival_airport" = 'JFK';

  5. בחלון Generate SQL using QueryData with: flights-assistant (יצירת SQL באמצעות QueryData עם: flights-assistant), לוחצים על Edit (עריכה).

  6. מזינים את השאלה הבאה בשפה טבעית כדי ליצור שאילתת SQL, ולוחצים על עדכון.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

    מסד הנתונים לא מבין את המונח תנועה nighttime. יכול להיות שהדבר ימנע את יצירת שאילתת ה-SQL או יגרום ליצירת שאילתה שמתעלמת מהמונח, כמו שמוצג בשאילתה הבאה.

    -- The database schema does not contain information about traffic.
-- Returning all flights departing from New York airports.
SELECT
  f.airline,
  f.flight_number,
  a.name AS departure_airport_name,
  f.departure_time,
  b.name AS arrival_airport_name,
  f.arrival_time
FROM
  flights AS f
JOIN
  airports AS a
  ON f.departure_airport = a.iata
JOIN
  airports AS b
  ON f.arrival_airport = b.iata
WHERE
  a.city = 'New York'
ORDER BY
  f.departure_time;

  7. בחלון Generate SQL using QueryData with: flights-assistant (יצירת SQL באמצעות QueryData עם: flights-assistant), לוחצים על Edit (עריכה).

  8. מזינים את השאלה הבאה בשפה טבעית כדי ליצור שאילתת SQL, ולוחצים על עדכון.

    flight to disney world

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

    SELECT
  "flights"."id",
  "flights"."airline",
  "flights"."flight_number",
  "flights"."departure_airport",
  "flights"."arrival_airport",
  "flights"."departure_time",
  "flights"."arrival_time",
  "flights"."departure_gate",
  "flights"."arrival_gate"
FROM
  "flights"
INNER JOIN
  "airports" ON "flights"."arrival_airport" = "airports"."iata"
WHERE
  "airports"."name" ILIKE '%Disney World%';

יצירת הקשר לקבוצת ההקשרים

בקטע הזה יוצרים קובץ הקשר שעוזר לשפר את יכולות השאילתות של קבוצת ההקשר.

מגדירים את הסביבה

לפני שמתחילים ליצור הקשר, צריך להכין את הסביבה.

כדי להגדיר את הסביבה, פועלים לפי השלבים הבאים:

  1. מתקינים את Antigravity CLI. מידע נוסף זמין במאמר מדריך למתחילים ל-Antigravity CLI.
  2. מתקינים את Google Cloud CLI.

  3. הגדרת Application Default Credentials‏ (ADC). מריצים את הפקודות הבאות בטרמינל כדי לבצע אימות ולבחור את הפרויקט:

    gcloud auth application-default login

  4. מתקינים את הפלאגין של סוכן הנדסת ההקשר, שכולל תהליכי עבודה ליצירת הקשר. מחליפים את VERSION בגרסה שפורסמה הנדרשת:

    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION

    מוודאים שהגרסה שמתקינים היא v0.6.0 ואילך. כדי לעדכן את הפלאגין של סוכן הנדסת ההקשר, מסירים את הגרסה הישנה ומתקינים את הגרסה החדשה:

    agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/NEW_VERSION

  5. בטרמינל, מפעילים את antigravity CLI.

    agy

  6. מגדירים חיבור למסד נתונים. התוסף דורש חיבור למסד נתונים כדי ליצור הקשר, והחיבור הזה נתמך על ידי MCP Toolbox ומוגדר בקובץ ההגדרות tools.yaml.

    כדי ליצור את קובץ ההגדרות tools.yaml בספרייה הנוכחית, מזינים הנחיה כמו Help me set up the database connection ופועלים לפי ההוראות שמופיעות במיומנות. מידע נוסף על קובץ tools.yaml זמין במסמכי העזרה של MCP Toolbox.

  7. כדי לטעון מחדש את התצורה אחרי שיוצרים את הקובץ tools.yaml, מריצים את הפקודה הבאה ב-Antigravity CLI ופועלים לפי ההוראות לטעינה מחדש של שרת ה-MCP של ארגז הכלים:

    /mcp

  8. בוחרים באפשרות toolbox.

  9. בוחרים באפשרות Restart.

  10. מוודאים שערכת הכלים של MCP והפלאגין של סוכן הנדסת ההקשר מחוברים ומוכנים לשימוש.

    /mcp

יצירת הקשר של התבנית

בקטע הזה, כדי לפתור את הבעיה מהקטע הקודם שבה QueryData לא זיהה את המונח nighttime traffic, מגדירים את המונח בקובץ של קבוצת ההקשר כטראפיק שמתרחש בין 5:00 PM ל-7:00 PM.

כדי ליצור הקשר של התבנית:

  1. מזינים את ההנחיה הבאה במעטפת האג'נטית:

    Generate a template for the question: "Tell me flights that can help me beat nighttime traffic if traveling from New York" with the following SQL query:
SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
  ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

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

  3. בודקים את תבנית השאילתה שנוצרה. אפשר לשמור את תבנית השאילתה כקובץ הקשר חדש של הסוכן או לצרף אותה לקובץ הקשר הקיים של הסוכן.

  4. נותנים לסוכן הנחיה save it to contextset.json. הסוכן יוצר את הקובץ באותה תיקייה, עם התוכן הבא:

    {
  "templates": [
    {
      "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
      "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
      "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
      "parameterized": {
        "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = ? AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
        "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from ?"
      }
    }
  ]
}

יצירת הקשר לחיפוש ערכים

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

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

  1. מזינים את ההנחיה הבאה במעטפת האג'נטית:

  2. מזינים postgresql כדי לבחור ב-Cloud SQL כמנוע מסד הנתונים.

  3. מזינים את הגדרת החיפוש של הערך באופן הבא:

    Generate a value search on table "airports" for column "city" with concept "Airport City" using match function "SEMANTIC_SIMILARITY_MATCH".

  4. בודקים את הגדרת החיפוש של הערך שנוצרה. אפשר לשמור את הגדרת החיפוש של הערך כקובץ חדש של הגדרות הקשר, או להוסיף אותה לקובץ קיים של הגדרות הקשר.

  5. נותנים הנחיה לסוכן Append the context to context_set.json. הפעולה הזו מוסיפה את הגדרת החיפוש של הערך לקובץ ההקשר שנוצר בקטע הקודם.

  6. מזינים את מופע מסד הנתונים ואת שם מסד הנתונים שעבורם נוצר קובץ הגדרת ההקשר.

    קובץ ההקשר הקיים מתעדכן עם הגדרת החיפוש של הערך, עם התוכן הבא:

      {
    "templates": [
      {
        "nl_query": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
        "sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = 'New York' AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
        "intent": "Tell me flights that can help me beat nighttime traffic if traveling from New York",
        "manifest": "Tell me flights that can help me beat nighttime traffic if traveling from a given city",
        "parameterized": {
          "parameterized_sql": "SELECT f.airline, f.flight_number, a.name AS airport_name, f.departure_time FROM flights f JOIN airports a ON f.departure_airport = a.iata WHERE a.city = $1 AND (EXTRACT(HOUR FROM f.departure_time) < 17 OR EXTRACT(HOUR FROM f.departure_time) >= 19) ORDER BY f.departure_time;",
          "parameterized_intent": "Tell me flights that can help me beat nighttime traffic if traveling from $1"
        }
      }
    ],
    "value_searches": [
      {
          "query": "/* Requires extensions: vector, google_ml_integration */ WITH SemanticMetrics AS (    SELECT T.city AS original_value, (        (google_ml.embedding('gemini-embedding-001', $value)::vector <=>          google_ml.embedding('gemini-embedding-001', T.city)::vector) / 2.0    ) AS normalized_dist     FROM airports T     WHERE T.city IS NOT NULL) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, ''::text AS context FROM SemanticMetrics",
          "concept_type": "Airport City",
          "description": "Semantic search for airport city name"
      }
  ]
  }

העלאת קובץ של קבוצת הקשר ל-QueryData

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

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

  1. נכנסים לדף Cloud SQL במסוף Google Cloud .

    מעבר אל Cloud SQL

  2. בוחרים מופע מהרשימה.

  3. בתפריט הניווט, לוחצים על Cloud SQL Studio.

  4. נכנסים ל-Studio באמצעות אימות של ניהול זהויות והרשאות גישה (IAM).

  5. בחלונית Explorer, לצד Context sets (קבוצות של הקשרים), לוחצים על סמל Actions (פעולות) ().

  6. לוחצים על עריכת קבוצת ההקשרים.

  7. אופציונלי: עורכים את תיאור קבוצת ההקשרים.

  8. בקטע העלאת קובץ של קבוצת הקשרים, לוחצים על עיון ובוחרים את קובץ קבוצת ההקשרים שנוצר קודם.

  9. לוחצים על Save.

יצירת שאילתת SQL באמצעות QueryData

בקטע הזה, תשתמשו בקובץ ההקשר שהעליתם כדי לשאול שאלות בשפה טבעית. כך תוכלו לוודא ש-QueryData מבין ומחיל נכון הגדרות של מונחים כמו nighttime traffic וביטויים קשורים אחרים, ושהחיפוש של ערכים ממפה ביטויי ערכים לערכים ספציפיים שמאוחסנים בעמודות של מסד הנתונים (לדוגמה, מיפוי של 'דיסני וורלד' ל'אורלנדו')

כדי ליצור שאילתות SQL, פועלים לפי השלבים הבאים:

  1. בחלונית Explorer, ליד קבוצת ההקשר, לוחצים על View actions (הצגת פעולות).
  2. לוחצים על בדיקת הגדרת ההקשר.
  3. בעורך השאילתות, לוחצים על יצירת SQL באמצעות QueryData עם: עוזר לטיסות.

  4. מזינים את השאלה הבאה בשפה טבעית כדי ליצור שאילתת SQL, ולוחצים על יצירה.

    Tell me flights that can help me beat nighttime traffic if traveling from New York

    שאילתת ה-SQL שנוצרת נראית כך:

    SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a ON f.departure_airport = a.iata
WHERE
  a.city = 'New York'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

    זו אותה שאלה שהוספתם להקשר של QueryData. אפשר לראות שעכשיו QueryData יכול לפרש בצורה מדויקת את המונח nighttime traffic.

    למרות שההקשר נובע משאלה מסוימת, הכלי QueryData משתמש בו כדי לשפר את יצירת ה-SQL למגוון רחב של שאלות דומות.

  5. בחלון Generate SQL using QueryData with: flights-assistant (יצירת SQL באמצעות QueryData עם: flights-assistant), לוחצים על Edit (עריכה).

  6. מזינים את השאלה הבאה (או שאלה דומה) כדי ליצור שאילתת SQL, ולוחצים על עדכון.

    What are the flights that can help me avoid evening traffic if departing from Boston

    מכיוון שהשאלה מחליפה את המונח nighttime traffic במונח דומה, evening traffic, QueryData מספקת תשובה עקבית לשאלה הזו על ידי יישום אותה פרשנות.

    שאילתת ה-SQL שנוצרת נראית כך:

    -- What are the flights that can help me avoid evening traffic if departing from Boston
SELECT
  f.airline,
  f.flight_number,
  a.name AS airport_name,
  f.departure_time
FROM
  flights f
JOIN
  airports a
ON
  f.departure_airport = a.iata
WHERE
  a.city = 'Boston'
  AND (
    EXTRACT(HOUR FROM f.departure_time) < 17
    OR EXTRACT(HOUR FROM f.departure_time) >= 19
  )
ORDER BY
  f.departure_time;

  7. בחלון Generate SQL using QueryData with: flights-assistant (יצירת SQL באמצעות QueryData עם: flights-assistant), לוחצים על Edit (עריכה).

  8. מזינים את השאלה הבאה כדי ליצור שאילתת SQL ולוחצים על עדכון.

    flights to disney world

    שאילתת ה-SQL שנוצרת נראית כך:

    SELECT
  "flights"."id",
  "flights"."airline",
  "flights"."flight_number",
  "flights"."departure_airport",
  "flights"."arrival_airport",
  "flights"."departure_time",
  "flights"."arrival_time",
  "flights"."departure_gate",
  "flights"."arrival_gate"
FROM
  "flights"
JOIN
  "airports" ON "flights"."arrival_airport" = "airports"."iata"
WHERE
  "airports"."city" = 'Orlando';

    שימו לב שעכשיו QueryData יכול לפרש בצורה מדויקת את המונח disney world כקשור לעיר Orlando.

שילוב של QueryData עם האפליקציה

בקטע הזה, יוצרים סוכן QueryData לאפליקציה לחיפוש טיסות. הסוכן QueryData מספק ממשק שיחה לטבלאות flights ו-airports שיצרתם קודם. בנוסף, נסביר איך ליצור את סוכן QueryData ולשלב אותו באפליקציה באמצעות הערכה לפיתוח סוכנים (ADK), הכלי QueryData MCP של Gemini Data Analytics וקבוצת הקשר כדי לשפר את איכות התשובות.

  1. מורידים את MCP Toolbox מגרסה 0.31.0 ואילך. ‫MCP toolbox חושף את סוכן QueryData ככלי שאפליקציות יכולות להתחבר אליו. ערכת הכלים של MCP שונה מסוכן הנדסת ההקשר שהתקנתם קודם, שמייצר הקשר.

  2. מגדירים Application Default Credentials (ADC).

    gcloud auth application-default login

  3. מאתרים את מזהה קבוצת ההקשר. מידע נוסף על איתור מזהה ערכת ההקשר

  4. יוצרים את ההגדרה tools.yaml כדי להתחבר לסוכן QueryData באמצעות MCP Toolbox. מידע נוסף זמין במאמרים בנושא מקור נתונים של Gemini Data Analytics ובנושא הכלי QueryData של Gemini Data Analytics.

    kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: "PROJECT_ID"
---
kind: tool
name: cloud_gda_query_tool
type: cloud-gemini-data-analytics-query
source: gda-api-source
description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
location: "REGION_ID"
context:
  datasourceReferences:
    cloudSqlReference:
      databaseReference:
        engine: "POSTGRESQL"
        projectId: "PROJECT_ID"
        region: "REGION_ID"
        instanceId: "INSTANCE_ID"
        databaseId: "DATABASE_ID"
      agentContextReference:
        contextSetId: "CONTEXT_SET_ID"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫REGION_ID: האזור של מופע Cloud SQL (לדוגמה, us-central1).
    • ‫INSTANCE_ID: המזהה של מופע Cloud SQL.
    • ‫DATABASE_ID: השם של מסד הנתונים שאליו רוצים להתחבר.
    • ‫CONTEXT_SET_ID: מזהה קבוצת ההקשר. מידע נוסף על איתור מזהה ערכת ההקשר

  5. מריצים את שרת ה-MCP Toolbox עם הקובץ tools.yaml.

    ./toolbox --config "tools.yaml"

  6. יצירת אפליקציית ADK שמפעילה את הכלי QueryData של Gemini Data Analytics באמצעות Python SDK של MCP Toolbox. מידע נוסף על השימוש ב-Python SDK של MCP Toolbox זמין במדריך למתחילים בנושא Toolbox. מידע נוסף על השימוש ב-Python ADK זמין במדריך למתחילים בנושא ADK.

    1. יוצרים ספרייה לאחסון האפליקציה, לדוגמה flight-assistant-app.

    2. עוברים לספרייה flight-assistant-app.

      mkdir flight-assistant-app
cd flight-assistant-app

    3. מריצים את הפקודות הבאות בספרייה flight-assistant-app כדי ליצור סביבה וירטואלית ולהתקין את הרכיבים הנדרשים.

      python3 -m venv .venv
source .venv/bin/activate
pip install toolbox-core
pip install google-genai
pip install google-adk

    4. הגדרת סוכן ADK.

      1. יוצרים סוכן ADK.

        adk create my_agent

      2. בוחרים את המודל gemini-2.5-flash.

      3. בוחרים באפשרות Google AI ומזינים את מפתח Gemini API. מידע נוסף על איתור מפתח API זמין במאמר שימוש במפתחות API של Gemini.

    5. מחליפים את התוכן של הקובץ agent.py בקוד אפליקציה לדוגמה של Flight Data Assistant שמופיע בהמשך.

      from typing import cast

from google.adk.agents.llm_agent import Agent
from google.adk.agents.llm_agent import ToolUnion

from toolbox_core import ToolboxSyncClient

TOOLBOX_URL = "http://127.0.0.1:5000"

INSTRUCTION = """
# ROLE
You are a friendly and factual flight data assistant. Your goal is to help users find the best flights for their needs by providing accurate information with a helpful, professional tone.
- use the Query Data Tool to answer the user's question, if the tool fails to generate a valid query, ask the user to clarify their question.

# OPERATIONAL CONSTRAINTS
- TOOL LIMITATION: You only have access to the Query Data Tool. Do not claim to have capabilities beyond what this tool provides.
- TRANSPARENCY POLICY: Maintain a seamless user experience. Never mention that you are using a tool, querying a database, or generating SQL. Frame all responses as your own direct assistance.
- SCOPE MANAGEMENT: If a user asks for something beyond your capabilities, politely state that you cannot perform that specific task. Guide the user towards what you can help with.

# COMMUNICATION STYLE
- Be concise and scannable when listing answers.
- Maintain a helpful, professional persona.

=====

# QUERY DATA TOOL

Inputs:
1. query: A natural language formulation of a database query.

Outputs: (all optional)
1. disambiguation_question: Clarification questions or comments where the tool needs the users' input.
2. generated_query: The generated query for the user query.
3. intent_explanation: An explanation for why the tool produced `generated_query`.
4. query_result: The result of executing `generated_query`.
5. natural_language_answer: The natural language answer that summarizes the `query` and `query_result`.

Usage guidance:
1. If `disambiguation_question` is produced, then solicit the needed inputs from the user and try the tool with a new `query` that has the needed clarification.
2. If `natural_language_answer` is produced, use `intent_explanation` and `generated_query` to see if you need to clarify any assumptions for the user.
3. If the tool output indicates failure or empty results, explain that clearly using the provided reasoning.
"""

client = ToolboxSyncClient(TOOLBOX_URL)

mcp_tool = client.load_tool("cloud_gda_query_tool")

root_agent = Agent(
    model="gemini-2.5-flash",
    name="root_agent",
    instruction=INSTRUCTION,
    tools=cast(list[ToolUnion], [mcp_tool]),
)

  7. מריצים את הפקודות הבאות בספרייה flight-assistant-app כדי להפעיל את האפליקציה ולגשת לשרת האינטרנט של ADK בכתובת http://127.0.0.1:8000.

    adk web --port 8000

  8. מזינים טקסט כלשהו, כמו hello, כדי להתחיל אינטראקציה עם הסוכן.

    סוכן ה-ADK עונה על שאלות כלליות ומפעיל את כלי ה-MCP הנדרשים.

  9. מזינים את השאלה הבאה שקשורה לטיסה.

    How many flights depart from the west side?

    כדי לענות על השאלה הזו, מופעל כלי ה-MCP. עם זאת, המונח the west הוא דו-משמעי ולא מציין שדות תעופה ספציפיים, ולכן הכלי MCP מחזיר שאלה להסרת דו-משמעות, והסוכן משתמש בה כדי ליצור תגובה.

    I cannot determine how many flights depart from the 'west side' as the database does not contain information about which airports are considered to be on the 'west side'. However, I can help you with questions like:

1. How many flights depart from a specific airport?

2. What are the departure airports for all flights?

3. How many flights depart from each airport? Would you like to rephrase your question based on these options?

  10. מזינים שאלה דומה לזו שבתבנית השאילתה שנוצרה לסוכן.

    Help me find flights from San Francisco that avoid the evening rush hour.

    על סמך ההקשר של QueryData שנוסף קודם, כלי ה-MCP מבין ש-evening traffic מתרחש בין השעות 17:00 ל-19:00. הכלי MCP מחזיר את הנתונים המשויכים לסוכן כדי שישתמש בהם ליצירת התשובה.

    Here are the flights departing from San Francisco that avoid the evening rush hour (defined as 5 PM to 7 PM):

* UA 1532 departing at 05:50:00
* UA 1158 departing at 05:57:00
* CY 922 departing at 06:38:00
* OO 5441 departing at 07:08:00
* UA 616 departing at 07:14:00
* AA 24 departing at 07:14:00
* B6 434 departing at 08:00:00
* AA 242 departing at 08:18:00
* UA 1739 departing at 08:22:00
* OO 6336 departing at 08:32:00
* US 1784 departing at 08:47:00
* DL 1631 departing at 09:00:00
* DL 1106 departing at 09:06:00
* OO 5427 departing at 09:06:00
* CY 352 departing at 09:25:00

  11. מזינים שאלה על סמך סוג המושג שהוספתם בהקשר של סוכן QueryData.

    Get me flights to disney world

    על סמך ההקשר של חיפוש הערכים שנוסף קודם, סוכן QueryData מבין שהערך disney world מתייחס לעיר Orlando ומחזיר את הנתונים המשויכים כדי שהסוכן יוכל להשתמש בהם ליצירת התשובה.

    Here are the flights heading to Orlando, which is the location of Disney World:

* Flight UA 1249 departs from SFO and arrives at MCO on 2025-01-02 at 18:15:00Z.
* Flight UA 698 departs from SFO and arrives at MCO on 2025-01-02 at 22:33:00Z.
* Flight UA 292 departs from SFO and arrives at MCO on 2025-01-03 at 06:37:00Z.

שיפור הביצועים של הסוכן

ממשק המשתמש האינטרנטי של ADK מאפשר לבדוק את הבקשה והתגובה מכלי ה-MCP של Gemini Data Analytics QueryData. אפשר להשתמש בתשובה הזו כדי לבחון את התשובות של הכלי, כמו שאילתת SQL שנוצרה, קבוצת תוצאות, הסבר על הכוונה, שאלה להסרת דו-משמעות ותשובה בשפה טבעית, כדי לוודא שהתשובות של הסוכן נכונות.

לדוגמה, אם הזנתם קודם את הטקסט How many flights depart from the west side?, לוחצים על בועת הצ'אט של הסוכן. בכרטיסייה אירוע בחלונית הניווט הימנית, מרחיבים את functionResponse כדי לראות את התשובה הבאה.

"{"disambiguationQuestion": ["[NOT_ENOUGH_INFO] The database schema does not
contain information about which airports are on the 'west side'. Therefore, I
cannot determine how many flights depart from the west side.Possible alternative
questions: 1. How many flights depart from a specific airport? 2. What are the
departure airports for all flights? 3. How many flights depart from each
airport?"]}"

שיפור הדיוק של התשובה

כדי לשפר את הדיוק של התשובות שמתקבלות מהכלי Gemini Data Analytics QueryData, אפשר להוסיף הקשר נוסף. משתמשים בסוכן הנדסת ההקשר כדי ליצור הקשר, ואז מעלים את קובץ קבוצת ההקשר המעודכן לסוכן flights-assistant QueryData הקיים. מידע נוסף זמין במאמר בנושא ניהול של קבוצות הקשר ב-Data Agents Studio. המסוף מעבד באופן מיידי את ההקשר החדש אחרי שמעלים אותו, כך שאפשר לשפר את רמת הדיוק של הסוכן בלי שהאפליקציה תושבת.

כמה נציגים

בסביבת הפיתוח, אפשר לבצע בדיקות A/B בכמה הקשרים של סוכן QueryData על ידי הקצאת שמות שונים לכלים בקובץ tools.yaml. לדוגמה, אפשר ליצור הגדרות ייחודיות של tools.yaml על ידי הגדרת שני כלים של cloud-gemini-data-analytics-query עם שמות שונים, כמו cloud_gda_query_tool_v1 ו-cloud_gda_query_tool_v2. ההגדרה הזו מאפשרת לכם להטמיע לוגיקה של אפליקציה שבוחרת באופן פרוגרמטי את גרסת ההקשר הנדרשת על ידי בחירת שם הכלי המתאים.

בדוגמה הבאה tools.yaml אפשר לראות איך מגדירים כמה סוכני QueryData למקור מסד נתונים:

kind: source
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: <var>PROJECT_ID</var>
---
kind: tool
name: cloud_gda_query_tool_v1
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V1_YOUR_CONTEXT_SET_ID"
generationOptions: ...
---
kind: tool
name: cloud_gda_query_tool_v2
type: cloud-gemini-data-analytics-query
source: gda-api-source
context:
  datasourceReferences:
    <var>DB_SOURCE</var>:
      databaseReference: ...
      agentContextReference:
        contextSetId: "V2_YOUR_CONTEXT_SET_ID"
generationOptions: ...

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫V1_YOUR_CONTEXT_SET_ID: מזהה קבוצת ההקשר לגרסה 1.
  • ‫V2_YOUR_CONTEXT_SET_ID: מזהה קבוצת ההקשר לגרסה 2

הסרת המשאבים

בקטעים הבאים מוסבר איך למחוק את המשאבים והאובייקטים האלה.

מחיקת קבוצת ההקשרים

לפני שמוחקים את המופע, צריך למחוק את קבוצת ההקשר שיצרתם.

  1. נכנסים לדף Cloud SQL במסוף Google Cloud .

    מעבר אל Cloud SQL

  2. בוחרים מופע מהרשימה.

  3. בתפריט הניווט, לוחצים על Cloud SQL Studio.

  4. נכנסים ל-Studio באמצעות אימות של ניהול זהויות והרשאות גישה (IAM).

  5. בחלונית Explorer, לצד קבוצת ההקשר, לוחצים על View actions (הצגת פעולות).

  6. בחלון מחיקת קבוצת הקשרים, מזינים flight-assistant בתיבת האישור.

  7. לוחצים על אישור.

מחיקת המכונה

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

  1. נכנסים לדף Cloud SQL במסוף Google Cloud .

    מעבר אל Cloud SQL

  2. בוחרים מופע מהרשימה.

  3. לוחצים על Delete.

  4. כדי לאשר שרוצים למחוק את המופע, מזינים את שם המופע ולוחצים על מחיקה.

המאמרים הבאים