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

חיבור לסוכן לאינטראקציה עם נתונים באמצעות MCP

אדמינים של פלטפורמה מבוססת-סוכנים של צד שלישי (כמו Claude Code,‏ Claude Cowork או ChatGPT) או של Google (כמו Gemini Enterprise) יכולים להגדיר חיבור Model Context Protocol‏ (MCP) מותאם אישית לשרת ה-MCP המרוחק של Conversational Analytics API‏ (https://geminidataanalytics.googleapis.com/mcp). חיבור הפלטפורמה מבוססת-הסוכנים לשרת הזה מאפשר לסוכן הבסיס של הפלטפורמה לגלות סוכנים ייעודיים לאינטראקציה עם נתונים ולשלוח אליהם שאילתות בשם משתמשים עסקיים.

שרת ה-MCP המרוחק של Conversational Analytics API משתמש בהרשאה באמצעות OAuth 2.0 עם 3 רגליים כדי להפיץ את פרטי הכניסה של משתמשי הקצה (EUC) ל-BigQuery. ההעברה הזו מבטיחה שבקשות הגילוי של הסוכן והשאילתות ב-BigQuery יפעלו תחת הזהות של המשתמש המאומת, ובהתאם להרשאות הקיימות של ניהול הזהויות והרשאות הגישה (IAM) ולמדיניות של משילות מידע (data governance). סוכנים לאינטראקציה עם נתונים שמגובים ב-Looker לא מקבלים פרטי כניסה של משתמשי קצה. במקום זאת, השאילתות דורשות פרטי כניסה נפרדים של לקוח Looker API (מידע נוסף זמין במאמר אימות של סוכנים לאינטראקציה עם נתונים שמגובים ב-Looker).

במאמר שרת MCP מרוחק של Conversational Analytics API מוסבר איך סוכני הבסיס (הסוכנים הראשיים שמקבלים את בקשות המשתמשים) מתקשרים עם שרת ה-MCP המרוחק.

הערה: אי אפשר לגשת לסוכנים לאינטראקציה עם נתונים שאתם יוצרים בממשק המשתמש של Looker או באמצעות Looker API דרך שרת ה-MCP המרוחק של Conversational Analytics API. כדי לשלוח שאילתות לנתוני Looker דרך שרת ה-MCP הזה, אתם צריכים ליצור סוכן לאינטראקציה עם נתונים באמצעות Conversational Analytics API עם מקור נתונים של Looker. כששולחים שאילתות לסוכנים לאינטראקציה עם נתונים שמגובים ב-Looker באמצעות כלי ה-MCP של chat, הבקשה חייבת לכלול את פרטי הכניסה ל-Looker API באובייקט credentials. שרת ה-MCP שמנוהל על ידי Looker מספק כלים לשליחת שאילתות ישירות למודלים של Looker, אבל הוא לא מציג סוכנים לאינטראקציה עם נתונים.

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

לפני שמגדירים את חיבור ה-MCP בפלטפורמת הסוכנים, צריך לבצע את הפעולות הבאות:

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

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

כדי לקבל את ההרשאות שדרושות לאימות דרך שרת ה-MCP המרוחק ולשליחת שאילתות לסוכנים לאינטראקציה עם נתונים, בקשו מהאדמין להקצות לכם את התפקידים הבאים ב-IAM:

צ'אט עם סוכנים לאינטראקציה עם נתונים:
- Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser) בפרויקט
- משתמש Gemini ל-Google Cloud (roles/cloudaicompanion.user) בפרויקט
הרצת שאילתות ב-BigQuery: BigQuery Job User (roles/bigquery.jobUser) בפרויקט לחיוב
קריאת נתונים ב-BigQuery: BigQuery Data Viewer (roles/bigquery.dataViewer) במערך הנתונים או בטבלה

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

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

הגדרת פרטי כניסה והיקפי הרשאות של OAuth 2.0

כדי לאפשר לפלטפורמת הסוכנים לאמת משתמשים ולהעביר את פרטי הכניסה שלהם לשרת ה-MCP המרוחק של Conversational Analytics API, צריך ליצור פרטי כניסה ל-OAuth 2.0 (מזהה לקוח וסוד לקוח) בפרויקט ב- Google Cloud .

