Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

יצירת סוכן AI ל-Google Workspace באמצעות ADK ו-MCP

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 מקומי שמתחבר ל-5 שרתי MCP של Workspace באמצעות טוקנים סטטיים.
פיתוח ופריסה של סוכן ADK מוכן לייצור ב-Gemini Enterprise Agent Platform (GEAP) Agent Runtime שמשתמש בהזרקת טוקנים דינמית.
אפשר לרשום ולבדוק את סוכן ה-AI המותאם אישית באופן מקורי ב-Gemini Enterprise.

הדרישות

דפדפן אינטרנט (לדוגמה, Chrome).
פרויקט ב-Google Cloud שהחיוב בו מופעל.
חשבון Google Workspace (עם התכונות החכמות מופעלות).
‫Python 3.11 ואילך מותקן במחשב המקומי.
‫Google Cloud CLI (gcloud) מותקן ומאותחל.

‫2. לפני שמתחילים

יצירה או בחירה של פרויקט ב-Google Cloud

אפשרות Console

ב-מסוף 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 הייעודיים.

אפשרות Console

כדי להפעיל אותם באמצעות דפדפן האינטרנט, לוחצים על הלחצנים הבאים:

אפשרות 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

הגדרת אפליקציית Chat

כדי להשתמש בשרת ה-MCP של Google Chat, צריך להגדיר אפליקציית Chat בפרויקט בענן שלכם ב-Google.

עוברים אל Google Chat API > Manage (ניהול) > Configuration (הגדרה).
הגדרת אפליקציית Chat:
- שם האפליקציה: ADK Workspace Agent
- כתובת ה-URL של האווטאר: https://developers.google.com/chat/images/quickstart-app-avatar.png
- תיאור: MCP server connection for ADK Agent
- בקטע פונקציונליות, משביתים את האפשרות הפעלת תכונות אינטראקטיביות.
- בקטע יומנים, בוחרים באפשרות רישום שגיאות ביומן.
לוחצים על שמירה.

3. הגדרת הסכמה ולקוחות OAuth

שרתי ה-MCP של Google Workspace משתמשים ב-OAuth 2.0 לאימות מאובטח. צריך להגדיר את מסך הסכמה ל-OAuth וליצור שני מזהי לקוח נפרדים: אחד לפיתוח מקומי ואחד לסוכן שנפרס.

ב-מסוף Google Cloud, לוחצים על תפריט הניווט (סמל ההמבורגר) בפינה הימנית העליונה. בוחרים באפשרות Google Auth Platform (פלטפורמת אימות Google) > Branding (מיתוג) (או באפשרות APIs & Services (ממשקי API ושירותים) > OAuth consent screen (מסך הסכמה ל-OAuth) אם Google Auth Platform לא מוצגת).
הגדרת פרטי האפליקציה:
- שם האפליקציה: Workspace ADK Agent
- User support email (כתובת אימייל לתמיכה במשתמשים): בוחרים את כתובת האימייל.
מגדירים את הקהל: בוחרים באפשרות פנימי.
מגדירים את הפרטים ליצירת קשר: מזינים את כתובת האימייל ולוחצים על יצירה.

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

https://www.googleapis.com/auth/calendar.calendarlist.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.calendars
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/gmail.send
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

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

יצירת מזהה לקוח לפיתוח מקומי (אפליקציה למחשב)

במסוף Google Cloud, עוברים אל Google Auth Platform > Clients (או אל APIs & Services > Credentials). לוחצים על Create Credentials (יצירת פרטי כניסה) או על Create Client (יצירת לקוח) ובוחרים באפשרות OAuth client ID (מזהה לקוח OAuth).
בוחרים באפשרות אפליקציה למחשב כסוג האפליקציה.
נותנים לו את השם Workspace Agent Local.
לוחצים על Create ומורידים את קובץ ה-JSON. שומרים אותו באופן מקומי כ-client_secret.json.

4. פיתוח ובדיקה של סוכנים

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

בוחרים את הסביבה: מחשב מקומי או Google Cloud Shell כדי להגדיר את סביבת הפיתוח. שתי השיטות ישתמשו בסקריפט Python משותף לאימות, כדי להבטיח עקביות בין הפלטפורמות.

1. הגדרת ספריית סביבה

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

