Google Workspace-KI‑Agenten mit ADK und MCP erstellen

1. Einführung

In diesem Codelab erfahren Sie, wie Sie mit dem Agent Development Kit (ADK) einen KI-Agenten mit Pro-Code erstellen, der direkt mit den offiziellen Google Workspace-MCP-Servern verbunden ist.

Das Model Context Protocol (MCP) ist ein offener Standard, der es KI-Modellen ermöglicht, Tools, die von Remoteservern bereitgestellt werden, sicher zu verwenden. Das ADK ist das Pro-Code-Framework von Google zum Erstellen autonomer Agenten. Durch die Kombination dieser Datenquellen können Sie hochgradig angepasste Agents erstellen, die auf Ihren Daten aus Gmail, Google Drive, Google Kalender, Google Chat und Personen basieren.

Die vollständige Dokumentation zu verfügbaren Tools und zur Konfiguration finden Sie unter Google Workspace-MCP-Server konfigurieren.

Aufgaben

• Aktivieren Sie Google Workspace MCP-Dienste in Ihrem Google Cloud-Projekt.
• Konfigurieren Sie die OAuth-Zustimmung und erstellen Sie Anmeldedaten für lokale Tests und die Produktionsbereitstellung.
• Lokalen ADK-Agenten erstellen, der mithilfe statischer Tokens eine Verbindung zu den fünf Workspace-MCP-Servern herstellt
• Einen produktionsreifen ADK-Agenten erstellen und in der Gemini Enterprise Agent Platform (GEAP) Agent Runtime bereitstellen, der die dynamische Token-Einfügung verwendet.
• Registrieren und testen Sie Ihren benutzerdefinierten Agenten nativ in Gemini Enterprise.

Voraussetzungen

• Ein Webbrowser, z.B. Chrome.
• Google Cloud-Projekt mit aktivierter Abrechnungsfunktion.
• Ein Google Workspace-Konto (mit aktivierten smarten Funktionen)
• Python 3.11 oder höher ist auf Ihrem lokalen Computer installiert.
• Die Google Cloud CLI (gcloud) ist installiert und initialisiert.

2. Hinweis

Google Workspace Developer Preview Program:Der Zugriff auf Google Workspace-MCP-Server ist Teil des öffentlichen Entwicklervorschauprogramms. Falls Sie es noch nicht getan haben, registrieren Sie sich bitte unter https://developers.google.com/workspace/preview und sorgen Sie dafür, dass Ihr Konto für das Programm akzeptiert wird.

Google Cloud-Projekt erstellen oder auswählen

Konsolenoption

Wählen Sie in der Google Cloud Console ein Google Cloud-Projekt aus oder erstellen Sie eines.

CLI-Option

So erstellen Sie ein neues Projekt und legen es als aktiv fest:

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

APIs aktivieren

Wenn Sie die Google Workspace-MCP-Server verwenden möchten, müssen Sie sowohl die Standard-Google Workspace-APIs als auch die dedizierten MCP-Dienste aktivieren.

Konsolenoption

Klicken Sie auf die folgenden Buttons, um sie über den Webbrowser zu aktivieren:

Standard-APIs aktivieren

MCP-Dienste aktivieren

CLI-Option: Führen Sie diese Terminalbefehle aus:

# 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-App konfigurieren

Wenn Sie den Google Chat-MCP-Server verwenden möchten, müssen Sie eine Chat-App in Ihrem Google Cloud-Projekt konfigurieren.

1. Rufen Sie die Google Chat API > Verwalten > Konfiguration auf.
2. Chat App einrichten:
   • App-Name: ADK Workspace Agent
   • Avatar-URL: https://developers.google.com/chat/images/quickstart-app-avatar.png
   • Description: MCP server connection for ADK Agent
   • Deaktivieren Sie unter Funktionen die Option Interaktive Funktionen aktivieren.
   • Wählen Sie unter Logs die Option Fehler in Logging protokollieren aus.
3. Klicken Sie auf Speichern.

3. OAuth-Zustimmung und -Clients konfigurieren

Die Google Workspace MCP-Server verwenden OAuth 2.0 für die sichere Authentifizierung. Sie müssen den OAuth-Zustimmungsbildschirm konfigurieren und zwei separate Client-IDs erstellen: eine für die lokale Entwicklung und eine für den bereitgestellten Agent.

