שילוב סוכן נתונים עם אפליקציה

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

מידע נוסף מופיע במאמר סקירה כללית על סוכני נתונים.

מטרות

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

עלויות

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

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

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

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

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

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

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

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

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

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

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

כדי להעניק את ההרשאה executesql למכונת Cloud SQL ולהפעיל את Cloud SQL Data API, מריצים את הפקודה הבאה:
‫
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
מחליפים את 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 ואת הסכימה:

    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 ו-airport

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

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

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

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

    SELECT * FROM flights LIMIT 10;
SELECT * FROM airports LIMIT 10;

יצירת סוכן נתונים

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

  1. בחלונית Explorer, לצד סוכני נתונים, לוחצים על הצגת פעולות.
  2. לוחצים על יצירת סוכן.
  3. בשדה Name your agent (מתן שם לסוכן), מזינים flights-assistant.
  4. לוחצים על יצירה.

בדיקת הסוכן ב-Studio

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

  1. בחלונית Explorer, לצד סוכן הנתונים, לוחצים על הצגת פעולות.
  2. לוחצים על בדיקת הנציג.
  3. בעורך השאילתות, לוחצים על יצירת SQL באמצעות סוכן: flights-assistant.

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

    Find flights from SFO to JFK.

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

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

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

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

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

    מסד הנתונים לא מבין את המונח nighttime traffic. יכול להיות שהפעולה הזו תמנע את יצירת שאילתת ה-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;

יצירת הקשר לסוכן

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

כדי ליצור הקשר של הסוכן:

  1. בספרייה המקומית, מתקינים את Gemini CLI. מידע נוסף זמין במאמר מדריך למתחילים ל-Gemini CLI.
  2. מתקינים את ה-CLI של gcloud ומגדירים את פרטי הכניסה ב-Application Default Credentials ‏ (ADC).

  3. מתקינים את התוסף MCP Toolbox Gemini CLI, שמתחבר למסד הנתונים.

    gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

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

    sources:
  flight-sql-source:
    kind: cloud-sql-mysql
    project: PROJECT_ID
    region: REGION_ID
    instance: INSTANCE_ID
    database: DATABASE_ID
    user: USER_NAME
    password: PASSWORD

tools:
  # (Optional) Fetches database schemas for context generation in the bulk generation (/generate_bulk_templates) phase.
  list_flight_schemas_tool:
    kind: mysql-list-tables
    source: flight-sql-source
    description: Use this tool to list all tables and their schemas in the flight database.
  # (Optional) Executes generated SQL for validation in the bulk generation (/generate_bulk_templates) phase.
  execute_sql_tool:
    kind: mysql-execute-sql
    source: flight-sql-source
    description: Use this tool to execute SQL against the flight database.

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

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

  5. מתקינים את uv Python package installer לפי מדריך ההתקנה הרשמי, ומוודאים שההתקנה הצליחה באמצעות הפקודה:

    uv --version

  6. מתקינים את שרת ה-MCP של DB Context Enrichment, שכולל תהליכי עבודה ליצירת הקשר.

    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

  7. מייצאים את מפתח Gemini API כמשתנה סביבה. מידע נוסף על איתור מפתח API זמין במאמר שימוש במפתחות Gemini API.

    export GEMINI_API_KEY="YOUR_API_KEY"

    מחליפים את הערך YOUR_API_KEY במפתח Gemini API.

  8. באותה ספרייה שבה יצרתם את הקובץ tools.yaml, מפעילים את Gemini:

    gemini

  9. משלימים את הגדרת האימות של Gemini CLI.

  10. מוודאים שערכת הכלים של ה-MCP והתוסף להעשרת מסד הנתונים מחוברים ומוכנים לשימוש.

    /mcp list

  11. מריצים את הפקודה /generate_targeted_templates ומבצעים את הפעולות בתהליך:

    /generate_targeted_templates

  12. במסוף, מזינים את השאילתה בשפה טבעית שרוצים להוסיף לתבנית השאילתה.

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

  13. מזינים שאילתת SQL תואמת שרוצים להוסיף לתבנית השאילתה. תבנית השאילתה הזו מגדירה את המונח nighttime כמתרחש בין 5:00 PM לבין 7:00 PM.

    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;

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

    אפשר גם להריץ את תהליך העבודה /generate_bulk_templates כדי ש-Gemini CLI יסרוק את סכימת מסד הנתונים ויציע הקשרים קשורים, וכך יספק הקשר נוסף. חשוב להוסיף גם את list_flight_schemas_tool וגם את execute_sql_tool להגדרת tools.yaml שיצרתם בשלב 4.

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

  16. בוחרים באפשרות ליצירת קובץ הקשר חדש של הסוכן. ‫Gemini יוצר שם קובץ INSTANCE_ID_DATABASE_ID_context_set_TIMESTAMP.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 ?"
      }
    }
  ]
}

