1. מבוא
ב-Codelab הזה תלמדו איך ליצור סוכן AI עם קוד מקצועי באמצעות הערכה לפיתוח סוכנים (ADK) שמתחברת ישירות לשרתי ה-MCP הרשמיים של Google Workspace.
Model Context Protocol (MCP) הוא תקן פתוח שמאפשר למודלים של AI להשתמש בצורה מאובטחת בכלים שמסופקים על ידי שרתים מרוחקים. ADK הוא מסגרת של Google לפיתוח סוכנים אוטונומיים באמצעות קוד. כשמשלבים אותם, אפשר ליצור סוכנים בהתאמה אישית גבוהה שמבוססים על הנתונים שלכם ב-Gmail, ב-Google Drive, ביומן Google, ב-Google Chat ובאנשי הקשר.
במאמר הגדרת שרתי MCP של Google Workspace מפורט מידע מלא על הכלים וההגדרות הזמינים.
הפעולות שתבצעו:
- מפעילים את שירותי Google Workspace MCP בפרויקט ב-Google Cloud.
- מגדירים את ההסכמה של OAuth ויוצרים פרטי כניסה לבדיקה מקומית ולפריסה בסביבת הייצור.
- יוצרים סוכן ADK מקומי שמתחבר לשרתי MCP של Google Workspace באמצעות אסימונים סטטיים.
- מפתחים ופורסים סוכן ADK שמוכן לייצור ב-Gemini Enterprise Agent Platform (GEAP) Agent Runtime שמשתמש בהזרקת טוקנים דינמית.
- רושמים ובודקים את הסוכן המותאם אישית באופן מקורי ב-Gemini Enterprise.
הדרישות
- דפדפן אינטרנט (למשל, Chrome).
- פרויקט ב-Google Cloud עם חיוב מופעל.
- חשבון Google Workspace (עם תכונות חכמות מופעלות).
- Python 3.11 ואילך מותקן במחשב המקומי.
- Google Cloud CLI (
gcloud) מותקן ומופעל.
2. לפני שמתחילים
יצירה או בחירה של פרויקט ב-Google Cloud
אפשרות במסוף
במסוף Google Cloud, בוחרים פרויקט קיים או יוצרים פרויקט חדש ב-Google Cloud.
אפשרות CLI
יוצרים פרויקט חדש ומגדירים אותו כפעיל:
gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID
הפעלת ממשקי ה-API
כדי להשתמש בשרתי MCP של Google Workspace, צריך להפעיל גם את ממשקי ה-API הרגילים של Google Workspace וגם את שירותי ה-MCP הייעודיים.
אפשרות במסוף
כדי להפעיל אותם באמצעות דפדפן האינטרנט, לוחצים על הכפתורים הבאים:
אפשרות CLI מריצים את הפקודות הבאות בטרמינל:
# Enable standard GWS APIs
gcloud services enable chat.googleapis.com \
drive.googleapis.com \
calendar-json.googleapis.com \
people.googleapis.com \
gmail.googleapis.com
# Enable dedicated MCP services
gcloud services enable calendarmcp.googleapis.com \
chatmcp.googleapis.com \
drivemcp.googleapis.com \
gmailmcp.googleapis.com \
workspacemcp.googleapis.com
הגדרת האפליקציה ל-Chat
כדי להשתמש בשרת MCP של Google Chat, צריך להגדיר אפליקציה ל-Chat בפרויקט בענן של Google.
- במסוף Google Cloud, מחפשים את Google Chat API ולוחצים על Google Chat API > ניהול > הגדרה.
- מגדירים את האפליקציה ל-Chat:
- שם האפליקציה:
ADK Workspace Agent - כתובת ה-URL של הדמות:
https://developers.google.com/chat/images/quickstart-app-avatar.png - תיאור:
MCP server connection for ADK Agent - בקטע פונקציונליות, משביתים את האפשרות הפעלת תכונות אינטראקטיביות.
- בקטע Logs, בוחרים באפשרות Log errors to Logging.
- שם האפליקציה:
- לוחצים על שמירה.
3. הגדרת הסכמה ולקוחות ב-OAuth
שרתי ה-MCP של Google Workspace משתמשים ב-OAuth 2.0 לאימות מאובטח. צריך להגדיר את מסך ההסכמה ל-OAuth וליצור שני מזהי לקוח נפרדים: אחד לפיתוח מקומי ואחד לסוכן שנפרס.
הגדרת מסך ההסכמה ל-OAuth
- בפינה הימנית העליונה של מסוף Google Cloud, לוחצים על תפריט הניווט (סמל ההמבורגר). בוחרים באפשרות פלטפורמת האימות של Google > מיתוג (או ממשקי API ושירותים > מסך הסכמה ל-OAuth אם פלטפורמת האימות של Google לא מוצגת).
- מגדירים את פרטי האפליקציה:
- שם האפליקציה:
Workspace ADK Agent - כתובת אימייל לתמיכה במשתמשים: בוחרים את כתובת האימייל שלכם.
- שם האפליקציה:
- מגדירים את Audience: בוחרים באפשרות Internal.
- מגדירים את Contact Information: מזינים את כתובת האימייל ולוחצים על Create.
- עוברים אל גישה לנתונים > הוספה או הסרה של היקפים. בקטע הוספה ידנית של היקפי הרשאות, מוסיפים את היקפי ההרשאות הבאים כדי לתת גישה לשירותים הנדרשים:
https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.calendars https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/chat.spaces https://www.googleapis.com/auth/chat.messages https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive.file https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.compose https://www.googleapis.com/auth/directory.readonly https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/contacts.readonly https://www.googleapis.com/auth/cloud-platform - לוחצים על הוספה לטבלה, אחר כך על עדכון ולבסוף על שמירה.
יצירת מזהה לקוח לפיתוח מקומי (אפליקציה למחשב)
כשמגדירים לקוח OAuth 2.0 לשרתי MCP של Google Workspace, צריך להפעיל את הגדרת הסיווג כסוכני (is_agentic) על ידי בחירה באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI. לקוחות OAuth שלא הפעילו את ההגדרה הזו לא יכולים לשלוח קריאות לנקודות קצה של MCP ב-Google Workspace.
- במסוף Google Cloud, נכנסים אל פלטפורמת האימות של Google > לקוחות (או ממשקי API ושירותים > פרטי כניסה). לוחצים על Create Client (או על Create Credentials ואז על OAuth client ID).
- בוחרים באפשרות אפליקציה למחשב כסוג האפליקציה.
- נותנים לו את השם
Workspace Agent Local. - בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI כדי להפעיל את דגל הסיווג
is_agenticבלקוח OAuth. - לוחצים על Create ומורידים את קובץ ה-JSON. שומרים אותו באופן מקומי בתור
client_secret.json.
4. פיתוח ובדיקה של סוכנים
בקטע הזה מוסבר איך ליצור את סביבת הנציג. אנחנו נשתמש בגישה של טוקן סטטי לבדיקה, שבה אנחנו מאחזרים טוקן OAuth באמצעות gcloud ומעבירים אותו אל McpToolset של ADK. אתם יכולים לבצע את השלבים הבאים באמצעות המכונה המקומית או Google Cloud Shell.
בוחרים את הסביבה: מכונה מקומית או Google Cloud Shell כדי להגדיר את סביבת הפיתוח. בשתי השיטות נעשה שימוש בסקריפט Python משותף לאימות, כדי להבטיח עקביות בין הפלטפורמות.
1. הגדרת ספריית הסביבה
מריצים את הפקודות הבאות בטרמינל כדי ליצור ספריית פרויקט ולהתקין את החבילות הנדרשות.
- ב-Google Cloud Shell: קודם לוחצים על הסמל Activate Cloud Shell (
>_) בסרגל הכלים שבפינה הימנית העליונה של מסוף Google Cloud. - במחשב מקומי: פותחים את הטרמינל הרגיל.
mkdir -p gws-adk-agent/workspace_agent
cd gws-adk-agent
python3 -m venv .venv
source .venv/bin/activate
pip install google-adk poetry google-auth-oauthlib
2. הכנת קובץ פרטי הכניסה
צריך להציב את הקובץ client_secret.json שהורדתם בשלב הקודם בתיקיית השורש של gws-adk-agent.
- מחשב מקומי: מעבירים או מעתיקים את קובץ ה-
client_secret.jsonשהורדתם לספרייהgws-adk-agent. - Google Cloud Shell: כדי ליצור את הקובץ, מריצים את הפקודה הבאה ב-Cloud Shell (מחליפים את
[PASTE_JSON_HERE]בתוכן ה-JSON בפועל):
cat << 'EOF' > client_secret.json
[PASTE_JSON_HERE]
EOF
3. אימות ויצירת .env (auth.py)
כדי לטפל באימות באופן עקבי ולמנוע בעיות בניתוב של ה-CLI שספציפיות לסביבה, אנחנו משתמשים בסקריפט Python בהתאמה אישית שמופעל על ידי ספריות האימות הרשמיות של Google. הסקריפט הזה מנהל את תהליך ה-OAuth, שומר את Application Default Credentials (ADC) באופן מקומי ויוצר את הקובץ .env הנדרש.
יוצרים קובץ בשם auth.py בספרייה gws-adk-agent ומוסיפים את הקוד הבא:
import json
import os
from urllib.parse import urlparse, parse_qs
import google.auth
from google_auth_oauthlib.flow import InstalledAppFlow
CLIENT_SECRET_FILE = 'client_secret.json'
SCOPES = [
"https://www.googleapis.com/auth/cloud-platform",
"https://www.googleapis.com/auth/calendar",
"https://www.googleapis.com/auth/chat.spaces.readonly",
"https://www.googleapis.com/auth/chat.messages",
"https://www.googleapis.com/auth/drive.readonly",
"https://www.googleapis.com/auth/gmail.readonly",
"https://www.googleapis.com/auth/gmail.compose",
"https://www.googleapis.com/auth/directory.readonly",
"https://www.googleapis.com/auth/contacts.readonly"
]
# Initialize the flow from the client secrets JSON
flow = InstalledAppFlow.from_client_secrets_file(
CLIENT_SECRET_FILE,
scopes=SCOPES,
redirect_uri='http://localhost:8085/'
)
# Generate the Auth URL
auth_url, expected_state = flow.authorization_url(prompt='consent', access_type='offline')
print("\n=== GOOGLE OAUTH OFFICIAL LIBRARY FLOW ===")
print("1. Copy the following link and paste it into your browser (or click it if supported):\n")
print(auth_url)
print("\n2. Authorize the application.")
print("3. Your browser will redirect to a 'localhost' page (it will show a 'Site can't be reached' error, which is EXPECTED and normal).")
print("4. Copy the ENTIRE URL from your browser's address bar (including the http://localhost:8085/ part).\n")
# Get the redirected URL from the user
redirected_url = input("Paste the full localhost URL here: ").strip()
# Exchange the redirect URL for tokens
print("\nExchanging code for tokens...")
try:
parsed_url = urlparse(redirected_url)
query_params = parse_qs(parsed_url.query)
returned_state = query_params.get('state', [None])[0]
code = query_params.get('code', [None])[0]
if not code:
raise ValueError("No 'code' parameter found in the URL.")
if returned_state != expected_state:
raise ValueError("CSRF Warning! State mismatch.")
flow.fetch_token(code=code)
creds = flow.credentials
except Exception as e:
print(f"Authentication failed: {e}")
exit(1)
if not creds.refresh_token:
print("\nError: No refresh token returned. You may need to revoke access and try again.")
exit(1)
# Save Application Default Credentials
adc_data = {
"client_id": creds.client_id,
"client_secret": creds.client_secret,
"refresh_token": creds.refresh_token,
"type": "authorized_user"
}
adc_dir = os.path.expanduser("~/.config/gcloud")
os.makedirs(adc_dir, exist_ok=True)
adc_path = os.path.join(adc_dir, "application_default_credentials.json")
with open(adc_path, "w") as f:
json.dump(adc_data, f, indent=2)
# Detect Project ID
try:
_, project_id = google.auth.default()
except Exception:
project_id = None
project_id = project_id or os.environ.get("GOOGLE_CLOUD_PROJECT", "YOUR_PROJECT_ID")
# Save to .env for local development (relative to project root)
env_dir = "workspace_agent"
os.makedirs(env_dir, exist_ok=True)
env_path = os.path.join(env_dir, ".env")
with open(env_path, "w") as f:
f.write("GOOGLE_GENAI_USE_VERTEXAI=1\n")
f.write(f"GOOGLE_CLOUD_PROJECT={project_id}\n")
f.write("GOOGLE_CLOUD_LOCATION=us-central1\n")
print(f"\nSuccess! Application Default Credentials saved to: {adc_path}")
print(f"Environment variables saved to: {env_path}")
if project_id == "YOUR_PROJECT_ID":
print("NOTE: Could not automatically detect Project ID. Please update it manually in .env")
מריצים את הסקריפט בטרמינל:
python3 auth.py
יצירת קוד הסוכן
לא משנה באיזו סביבה בחרתם בשלב הקודם, הקוד של הנציג נשאר בדיוק אותו דבר. יוצרים קובץ בשם agent.py בתוך תת-הספרייה workspace_agent שיצרתם קודם, ומוסיפים את הקוד הבא. הסקריפט הזה משתמש ב-Application Default Credentials (ADC) כדי לספק הרשאה, לאמת באופן אוטומטי ולרענן את פרטי הכניסה בזיכרון בלבד באמצעות ספק כותרות דינמי.
import os
import datetime
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
# Enable graceful error handling so timeouts return as tool outputs instead of crashing
os.environ["ADK_ENABLE_MCP_GRACEFUL_ERROR_HANDLING"] = "1"
MODEL = "gemini-2.5-flash"
# Inject User ADC path globally so both ADK and underlying GenAI SDKs
# load it safely, bypassing broken Compute Engine metadata fallbacks.
_adc_path = os.path.expanduser(
"~/.config/gcloud/application_default_credentials.json"
)
if not os.path.exists(_adc_path):
raise FileNotFoundError(
f"User ADC not found at {_adc_path}. "
"Please run 'python3 auth.py' first to generate credentials."
)
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = _adc_path
creds, _ = google.auth.default()
class TokenRelay:
"""Manages in-memory caching of Google OAuth access tokens.
Decouples token refresh logic from credentials validation states to
prevent infinite refresh loops during automated tool retries.
"""
def __init__(self, credentials):
self._creds = credentials
self._cached_token: str | None = None
self._expiry: datetime.datetime | None = None
def get_token(self) -> str:
now = datetime.datetime.now()
# Refresh if no cache or expiring within 5 minutes
if (
self._cached_token is None
or self._expiry is None
or now >= (self._expiry - datetime.timedelta(minutes=5))
):
self._creds.refresh(Request())
self._cached_token = self._creds.token
# Token lives for 60 mins; cache for 50 mins safely
self._expiry = now + datetime.timedelta(minutes=50)
print("\n[Agent Runtime] Access token refreshed from ADC.")
return self._cached_token or ""
# Initialize auth relay and perform startup safety check
token_relay = TokenRelay(creds)
token_relay.get_token()
def auth_header_provider(tool_context=None) -> dict[str, str]:
return {"Authorization": f"Bearer {token_relay.get_token()}"}
# Initialize the Google Workspace MCP servers with dynamic runtime provider
calendar_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://calendarmcp.googleapis.com/mcp/v1",
),
header_provider=auth_header_provider
)
chat_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://chatmcp.googleapis.com/mcp/v1",
),
header_provider=auth_header_provider
)
drive_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://drivemcp.googleapis.com/mcp/v1",
),
header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://gmailmcp.googleapis.com/mcp/v1",
),
header_provider=auth_header_provider
)
people_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://people.googleapis.com/mcp/v1",
),
header_provider=auth_header_provider
)
universal_search_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://workspacemcp.googleapis.com/mcp/v1",
),
header_provider=auth_header_provider
)
current_date = datetime.datetime.now().strftime("%Y-%m-%d")
# Define the agent and attach all configured toolsets
root_agent = LlmAgent(
model=MODEL,
name='gws_adk_agent',
instruction=f"""You are a helpful assistant grounded in the user's Google Workspace data.
Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
Use the provided MCP tools to answer questions about their Calendar, Chat, Drive, Gmail, Contacts, and perform Universal Search.
If a tool returns an error indicating a timeout, inform the user that the service took too long to respond.""",
tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp, universal_search_mcp]
)
הרצה ובדיקה של הנציג
אתם יכולים לנהל אינטראקציה עם הנציג באמצעות ממשק המשתמש האינטראקטיבי באינטרנט או ישירות בתוך הטרמינל או המעטפת.
אפשרות 1: ממשק משתמש אינטראקטיבי באינטרנט
אם אתם משתמשים במכונה מקומית:
- מתיקיית השורש של הפרויקט ב-
gws-adk-agent, מפעילים את ממשק האינטרנט של ADK:adk web - כדי לדבר עם הנציג, פותחים את
http://localhost:8000בדפדפן.
אם אתם ב-Google Cloud Shell:
- מתיקיית השורש של הפרויקט ב-
gws-adk-agent, מפעילים את ממשק האינטרנט של ADK ואוכפים באופן מפורש את יציאה 8080:adk web --port 8080 --allow_origins=* - לוחצים על הלחצן Web Preview בפינה הימנית העליונה של סרגל הכלים של Cloud Shell ובוחרים באפשרות Preview on port 8080 כדי לפתוח את הממשק בכרטיסייה חדשה.
אפשרות 2: מצב CLI בטרמינל (חלופה)
אם אתם מעדיפים להישאר בטרמינל או לא רוצים להגדיר תצוגות מקדימות בדפדפן אינטרנט, ADK מספק מצב צ'אט REPL אינטראקטיבי מקורי.
מתיקיית השורש של הפרויקט ב-gws-adk-agent, מריצים את הפקודה הבאה (היא פועלת באופן זהה במכונה מקומית וב-Google Cloud Shell):
adk run workspace_agent
תיכנסו לשיחת צ'אט אינטראקטיבית ישירות במעטפת:
Running agent gws_adk_agent, type exit to exit.
[user]:
נסו לתת הנחיה לסוכן שלכם
לא משנה באיזה ממשק בחרתם, נסו לבדוק את הנציג באמצעות שאילתות שמשתמשות בכלי ה-MCP של Workspace:
What are my upcoming meetings this week?
Summarize the last 3 unread emails in my Gmail.
5. פריסה בסביבת הייצור
כדי לפרוס את הנציג בסביבת הייצור, אי אפשר להשתמש באסימון מקומי בתוך הקוד. במקום זאת, אנחנו משתמשים ב-header_provider של ADK כדי לחלץ באופן דינמי את טוקן הגישה של OAuth שפלטפורמת Gemini Enterprise מוסיפה כשהמשתמש יוצר אינטראקציה עם הסוכן.
יצירת קוד הסוכן בסביבת הייצור
יוצרים חבילת ספרייה בשם enterprise_ai ויוצרים קובץ agent.py בתוכה:
mkdir -p enterprise_ai
כתוב את התוכן הבא ב-enterprise_ai/agent.py:
import os
import datetime
import re
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext
# Enable graceful error handling so timeouts return as tool outputs instead of crashing
os.environ["ADK_ENABLE_MCP_GRACEFUL_ERROR_HANDLING"] = "1"
MODEL = "gemini-2.5-flash"
# This name MUST match the Authorization Name used during Gemini Enterprise registration
CLIENT_AUTH_NAME = "workspace-adk-auth"
def _get_access_token_from_context(tool_context: ToolContext) -> str:
"""Dynamically parses the user bearer token injected into the ToolContext state."""
escaped_name = re.escape(CLIENT_AUTH_NAME)
pattern = re.compile(fr"^{escaped_name}_\d+$")
state_dict = tool_context.state.to_dict() if hasattr(tool_context.state, 'to_dict') else tool_context.state
matching_keys = [k for k in state_dict.keys() if pattern.match(k)]
if matching_keys:
return state_dict.get(matching_keys[0])
raise Exception(f"No bearer token found in ToolContext state matching pattern {pattern.pattern}")
def auth_header_provider(tool_context: ToolContext) -> dict[str, str]:
"""Provides the dynamic Authorization header for MCP requests."""
token = _get_access_token_from_context(tool_context)
return {"Authorization": f"Bearer {token}"}
# Initialize toolsets using the dynamic header_provider
calendar_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://calendarmcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
chat_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://chatmcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
drive_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://drivemcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://gmailmcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
people_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://people.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
universal_search_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(url="https://workspacemcp.googleapis.com/mcp/v1"),
header_provider=auth_header_provider
)
current_date = datetime.datetime.now().strftime("%Y-%m-%d")
root_agent = LlmAgent(
model=MODEL,
name='enterprise_ai',
instruction=f"""You are an enterprise assistant grounded securely in the user's Workspace data.
Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
Always use the provided MCP tools to fetch context from Calendar, Chat, Drive, Gmail, People, and search for information across multiple Google Workspace products.
If a tool returns an error indicating a timeout, inform the user that the service took too long to respond.""",
tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp, universal_search_mcp]
)
פריסה ב-GEAP Agent Runtime
פורסים את הסוכן עם תכנות מלא באמצעות ADK CLI:
adk deploy agent_engine \
--project=$(gcloud config get-value project) \
--region=us-central1 \
--display_name="Workspace ADK Agent" \
enterprise_ai
מחכים שהפריסה תסתיים ומעתיקים את שם המשאב של מנוע החשיבה הרציונלית שנוצר מהפלט של הטרמינל (למשל, projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID).
6. הרשמה ל-Gemini Enterprise
עכשיו אנחנו מוסיפים את הסוכן המותאם אישית של ADK ל-Gemini Enterprise כדי שהמשתמשים יוכלו לדבר איתו באופן טבעי.
יצירת מזהה לקוח לסביבת הייצור (אפליקציית אינטרנט)
כדי לפרוס את הנציג בסביבת הייצור, צריך ליצור מזהה לקוח של אפליקציית אינטרנט. בניגוד ללקוח של אפליקציה למחשב שמשמש לבדיקה מקומית, לקוח של אפליקציית אינטרנט מאפשר תהליך OAuth מאובטח בצד השרת. כך הסוכן שמתארח ב-GEAP Agent Runtime יכול לקבל באופן מאובטח את אסימוני האימות של המשתמש שמועברים על ידי Gemini Enterprise, באמצעות כתובת ה-URI להפניה אוטומטית שצוינה. ההגדרה הזו נדרשת כדי שהסוכן יוכל לגשת באופן מאובטח לנתוני Google Workspace בשם המשתמש בסביבת ייצור.
- בפינה הימנית העליונה של מסוף Google Cloud, לוחצים על תפריט הניווט (סמל ההמבורגר). בוחרים באפשרות פלטפורמת האימות של Google > לקוחות (או ממשקי API ושירותים > פרטי כניסה אם פלטפורמת האימות של Google לא מוצגת). לוחצים על Create Client (או על Create Credentials ואז על OAuth client ID).
- בוחרים באפשרות אפליקציית אינטרנט בתור סוג האפליקציה.
- נותנים לו את השם
Workspace Agent Production. - בקטע Authorized redirect URIs, מוסיפים את מזהי ה-URI הבאים:
- לוחצים על Add URI ומזינים את
https://vertexaisearch.cloud.google.com/oauth-redirect. - לוחצים שוב על Add URI ומזינים את
https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
- לוחצים על Add URI ומזינים את
- בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI כדי להפעיל את דגל הסיווג
is_agenticבלקוח OAuth. - לוחצים על יצירה. בתיבת הדו-שיח "OAuth client created" (או מהרשימה Clients), מעתיקים את Client ID ואת Client Secret. תצטרכו את הפרטים האלה כשתרשמו את הסוכן ב-Gemini Enterprise.
יצירת אפליקציית Gemini Enterprise
- נכנסים לדף Gemini Enterprise במסוף Google Cloud:
- בכרטיס Gemini Enterprise, לוחצים על ניהול.
- לוחצים על יצירת אפליקציה.
- בקטע Gemini Enterprise, לוחצים על יצירה.
- בשדה שם האפליקציה, מזינים שם לאפליקציה. מזהה האפליקציה מופיע מתחת לשם האפליקציה.
- בשדה השם החיצוני של החברה או הארגון, מזינים את שם החברה או הארגון. במדריך הזה אפשר להשתמש ב-
Cymbal Bank. - בוחרים באפשרות global (Global) בתור המיקום של האפליקציה.
- לוחצים על המשך.
רישום הסוכן בהתאמה אישית
- פותחים את מסוף Gemini Enterprise:
- בוחרים את האפליקציה הפעילה, עוברים אל נציגים ולוחצים על + הוספת נציג > הוספת נציג בהתאמה אישית באמצעות Agent Runtime.
- בקטע הרשאות, לוחצים על הוספת הרשאה:
- שם ההרשאה:
workspace-adk-auth(חייב להיות התאמה מדויקת ל-CLIENT_AUTH_NAME בקוד Python) - מזהה לקוח: מדביקים את מזהה הלקוח של אפליקציית האינטרנט בסביבת הייצור שיצרתם למעלה.
- סוד לקוח: מדביקים את סוד הלקוח של אפליקציית האינטרנט בסביבת הייצור שיצרתם למעלה.
- URI של טוקן:
https://oauth2.googleapis.com/token - Authorization URI: יוצרים את ה-URI על ידי החלפת
YOUR_CLIENT_IDב-Client ID שהעתקתם בשלב 5 שלמעלה:https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.events%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.calendars%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.spaces%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.messages%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.file%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.compose%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdirectory.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcontacts.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
- שם ההרשאה:
- לוחצים על סיום ואז על הבא.
- בקטע הגדרה:
- שם הנציג/ה:
Workspace Pro Agent - תיאור:
Use this agent to answer questions about your Google Workspace data, including Gmail, Google Drive, Google Calendar, Google Chat, and Contacts. It can find files, summarize emails, check your schedule, and look up contact information. - Agent Runtime reasoning engine: מדביקים את שם המשאב של מנוע חשיבה רציונלית שהעתקתם מהפלט של
adk deploy.
- שם הנציג/ה:
- לוחצים על יצירה.
כדאי לנסות את הסוכן ב-Gemini Enterprise
אתם יכולים לתקשר עם הנציג באמצעות גרסת טרום-השקה (Preview) של מסוף Google Cloud (הדרך הכי מהירה למפתחים) או אפליקציית האינטרנט של Gemini Enterprise (חוויית משתמש קצה).
אפשרות 1: גרסת טרום-השקה (Preview) של מסוף Google Cloud
- נכנסים לדף Gemini Enterprise במסוף Google Cloud:
- בתפריט הניווט, לוחצים על Apps ובוחרים את האפליקציה שיצרתם.
- לוחצים על תצוגה מקדימה או על פתיחת התצוגה המקדימה בפינה השמאלית העליונה.
- בשורת החיפוש, מזינים את השאילתה הבאה:
Search for files in Drive related to 'Project Milestone', summarize them, and tell me if I have any meetings with the project owner today. - מקישים על Enter כדי לשלוח את השאילתה ולראות את התוצאות ישירות במסוף.
אפשרות 2: אתר Gemini Enterprise
- פותחים את הממשק של Gemini Enterprise בדפדפן.
- עוברים אל תפריט ☰ > נציגים ובוחרים באפשרות Workspace Pro Agent בקטע מהארגון שלך.
- מקלידים את אותה שאילתה כמו באפשרות Preview במסוף Google Cloud.
- לוחצים על Authorize כשמוצגת בקשה לעבור את תהליך ההסכמה מהמשתמש ב-OAuth.
- הסוכן יבצע משימות בצורה חלקה בכמה שירותים באמצעות פרוטוקול MCP.
7. הסרת המשאבים
כדי להימנע מחיובים מיותרים, נקו את המשאבים:
אפשרות מסוף
עוברים אל API & Services Dashboard, בוחרים את שירותי ה-MCP שהפעלתם (למשל, Calendar MCP, Gmail MCP) ולוחצים על Disable API. מוחקים את מזהי הלקוחות ב-OAuth בקטע פלטפורמת האימות של Google > לקוחות, ומוחקים את פריסת מנוע החשיבה הרציונלית ממסוף Gemini Enterprise.
אפשרות CLI
מריצים את פקודות הטרמינל הבאות כדי להשבית את שירותי ה-MCP:
# Disable Workspace MCP services
gcloud services disable calendarmcp.googleapis.com \
chatmcp.googleapis.com \
drivemcp.googleapis.com \
gmailmcp.googleapis.com \
workspacemcp.googleapis.com
8. מזל טוב
מעולה! יצרתם, בדקתם ופרסתם בהצלחה סוכן AI ב-ADK עם קוד מקצועי שמחובר ישירות לשרתי ה-MCP הרשמיים של Google Workspace.
מה למדתם
- איך מפעילים את שירותי Google Workspace MCP ב-Google Cloud.
- איך לטפל בפרטי הכניסה ל-OAuth לבדיקת ADK מקומית באמצעות כותרות סטטיות.
- איך מטמיעים הזרקת טוקנים דינמית באמצעות
header_providerלסוכנים בסביבת הייצור. - איך פורסים סוכן ADK ב-GEAP Agent Runtime ורושמים אותו ב-Gemini Enterprise.