OAuth-Zustimmungsbildschirm einrichten

1. Klicken Sie in der Google Cloud Console links oben auf das Navigationsmenü (Dreistrich-Menü). Wählen Sie Google Auth Platform > Branding aus (oder APIs & Dienste > OAuth-Zustimmungsbildschirm, falls Google Auth Platform nicht angezeigt wird).
2. Konfigurieren Sie App-Informationen:
   • App-Name: Workspace ADK Agent
   • E‑Mail-Adresse für den Nutzersupport: Wählen Sie Ihre E‑Mail-Adresse aus.
3. Konfigurieren Sie die Zielgruppe: Wählen Sie Intern aus.
4. Konfigurieren Sie die Kontaktdaten: Geben Sie Ihre E‑Mail-Adresse ein und klicken Sie auf Erstellen.
5. Klicken Sie auf Data Access > Add or Remove Scopes. Fügen Sie unter Bereiche manuell hinzufügen die folgenden Bereiche hinzu, um Zugriff auf alle fünf Dienste zu gewähren:

   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
   

6. Klicken Sie auf Zur Tabelle hinzufügen, dann auf Aktualisieren und schließlich auf Speichern.

Client-ID für die lokale Entwicklung erstellen (Desktop-App)

1. Rufen Sie in der Google Cloud Console die Seite Google Auth Platform > Clients (oder APIs & Dienste > Anmeldedaten) auf. Klicken Sie auf Anmeldedaten erstellen (oder Client erstellen) und wählen Sie OAuth-Client-ID aus.
2. Wählen Sie als Anwendungstyp Desktop-App aus.
3. Geben Sie den Namen Workspace Agent Local ein.
4. Klicken Sie auf Erstellen und laden Sie die JSON-Datei herunter. Speichern Sie sie lokal als client_secret.json.

4. Agent-Entwicklung und ‑Tests

In diesem Abschnitt wird beschrieben, wie Sie die Agent-Umgebung erstellen. Für Tests verwenden wir einen statischen Token-Ansatz, bei dem wir ein OAuth-Token mit gcloud abrufen und an McpToolset des ADK übergeben. Sie können diese Schritte entweder auf Ihrem lokalen Computer oder in Google Cloud Shell ausführen.

Wählen Sie Lokaler Computer oder Google Cloud Shell aus, um Ihre Entwicklungsumgebung einzurichten. Bei beiden Methoden wird ein gemeinsames Python-Skript für die Authentifizierung verwendet, um die Konsistenz auf allen Plattformen zu gewährleisten.

1. Umgebungsverzeichnis einrichten

Führen Sie die folgenden Befehle in Ihrem Terminal aus, um ein Projektverzeichnis zu erstellen und die erforderlichen Pakete zu installieren.

• Für Google Cloud Shell:Klicken Sie zuerst in der Symbolleiste rechts oben in der Google Cloud Console auf das Symbol Cloud Shell aktivieren (>_).
• Auf dem lokalen Computer:Öffnen Sie Ihr Standardterminal.

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

Wichtig:Achten Sie darauf, dass der Terminal-Prompt die aktivierte Umgebung widerspiegelt ((.venv) sollte angezeigt werden). Wenn Sie ein neues Terminalfenster öffnen oder später eine neue Verbindung zu Cloud Shell herstellen, MÜSSEN Sie source .venv/bin/activate aus dem Verzeichnis gws-adk-agent noch einmal ausführen, damit Sie die richtige Version der ADK CLI verwenden. Wenn Sie eine vorhandene oder globale Umgebung verwenden, kann es zu Versionskonflikten und 404-Fehlern für Web-Assets kommen.

2. Datei mit Anmeldedaten vorbereiten

Die im vorherigen Schritt heruntergeladene Datei client_secret.json muss im Stammverzeichnis Ihres gws-adk-agent-Verzeichnisses abgelegt werden.

• Lokaler Computer:Verschieben oder kopieren Sie die heruntergeladene Datei client_secret.json in das Verzeichnis gws-adk-agent.
• Google Cloud Shell:Erstellen Sie die Datei, indem Sie den folgenden Befehl in Cloud Shell ausführen (ersetzen Sie [PASTE_JSON_HERE] durch Ihren tatsächlichen JSON-Inhalt):