העלאת הקשר לסוכן

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

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

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

    מעבר אל Cloud SQL

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

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

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

  5. בחלונית Explorer, לצד סוכני נתונים, לוחצים על הצגת פעולות.

  6. לוחצים על עריכת סוכן.

  7. אופציונלי: עורכים את תיאור הסוכן.

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

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

יצירת שאילתת SQL באמצעות הקשר של הסוכן

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

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

  1. בחלונית Explorer, לצד סוכן הנתונים, לוחצים על הצגת פעולות.
  2. לוחצים על בדיקת הנציג.
  3. בעורך השאילתות, לוחצים על יצירת SQL באמצעות סוכן: flights-assistant.

  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;

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

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

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

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

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

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

    שאילתת ה-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;

שילוב הסוכן באפליקציה

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

  1. מורידים את MCP Toolbox בגרסה 0.24.0 ואילך. ארגז הכלים של MCP חושף את סוכן הנתונים ככלי שאפליקציות יכולות להתחבר אליו. ערכת הכלים של MCP שונה מהתוסף ל-Gemini CLI של MCP Toolbox שהתקנתם קודם, שיוצר הקשר.

  2. בטרמינל, מגדירים את הפרויקט שבו משתמשים.

    gcloud config set project [PROJECT_ID]

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

    gcloud auth application-default login

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

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

    sources:
  gda-api-source:
    kind: cloud-gemini-data-analytics
    projectId: "PROJECT_ID"

tools:
  cloud_gda_query_tool:
    kind: 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: "MYSQL"
            projectId: "PROJECT_ID"
            region: "REGION_ID"
            instanceId: "INSTANCE_ID"
            databaseId: "DATABASE_ID"
          agentContextReference:
            contextSetId: "DATA_AGENT_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: השם של מסד הנתונים שאליו רוצים להתחבר.
    • ‫DATA_AGENT_CONTEXT_SET_ID: המזהה של קבוצת ההקשר של סוכן הנתונים.

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

    ./toolbox --tools-file "tools.yaml"

  7. יוצרים אפליקציית ADK שמפעילה את כלי השאילתות של Gemini לניתוח נתונים באמצעות 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]),
)
    .

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

    adk web --port 8000

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

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

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

    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?

  11. מזינים שאלה שדומה לשאלה בתבנית השאילתה שנוצרה עבור הנציג.

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

    על סמך ההקשר של הסוכן שנוסף קודם, כלי ה-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

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

ממשק המשתמש האינטרנטי של ADK מאפשר לבדוק את הבקשה והתגובה מהכלי QueryData MCP של Gemini Data Analytics. אפשר להשתמש בתשובה הזו כדי לבחון את התשובות של הכלי, כמו שאילתת 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, אפשר להוסיף הקשר נוסף. משתמשים ב-Gemini CLI כדי ליצור הקשר, ואז מעלים את ההקשר המעודכן של הסוכן לסוכן הקיים flights-assistant. מידע נוסף זמין במאמר יצירת הקשרים באמצעות Gemini CLI. המסוף מעבד באופן מיידי את ההקשר החדש אחרי שמעלים אותו, כך שאפשר לשפר את רמת הדיוק של הסוכן בלי שהאפליקציה תושבת.

כמה נציגים

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

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

sources:
  gda-api-source:
    kind: cloud-gemini-data-analytics
    projectId: "<var>PROJECT_ID</var>"
tools:
  cloud_gda_query_tool_v1:
    kind: cloud-gemini-data-analytics-query
    source: gda-api-source
    context:
      datasourceReferences:
        <var>DB_SOURCE</var>:
          databaseReference: ...
          agentContextReference:
            contextSetId: "V1_YOUR_DATA_AGENT_CONTEXT_SET_ID"
    generationOptions: ...
  cloud_gda_query_tool_v2:
    kind: cloud-gemini-data-analytics-query
    source: gda-api-source
    context:
      datasourceReferences:
        <var>DB_SOURCE</var>:
          databaseReference: ...
          agentContextReference:
            contextSetId: "V2_YOUR_DATA_AGENT_CONTEXT_SET_ID"
    generationOptions: ...

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫V1_YOUR_DATA_AGENT_CONTEXT_SET_ID: המזהה של קבוצת ההקשר של סוכן הנתונים לגרסה 1.
  • ‫V2_YOUR_DATA_AGENT_CONTEXT_SET_ID: המזהה של קבוצת ההקשר של סוכן הנתונים לגרסה 2.

הסרת המשאבים

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

מחיקת הסוכן

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

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

    מעבר אל Cloud SQL

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

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

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

  5. בחלונית Explorer, לצד סוכן הנתונים, לוחצים על הצגת פעולות.

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

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

מחיקת המכונה

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

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

    מעבר אל Cloud SQL

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

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

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

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