פועלים לפי השלבים הרגילים שמפורטים במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs כדי להגדיר את מסך ההסכמה ל-OAuth וליצור מזהה לקוח ב-OAuth 2.0 בדף Credentials במסוףGoogle Cloud . כשמגדירים את פרטי הכניסה, צריך להחיל את ההגדרות הבאות שספציפיות לשילוב של Conversational Analytics API עם MCP:

Audience: אם הארגון משתמש ב-Google Workspace, בוחרים באפשרות Internal. הבחירה הזו מגבילה את הגישה למשתמשים בארגון, מונעת את הצורך באימות אפליקציות OAuth להיקפים רגישים, ומבטיחה שמדיניות בקרת הגישה לאפליקציות ב-Google Workspace לא תחסום את האימות של המשתמשים.
סוג אפליקציית האינטרנט וכתובת ה-URI להפניה אוטומטית: בוחרים באפשרות אפליקציית אינטרנט כסוג האפליקציה, ומוסיפים את Authorized redirect URI שנדרש על ידי פלטפורמת הסוכנים (לדוגמה, https://vertexaisearch.cloud.google.com/oauth-redirect כשמגדירים מחבר MCP בהתאמה אישית ב-Gemini Enterprise).
היקפי הרשאות ב-OAuth: מגדירים את מסך ההסכמה ל-OAuth ואת הלקוח כך שיבקשו את שני היקפי ההרשאות הבאים, כדי שלנציג הראשי תהיה הרשאה להפעיל את הכלים של Conversational Analytics API ולהריץ שאילתות לקריאה בלבד ב-BigQuery בשם המשתמש:
- היקף הנתונים ב-Gemini Data Analytics: https://www.googleapis.com/auth/geminidataanalytics
- היקף הרשאות לקריאה בלבד ב-BigQuery: https://www.googleapis.com/auth/bigquery.readonly
מעתיקים את מזהה הלקוח ואת סוד הלקוח שנוצרו ושומרים אותם במקום מאובטח.

הגדרת החיבור ל-MCP בהתאמה אישית

אחרי שיוצרים את מזהה הלקוח וסוד הלקוח ב-OAuth 2.0, רושמים חיבור MCP בהתאמה אישית (או מחבר MCP בהתאמה אישית) בהגדרות הניהול של הפלטפורמה מבוססת הסוכנים:

בפלטפורמה מבוססת-הסוכנים, יוצרים חיבור חדש לשרת MCP בהתאמה אישית ומציינים את ערכי ההגדרות הבאים:

הגדרה	ערך
כתובת ה-URL של שרת ה-MCP	`https://geminidataanalytics.googleapis.com/mcp`
שיטת אימות	OAuth 2.0
כתובת URL להרשאה	`https://accounts.google.com/o/oauth2/v2/auth`
פרמטרים של כתובת URL להרשאה	`&access_type=offline&prompt=consent` השתמשו במחרוזת הפרמטרים הזו אם הפלטפורמה שלכם דורשת טוקנים של רענון אופליין לסשנים של משתמשים.
כתובת URL לטוקן	`https://oauth2.googleapis.com/token`
היקפים	`https://www.googleapis.com/auth/geminidataanalytics` `https://www.googleapis.com/auth/bigquery.readonly` אם הפלטפורמה שלכם מצפה למחרוזת אחת שמופרדת ברווחים, הזינו: `https://www.googleapis.com/auth/geminidataanalytics https://www.googleapis.com/auth/bigquery.readonly`
מזהה לקוח	‫`CLIENT_ID` (מזהה הלקוח ב-OAuth 2.0 שיצרתם בקטע הקודם)
סוד לקוח	‫`CLIENT_SECRET` (סוד הלקוח של OAuth 2.0 שיצרתם בקטע הקודם)

אם מוצגת בקשה, מאמתים את חיבור ה-OAuth בפלטפורמה. כשמסך ההסכמה של Google נפתח, נכנסים לחשבון ומאשרים שהאפליקציה מבקשת גישה לקריאה בלבד גם ל-Gemini Data Analytics וגם ל-BigQuery.
מסנכרנים או טוענים מחדש את הכלים (הפעולות) של חיבור ה-MCP בפלטפורמה, כדי שלקוח ה-MCP יקרא ל-tools/list ב-https://geminidataanalytics.googleapis.com/mcp לייבוא הסכימות של הכלים (כמו list_data_agents,‏ get_data_agent ו-chat), ומוודאים שהכלים המיובאים מופעלים.

הגדרת הוראות להנחיות של הסוכן הראשי

כדי להשתמש בכלי ה-MCP של Conversational Analytics API‏ (list_data_agents,‏ get_data_agent ו-chat), צריך לציין את מזהה הפרויקט ב- Google Cloud ואת המיקום (לדוגמה, projects/PROJECT_ID/locations/LOCATION). בדרך כלל משתמשים עסקיים לא יודעים מהו מזהה הפרויקט ב- Google Cloud שבו מתארחים הסוכנים לאינטראקציה עם נתונים של הארגון, ולכן צריך לציין את מזהה הפרויקט ואת המיקום בהוראות המערכת המותאמות אישית או בהגדרת המיומנות של הסוכן הראשי. כך הנציג הראשי לא יבקש ממשתמשים עסקיים לספק מזהה פרויקט כשהם שואלים שאלה לגבי נתונים.

הוספת הוראות מערכת לחיפוש סוכנים ולניתוב אליהם

מוסיפים את ההוראות הבאות להנחיות המערכת או להוראות בהתאמה אישית של הנציג ברמה הבסיסית, ומחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloudואת LOCATION במיקום המשאב (למשל global,‏ us או eu):

When answering questions about enterprise data using the Conversational
Analytics MCP tools, always use the Google Cloud project ID
"PROJECT_ID" and location "LOCATION" (resource path
"projects/PROJECT_ID/locations/LOCATION"). Do not ask the user to
provide a Google Cloud project ID or location.

To answer a user's data question:
1. Call list_data_agents for "projects/PROJECT_ID/locations/LOCATION"
   to discover the available data agents and review their descriptions.
2. If you need additional context about a candidate agent's connected tables or
   verified queries, call get_data_agent for that agent.
3. Call the chat tool passing parent ("projects/PROJECT_ID/locations/LOCATION"),
   dataAgentContext with the full agent resource name
   ("projects/PROJECT_ID/locations/LOCATION/dataAgents/<var>AGENT_ID</var>"),
   and the user's question in messages.

אימות של סוכנים לאינטראקציה עם נתונים שמגובים ב-Looker

אם הסוכנים לאינטראקציה עם נתונים מתחברים ל-Looker Explores, הבקשות לכלי chat צריכות לכלול בלוק credentials שמכיל את פרטי הכניסה ל-Looker API (מזהה לקוח וסוד לקוח), כי Looker מנהל את האימות בנפרד מ-IAM.

כשמגדירים את הפלטפורמה של הסוכנים לאינטראקציה עם נתונים שמבוססים על Looker, מומלץ לפעול לפי השיטות הבאות:

אל תבקשו ממשתמשים סודות: הגדירו את הנציג ברמה הבסיסית כך שלעולם לא יבקש ממשתמשי קצה להדביק או לספק פרטי כניסה ל-Looker API בצ'אט.
שימוש בחשבון משתמש ייעודי ל-Looker API: יוצרים משתמש ייעודי ל-Looker API עם הרשאות מינימליות שמוגבלות רק למודלים ול-Explores שהסוכן לאינטראקציה עם נתונים צריך.
הזרקת פרטי כניסה מחוץ להקשר של המודל: מגדירים את הפלטפורמה, את תוכנת הביניים של לקוח ה-MCP או את שכבת ה-proxy כך שיזריקו את פרטי הכניסה ל-Looker API למטען הייעודי (payload) של הבקשה של chat בשכבת התעבורה או בשכבת הפעלת הכלים. אל תמקמו את סוד הלקוח בהוראות ההנחיה או בהיסטוריית השיחות של הנציג ברמה הבסיסית (root).

אזהרה: אל תעבירו את השדה clientSecret בהוראות של הנחיית המערכת או בהקשר של השיחה. חשיפת פרטי כניסה בטקסט של הפרומפט ממקמת אותם ישירות בחלון ההקשר של המודל, מה שמגדיל את הסיכון לדליפת סודות דרך יומני שיחות, החדרת פרומפטים או הפלט מהמודל. בכל פעם שאפשר, הגדירו את הפלטפורמה מבוססת הסוכן או את תוכנת הביניים של לקוח ה-MCP כך שיזריקו את הבלוק credentials למטען הייעודי (payload) של קריאת ה-API לכלי באופן אוטומטי מחוץ להקשר של המודל. אם הפלטפורמה שלכם דורשת להגדיר פרטי כניסה ישירות בהנחיות, השתמשו בחשבון משתמש ייעודי של Looker API עם הרשאות לקריאה בלבד בהיקף מוגבל, והחליפו את סוד הלקוח באופן קבוע.

דפוסי הזרקת פרטי כניסה לפלטפורמות של סוכנים

כדי למנוע חשיפה של סודות בחלון ההקשר של המודל, פלטפורמות בדרך כלל מזריקות את פרטי הכניסה ל-Looker באחת מהדרכים הבאות:

יירוט של שרת proxy או תווכה של לקוח MCP: בפלטפורמות שתומכות בתווכה לבקשות, ב-API Gateway או ב-hooks ליירוט כלים, הסוכן ברמה הבסיסית יוצר את קריאת ה-API לכלי chat שמכילה רק את הפרמטרים הסמנטיים (parent,‏ dataAgentContext ו-messages). שכבת התווכה מיירטת את בקשת ה-JSON-RPC היוצאת לפני שהיא מגיעה אל https://geminidataanalytics.googleapis.com/mcp, קוראת את פרטי הכניסה ממאגר סודי מאובטח או ממשתני סביבה, ומאכלסת את האובייקט credentials.
הגדרות של כלים עטופים: במסגרות של סוכנים בהתאמה אישית (כמו ערכת הפיתוח של הסוכן (ADK) או כלי תזמור מותאמים אישית ב-Python), חושפים גרסה עטופה של הכלי chat לסוכן הבסיס, שמשמיטה את הפרמטר credentials מהסכימה של הכלי. ה-execution handler של ה-wrapper מצרף את הבלוק credentials באופן פרוגרמטי מהגדרה מאובטחת, לפני שהוא מעביר את הקריאה לשרת ה-MCP של Conversational Analytics API.

הדוגמה הבאה מציגה את המטען הייעודי (payload) המלא של בקשת JSON-RPC שלקוח ה-MCP שולח לשרת ה-MCP המרוחק בשביל הכלי chat. המודל יוצר את הפרמטרים parent,‏ dataAgentContext ו-messages, אבל הפלטפורמה המארחת או תוכנת הביניים של לקוח ה-MCP מאכלסת את האובייקט credentials לפני שליחת הבקשה:

{
  "parent": "projects/PROJECT_ID/locations/LOCATION",
  "dataAgentContext": {
    "dataAgent": "projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID"
  },
  "credentials": {
    "oauth": {
      "secret": {
        "clientId": "LOOKER_CLIENT_ID",
        "clientSecret": "LOOKER_CLIENT_SECRET"
      }
    }
  },
  "messages": [
    {
      "userMessage": {
        "text": "USER_QUESTION"
      }
    }
  ]
}

מחליפים את ערכי הדוגמה באופן הבא:

‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
‫LOCATION: המיקום של המשאבים של Conversational Analytics API (לדוגמה, global)
‫AGENT_ID: המזהה של הסוכן לאינטראקציה עם נתונים שמגובה ב-Looker
‫LOOKER_CLIENT_ID: מזהה הלקוח של משתמש Looker API
‫LOOKER_CLIENT_SECRET: סוד הלקוח של משתמש Looker API
USER_QUESTION: הפרומפט או השאלה שרוצים לשלוח לסוכן לאינטראקציה עם נתונים

אימות החיבור באמצעות הנחיה לבדיקה

אחרי שמקשרים את חיבור ה-MCP המותאם אישית לאפליקציית הנציג, פותחים את ממשק הצ'אט של הפלטפורמה, מאשרים את סשן המשתמש כשמוצגת בקשה, ושולחים הנחיה לבדיקה כדי לוודא שהנציג הראשי יכול להפעיל את כלי ה-MCP של Conversational Analytics API ולשלוח שאילתות ל-BigQuery באמצעות פרטי הכניסה שהוקצו.

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

What are the top 5 selling products in projects/PROJECT_ID/locations/LOCATION using the public dataset bigquery-public-data.iowa_liquor_sales.sales?

אתם יכולים גם להורות במפורש לסוכן הבסיס להפעיל את הכלי chat ממחבר ה-MCP‏ (CONNECTOR_NAME):

Use the chat tool from CONNECTOR_NAME to find the top 5 selling products in projects/PROJECT_ID/locations/LOCATION using the public dataset bigquery-public-data.iowa_liquor_sales.sales.