cat << 'EOF' > client_secret.json
[PASTE_JSON_HERE]
EOF

3. Authentifizieren und .env-Datei generieren (auth.py)

Um die Authentifizierung einheitlich zu handhaben und umgebungsspezifische Probleme beim CLI-Routing zu vermeiden, verwenden wir ein benutzerdefiniertes Python-Skript, das auf den offiziellen Google-Authentifizierungsbibliotheken basiert. Dieses Skript verwaltet den OAuth-Ablauf, speichert die Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) lokal und generiert die erforderliche .env-Datei.

Erstellen Sie im Verzeichnis gws-adk-agent eine Datei mit dem Namen auth.py und fügen Sie den folgenden Code hinzu:

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")

Führen Sie das Skript in Ihrem Terminal aus:

python3 auth.py

Agent-Code erstellen

Unabhängig von der Umgebung, die Sie im vorherigen Schritt ausgewählt haben, bleibt der Agent-Code genau derselbe. Erstellen Sie in Ihrem zuvor erstellten Unterverzeichnis workspace_agent eine Datei mit dem Namen agent.py und fügen Sie den folgenden Code hinzu. In diesem Skript werden Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) verwendet, um die Autorisierung bereitzustellen. Anmeldedaten werden automatisch über einen dynamischen Header-Anbieter validiert und aktualisiert.

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]
)

Agent ausführen und testen

Bevor Sie fortfahren:Prüfen Sie, ob Ihre virtuelle Umgebung noch aktiv ist (suchen Sie in der Eingabeaufforderung des Terminals nach (.venv)). Wenn sie nicht aktiv ist, führen Sie source .venv/bin/activate über das Verzeichnis gws-adk-agent aus.

Sie können entweder über die interaktive Web-UI oder direkt in Ihrem Terminal/Ihrer Shell mit Ihrem Agenten interagieren.

Option 1: Interaktive Web-UI

Wenn Sie einen lokalen Computer verwenden:

1. Starten Sie die ADK-Weboberfläche über das gws-adk-agent-Stammverzeichnis des Projekts:

   adk web
   

2. Öffnen Sie http://localhost:8000 in Ihrem Browser, um mit Ihrem Agent zu chatten.

Wenn Sie Google Cloud Shell verwenden:

1. Starten Sie die ADK-Weboberfläche im Stammverzeichnis Ihres gws-adk-agent-Projekts und erzwingen Sie dabei explizit Port 8080:

   adk web --port 8080 --allow_origins=*
   

2. Klicken Sie in der Symbolleiste von Cloud Shell oben rechts auf die Schaltfläche Webvorschau und wählen Sie Vorschau auf Port 8080 aus, um die Benutzeroberfläche in einem neuen Tab zu öffnen.

Option 2: Terminal-Befehlszeilenmodus (Alternative)

Wenn Sie lieber im Terminal bleiben oder die Einrichtung von Webbrowser-Vorschauen vermeiden möchten, bietet das ADK einen nativen interaktiven REPL-Chat-Modus.

Führen Sie im Stammverzeichnis Ihres gws-adk-agent-Projekts den folgenden Befehl aus. Er funktioniert sowohl auf einem lokalen Computer als auch in Google Cloud Shell:

adk run workspace_agent

Sie werden direkt in Ihrer Shell zu einer interaktiven Chatsitzung weitergeleitet:

Running agent gws_adk_agent, type exit to exit.
[user]: 

Prompting Ihres Agenten ausprobieren

Unabhängig von der ausgewählten Benutzeroberfläche sollten Sie den Agenten mit Anfragen testen, die die Workspace MCP-Tools nutzen:

• What are my upcoming meetings this week?
  

• Summarize the last 3 unread emails in my Gmail.
  

5. Produktionsbereitstellung

Wenn wir den Agent in der Produktion bereitstellen möchten, können wir kein hartcodiertes lokales Token verwenden. Stattdessen verwenden wir header_provider des ADK, um das von der Gemini Enterprise-Plattform eingefügte OAuth-Zugriffstoken dynamisch zu extrahieren, wenn ein Nutzer mit dem Agenten interagiert.