ב-Google Cloud Shell: קודם לוחצים על הסמל Activate Cloud Shell (הפעלת 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 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

MODEL = "gemini-2.5-flash"

# Load credentials from Application Default Credentials (ADC) saved by auth.py
creds, _ = google.auth.default()

# 1. STARTUP SAFETY: Ensure valid token at import time for static tool discovery (e.g. adk web UI load)
if not creds.valid:
    creds.refresh(Request())
    print("\n[Agent Startup] Access token refreshed from ADC.")

def auth_header_provider(tool_context=None) -> dict[str, str]:
    """2. RUNTIME SAFETY: Dynamically provides auth headers, refreshing if expired during the session."""
    if not creds.valid:
        creds.refresh(Request())
        print("\n[Agent Runtime] Access token refreshed from ADC.")
    return {"Authorization": f"Bearer {creds.token}"}

# Initialize the 5 GWS MCP servers with combined startup headers and dynamic runtime provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://calendarmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://chatmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://drivemcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://gmailmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://people.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)

current_date = datetime.datetime.now().strftime("%Y-%m-%d")

# Define the agent and attach all 5 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, and Contacts.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_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 (תצוגה מקדימה ביציאה 8080) כדי לפתוח את הממשק בכרטיסייה חדשה.

אפשרות 2: מצב Terminal 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 datetime
import os
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

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
)

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, and People.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

פריסה לזמן ריצה של סוכן GEAP

פורסים את הסוכן עם קוד מקצועי באמצעות ADK CLI:

adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Workspace ADK Agent" \
  enterprise_ai