Produktions-Agent-Code erstellen

Erstellen Sie ein Verzeichnispaket mit dem Namen enterprise_ai und darin eine agent.py-Datei:

mkdir -p enterprise_ai

Schreiben Sie den folgenden Inhalt in 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]
)

In der GEAP Agent Runtime bereitstellen

So stellen Sie Ihren Pro-Code-Agenten mit der ADK-CLI bereit:

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

Warten Sie, bis die Bereitstellung abgeschlossen ist, und kopieren Sie den generierten Reasoning-Engine-Ressourcennamen aus der Terminalausgabe (z.B. projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID).

6. In Gemini Enterprise registrieren

Wir stellen den benutzerdefinierten ADK-Agenten jetzt in Gemini Enterprise zur Verfügung, damit Nutzer direkt mit ihm chatten können.

Client-ID für die Produktion erstellen (Webanwendung)

Wenn Sie Ihren Agent in der Produktion bereitstellen möchten, müssen Sie eine Client-ID für Webanwendungen erstellen. Im Gegensatz zum Desktopclient, der für lokale Tests verwendet wird, ermöglicht ein Webanwendungsclient einen sicheren, serverseitigen OAuth-Ablauf. So kann der gehostete Agent in GEAP Agent Runtime die vom Nutzer bereitgestellten Authentifizierungstokens, die von Gemini Enterprise über den angegebenen Weiterleitungs-URI weitergeleitet werden, sicher empfangen. Diese Einrichtung ist erforderlich, damit der Kundenservicemitarbeiter in einer Produktionsumgebung sicher im Namen des Nutzers auf Google Workspace-Daten zugreifen kann.

1. Klicken Sie in der Google Cloud Console links oben auf das Navigationsmenü (Dreistrich-Menü). Wählen Sie Google Auth Platform > Clients (oder APIs & Dienste > Anmeldedaten, falls die Google Auth Platform nicht angezeigt wird) aus. Klicken Sie auf Anmeldedaten erstellen (oder Client erstellen) und wählen Sie OAuth-Client-ID aus.
2. Wählen Sie als Anwendungstyp Webanwendung aus.
3. Geben Sie den Namen Workspace Agent Production ein.
4. Fügen Sie im Abschnitt Autorisierte Weiterleitungs-URIs die folgenden URIs hinzu:
   • Klicken Sie auf URI hinzufügen und geben Sie https://vertexaisearch.cloud.google.com/oauth-redirect ein.
   • Klicken Sie noch einmal auf URI hinzufügen und geben Sie https://vertexaisearch.cloud.google.com/static/oauth/oauth.html ein.
5. Klicken Sie auf Erstellen. Kopieren Sie im Pop-up-Fenster „OAuth-Client erstellt“ (oder aus der Liste Clients) die Client-ID und den Clientschlüssel. Sie benötigen diese, wenn Sie den Agenten in Gemini Enterprise registrieren.

Gemini Enterprise-Anwendung erstellen

1. Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf:

Gemini Enterprise

1. Klicken Sie auf der Karte Gemini Enterprise auf Verwalten.
2. Klicken Sie auf Anwendung erstellen.
3. Klicken Sie im Bereich Gemini Enterprise auf Erstellen.
4. Geben Sie im Feld Name der Anwendung einen Namen für die Anwendung ein. Darunter wird die Anwendungs-ID angezeigt.
5. Geben Sie im Feld Externer Name Ihres Unternehmens oder Ihrer Organisation den Namen des Unternehmens oder der Organisation ein. Für diese Anleitung können Sie Cymbal Bank verwenden.
6. Wählen Sie als Standort für Ihre Anwendung Global aus.
7. Klicken Sie auf Weiter.

Benutzerdefinierten Agent registrieren

1. Öffnen Sie die Gemini Enterprise Console:

Gemini Enterprise Console

2. Wählen Sie Ihre aktive App aus, gehen Sie zu Agents (Agenten) und klicken Sie auf + Add agent (+ Agent hinzufügen) > Add Custom agent via Agent Runtime (Benutzerdefinierten Agenten über Agent Runtime hinzufügen).
3. Klicken Sie im Bereich Autorisierungen auf Autorisierung hinzufügen:
   • Autorisierungsname: workspace-adk-auth (Muss genau mit CLIENT_AUTH_NAME in Ihrem Python-Code übereinstimmen)
   • Client-ID: Fügen Sie die oben erstellte Client-ID der Webanwendung für die Produktion ein.
   • Clientschlüssel: Fügen Sie den oben erstellten Clientschlüssel der Webanwendung für die Produktion ein.
   • Token-URI: https://oauth2.googleapis.com/token
   • Autorisierungs-URI: Erstellen Sie den URI, indem Sie YOUR_CLIENT_ID durch die Client-ID ersetzen, die Sie oben in Schritt 5 kopiert haben:

     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
     

4. Klicken Sie auf Fertig und dann auf Weiter.
5. Im Bereich Konfiguration:
   • Agent-Name: Workspace Pro Agent
   • Beschreibung:

     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.
     

   • Reasoning Engine der Agent Runtime: Fügen Sie den Ressourcenname der Engine ein, den Sie aus der adk deploy-Ausgabe kopiert haben.
6. Klicken Sie auf Erstellen.

Agent in Gemini Enterprise ausprobieren

Sie können mit Ihrem Agent entweder über die Google Cloud Console Preview (am schnellsten für Entwickler) oder über die Gemini Enterprise Web-App (Endnutzererfahrung) interagieren.

Option 1: Google Cloud Console-Vorschau

1. Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf:

Gemini Enterprise

2. Klicken Sie im Navigationsmenü auf Apps und wählen Sie die App aus, die Sie gerade erstellt haben.
3. Klicken Sie oben rechts auf Vorschau oder Vorschau öffnen.
4. Geben Sie in der Suchleiste die folgende Abfrage ein:

   Search for files in Drive related to 'Project Milestone', summarize them, and tell me if I have any meetings with the project owner today.
   

5. Drücken Sie die Eingabetaste, um die Anfrage zu senden und die Ergebnisse direkt in der Console anzusehen.

Option 2: Gemini Enterprise Web-App

1. Öffnen Sie die Oberfläche Ihrer Gemini Enterprise-Webanwendung.
2. Klicken Sie auf das Dreistrich-Menü ☰ > Agents und wählen Sie unter Aus Ihrer Organisation die Option Workspace Pro-Agent aus.
3. Geben Sie dieselbe Anfrage ein wie in der Vorschauoption der Google Cloud Console.
4. Klicken Sie auf Autorisieren, wenn Sie aufgefordert werden, den OAuth-Nutzereinwilligungsvorgang zu durchlaufen.
5. Der Agent führt Aufgaben nahtlos über mehrere Dienste hinweg aus und nutzt dabei das MCP-Protokoll.

7. Bereinigen

Bereinigen Sie Ihre Ressourcen, um unnötige Gebühren zu vermeiden:

Console-Option

Rufen Sie das Dashboard „APIs & Dienste“ auf, wählen Sie die aktivierten MCP-Dienste aus (z.B. Calendar MCP, Gmail MCP) und klicken Sie auf API deaktivieren. Löschen Sie die OAuth-Client-IDs unter Google Auth Platform > Clients und löschen Sie die Reasoning Engine-Bereitstellung in der Gemini Enterprise Console.

Befehlszeilenoption

Führen Sie die folgenden Terminalbefehle aus, um die MCP-Dienste zu deaktivieren:

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

8. Glückwunsch

Glückwunsch! Sie haben einen Pro-Code-KI-Agenten für das ADK erstellt, getestet und bereitgestellt, der direkt mit den offiziellen Google Workspace-MCP-Servern verbunden ist.

Das haben Sie gelernt

• So aktivieren Sie Google Workspace MCP-Dienste in Google Cloud.
• Umgang mit OAuth-Anmeldedaten für lokale ADK-Tests mit statischen Headern
• Dynamisches Einfügen von Tokens mit header_provider für Produktions-Agents implementieren
• So stellen Sie einen ADK-Agenten in der GEAP-Laufzeit für KI-Agenten bereit und registrieren ihn in Gemini Enterprise.

Referenzdokumente

• Model Context Protocol-Spezifikation (MCP)
• ADK-Dokumentation (Pro-Code-Framework)
• Google Workspace-MCP-Server konfigurieren