מחכים שהפריסה תסתיים ומעתיקים את שם המשאב של Reasoning Engine שנוצר מפלט הטרמינל (למשל, 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 Credentials (יצירת פרטי כניסה) או על Create Client (יצירת לקוח) ובוחרים באפשרות OAuth client ID (מזהה לקוח OAuth).
בוחרים באפשרות Web application (אפליקציית אינטרנט) כסוג האפליקציה.
נותנים לו את השם Workspace Agent Production.
בקטע Authorized redirect URIs, מוסיפים את כתובות ה-URI הבאות:
- לוחצים על הוספת URI ומזינים את https://vertexaisearch.cloud.google.com/oauth-redirect.
- לוחצים שוב על הוספת URI ומזינים https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
לוחצים על יצירה. בחלון הקופץ 'נוצר לקוח OAuth' (או מרשימת הלקוחות), מעתיקים את מזהה הלקוח ואת סוד הלקוח. תצטרכו את הפרטים האלה כשתרשמו את הסוכן ב-Gemini Enterprise.

יצירת אפליקציית Gemini Enterprise

במסוף Google Cloud, עוברים לדף Gemini Enterprise:

‫

בכרטיס Gemini Enterprise, לוחצים על ניהול.
לוחצים על יצירת אפליקציה.
בקטע Gemini Enterprise, לוחצים על יצירה.
בשדה Your app name (שם האפליקציה שלך), מזינים שם לאפליקציה. מזהה האפליקציה מופיע מתחת לשם האפליקציה.
בשדה השם החיצוני של החברה או הארגון, מזינים את שם החברה או הארגון. במדריך הזה אפשר להשתמש ב-Cymbal Bank.
בוחרים באפשרות גלובלי (Global) כמיקום של האפליקציה.
לוחצים על המשך.

רישום הסוכן המותאם אישית

פותחים את מסוף Gemini Enterprise:

בוחרים את האפליקציה הפעילה, עוברים אל סוכנים ולוחצים על + הוספת סוכן > הוספת סוכן מותאם אישית באמצעות Agent Runtime.

בקטע הרשאות, לוחצים על הוספת הרשאה:

שם ההרשאה: workspace-adk-auth (חייב להיות זהה ל-CLIENT_AUTH_NAME בקוד Python)
Client ID (מזהה לקוח): מדביקים את מזהה הלקוח של אפליקציית האינטרנט של הסביבה הפרודקטיבית שנוצר בשלב הקודם.
סוד לקוח: מדביקים את סוד הלקוח של אפליקציית האינטרנט של הסביבה הפעילה שנוצר בשלב הקודם.
Token URI: https://oauth2.googleapis.com/token

Authorization URI: יוצרים את ה-URI על ידי החלפת YOUR_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.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.calendars%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.events%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.send%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.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%2Fdirectory.readonly&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

לוחצים על סיום ואז על הבא.

בקטע Configuration (הגדרה):

שם הסוכן: 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?

אתם יכולים ליצור אינטראקציה עם הסוכן באמצעות גרסת טרום-ההשקה של מסוף Google Cloud (האפשרות המהירה ביותר למפתחים) או באמצעות אפליקציית האינטרנט של Gemini Enterprise (חוויית משתמש קצה).

אפשרות 1: תצוגה מקדימה של Google Cloud Console

במסוף Google Cloud, עוברים לדף Gemini Enterprise:

‫

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

בסרגל החיפוש, מזינים את השאילתה הבאה:

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 בקטע מהארגון שלך.
מקלידים את אותה שאילתה כמו באפשרות התצוגה המקדימה במסוף Google Cloud.
כשמוצגת בקשה לעבור את תהליך הסכמה מהמשתמש ב-OAuth, לוחצים על הרשאה.
הסוכן יבצע משימות בצורה חלקה בכמה שירותים באמצעות פרוטוקול ה-MCP.

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

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

אפשרות מסוף

עוברים אל מרכז הבקרה של ממשקי ה-API והשירותים, בוחרים את שירותי ה-MCP שהפעלתם (לדוגמה, Calendar MCP,‏ Gmail MCP) ולוחצים על השבתת ה-API. מוחקים את מזהי הלקוחות ב-OAuth בקטע Google Auth Platform (פלטפורמת אימות של Google) > Clients (לקוחות), ומוחקים את הפריסה של Reasoning Engine ממסוף Gemini Enterprise.

אפשרות CLI

מריצים את פקודות הטרמינל הבאות כדי להשבית את שירותי ה-MCP:

# Disable Workspace MCP services
gcloud services disable calendarmcp.googleapis.com \
  chatmcp.googleapis.com \
  drivemcp.googleapis.com \
  gmailmcp.googleapis.com

8. מזל טוב

מעולה! יצרתם, בדקתם ופרסתם בהצלחה סוכן AI של ADK עם קוד מקצועי שמחובר ישירות לשרתי ה-MCP הרשמיים של Google Workspace.

מה למדתם

איך מפעילים שירותי Google Workspace MCP ב-Google Cloud.
איך מטפלים בפרטי כניסה של OAuth לבדיקה מקומית של ADK באמצעות כותרות סטטיות.
איך מטמיעים הזרקת טוקנים דינמית באמצעות header_provider לסוכני ייצור.
איך פורסים סוכן ADK ל-GEAP Agent Runtime ורושמים אותו ב-Gemini Enterprise.

יצירת סוכן AI ל-Google Workspace באמצעות ADK ו-MCP

1. מבוא

הפעולות שתבצעו:

הדרישות

‫2. לפני שמתחילים

יצירה או בחירה של פרויקט ב-Google Cloud

אפשרות Console

אפשרות CLI

הפעלת ממשקי ה-API

אפשרות Console

אפשרות CLI מריצים את פקודות הטרמינל הבאות:

הגדרת אפליקציית Chat

3. הגדרת הסכמה ולקוחות OAuth

הגדרת מסך ההסכמה ל-OAuth

יצירת מזהה לקוח לפיתוח מקומי (אפליקציה למחשב)

4. פיתוח ובדיקה של סוכנים

1. הגדרת ספריית סביבה

2. הכנת קובץ פרטי הכניסה

3. אימות ויצירה של קובץ ‎ .env ‏ (auth.py)

יצירת קוד הסוכן

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

אפשרות 1: ממשק משתמש אינטראקטיבי באינטרנט

אם אתם משתמשים במכונה מקומית:

אם אתם ב-Google Cloud Shell:

אפשרות 2: מצב Terminal CLI (חלופה)

איך כותבים הנחיות לסוכן

5. פריסה בסביבת ייצור

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

פריסה לזמן ריצה של סוכן GEAP

6. הרשמה ל-Gemini Enterprise

יצירת מזהה לקוח לסביבת ייצור (אפליקציית אינטרנט)

יצירת אפליקציית Gemini Enterprise

רישום הסוכן המותאם אישית

רוצה לנסות את הסוכן ב-Gemini Enterprise?

אפשרות 1: תצוגה מקדימה של Google Cloud Console

אפשרות 2: Gemini Enterprise בדפדפן

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

אפשרות מסוף

אפשרות CLI

8. מזל טוב

מה למדתם

מסמכי עזר

3. אימות ויצירה של קובץ ‎ .env ‏ (`auth.py`)