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

Membangun Agen AI Google Workspace dengan ADK dan MCP

1. Pengantar

Dalam codelab ini, Anda akan mempelajari cara membangun agen AI pro-code menggunakan Agent Development Kit (ADK) yang terhubung langsung ke server MCP Google Workspace resmi.

Model Context Protocol (MCP) adalah standar terbuka yang memungkinkan model AI menggunakan alat yang disediakan oleh server jarak jauh secara aman. ADK adalah framework pro-code Google untuk membangun agen otonom. Dengan menggabungkannya, Anda dapat membuat agen yang sangat disesuaikan berdasarkan data Gmail, Google Drive, Google Kalender, Google Chat, dan Kontak.

Untuk dokumentasi lengkap tentang alat dan konfigurasi yang tersedia, lihat Mengonfigurasi server MCP Google Workspace.

Yang akan Anda lakukan

Mengaktifkan layanan MCP Google Workspace di project Google Cloud.
Mengonfigurasi izin OAuth dan membuat kredensial untuk pengujian lokal dan deployment produksi.
Membangun agen ADK lokal yang terhubung ke 5 server MCP Workspace menggunakan token statis.
Membangun dan men-deploy agen ADK siap produksi ke Runtime Agen Platform Agen Gemini Enterprise (GEAP) yang menggunakan penyisipan token dinamis.
Mendaftarkan dan menguji agen kustom secara native dalam Gemini Enterprise.

Yang akan Anda butuhkan

Browser web (misalnya, Chrome).
Project Google Cloud yang mengaktifkan penagihan.
Akun Google Workspace (dengan fitur smart diaktifkan).
Python 3.11+ diinstal di komputer lokal Anda.
Google Cloud CLI (gcloud) diinstal dan diinisialisasi.

2. Sebelum memulai

Membuat atau Memilih project Google Cloud

Opsi Konsol

Di Konsol Google Cloud, pilih atau buat project Google Cloud.

Opsi CLI

Buat project baru dan tetapkan sebagai aktif:

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

Mengaktifkan API

Untuk menggunakan server MCP Google Workspace, Anda harus mengaktifkan Google Workspace API standar dan layanan MCP khusus.

Opsi Konsol

Klik tombol berikut untuk mengaktifkannya menggunakan browser web:

Opsi CLI Jalankan perintah terminal ini:

# 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

Mengonfigurasi Aplikasi Chat

Untuk menggunakan server MCP Google Chat, Anda harus mengonfigurasi aplikasi Chat di project Google Cloud.

Di konsol Google Cloud, telusuri Google Chat API, lalu klik Google Chat API > Manage > Configuration.
Siapkan aplikasi Chat:
- App name: ADK Workspace Agent
- Avatar URL: https://developers.google.com/chat/images/quickstart-app-avatar.png
- Description: MCP server connection for ADK Agent
- Di bagian Functionality, nonaktifkan Enable interactive features.
- Di bagian Logs, pilih Log errors to Logging.
Klik Save.

3. Mengonfigurasi Izin dan Klien OAuth

Server MCP Google Workspace menggunakan OAuth 2.0 untuk autentikasi yang aman. Anda harus mengonfigurasi layar izin OAuth dan membuat dua client ID terpisah: satu untuk pengembangan lokal dan satu untuk agen yang di-deploy.

Di konsol Google Cloud, klik Navigation menu (ikon hamburger) di pojok kiri atas. Pilih Google Auth Platform > Branding (atau APIs & Services > OAuth consent screen jika Google Auth Platform tidak terlihat).
Konfigurasikan App Information:
- App name: Workspace ADK Agent
- User support email: Pilih email Anda.
Konfigurasikan Audience: Pilih Internal.
Konfigurasikan Contact Information: Masukkan alamat email Anda, lalu klik Create.

Buka Data Access > Add or Remove Scopes. Di bagian Manually add scopes, tambahkan cakupan berikut untuk memberikan akses ke semua 5 layanan:

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

Klik Add to Table, lalu Update, dan terakhir Save.

Membuat Client ID untuk Pengembangan Lokal (Aplikasi Desktop)

Di konsol Google Cloud, buka Google Auth Platform > Clients (atau APIs & Services > Credentials). Klik Create Credentials (atau Create Client) dan pilih OAuth client ID.
Pilih Desktop app sebagai jenis aplikasi.
Beri nama Workspace Agent Local.
Klik Create dan download file JSON. Simpan secara lokal sebagai client_secret.json.

4. Pengembangan dan Pengujian Agen

Bagian ini menjelaskan cara membangun lingkungan agen. Kita akan menggunakan pendekatan token statis untuk pengujian, dengan mengambil token OAuth menggunakan gcloud dan meneruskannya ke McpToolset ADK. Anda dapat mengikuti langkah-langkah ini menggunakan Komputer Lokal atau Google Cloud Shell.

Pilih lingkungan Anda: Komputer Lokal atau Google Cloud Shell untuk menyiapkan lingkungan pengembangan. Kedua metode akan menggunakan skrip Python bersama untuk autentikasi guna memastikan konsistensi di seluruh platform.

1. Menyiapkan Direktori Lingkungan

Jalankan perintah berikut di terminal Anda untuk membuat direktori project dan menginstal paket yang diperlukan.

Untuk Google Cloud Shell: Pertama, klik ikon Activate Cloud Shell (>_) di toolbar kanan atas Konsol Google Cloud.
Untuk Komputer Lokal: Buka terminal standar Anda.

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. Menyiapkan File Kredensial

Anda harus menempatkan file client_secret.json yang Anda download pada langkah sebelumnya ke root direktori gws-adk-agent.

Komputer Lokal: Pindahkan atau salin file client_secret.json yang didownload ke direktori gws-adk-agent.
Google Cloud Shell: Buat file dengan menjalankan perintah berikut di Cloud Shell (ganti [PASTE_JSON_HERE] dengan konten JSON Anda yang sebenarnya):

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

3. Mengautentikasi dan Membuat .env (`auth.py`)

Untuk menangani autentikasi secara konsisten dan menghindari masalah perutean CLI khusus lingkungan, kita menggunakan skrip Python kustom yang didukung oleh library autentikasi Google resmi. Skrip ini mengelola alur OAuth, menyimpan Kredensial Default Aplikasi (ADC) secara lokal, dan membuat file .env yang diperlukan.

Buat file bernama auth.py di direktori gws-adk-agent dan tambahkan kode berikut:

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

Jalankan skrip di terminal Anda:

python3 auth.py

Membuat Kode Agen

Terlepas dari lingkungan yang Anda pilih pada langkah sebelumnya, kode agen akan tetap sama. Buat file bernama agent.py di dalam subdirektori workspace_agent yang telah dibuat sebelumnya dan tambahkan kode berikut. Skrip ini menggunakan Kredensial Default Aplikasi (ADC) untuk memberikan otorisasi, memvalidasi dan memperbarui kredensial secara otomatis dalam memori melalui penyedia header dinamis.

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 5 GWS 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
)

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

Menjalankan dan Menguji Agen Anda

Anda dapat berinteraksi dengan agen menggunakan UI Web interaktif atau langsung di dalam Terminal/Shell.

Opsi 1: UI Web Interaktif

Jika Anda menggunakan Komputer Lokal:

Dari direktori root project gws-adk-agent, mulai antarmuka web ADK:
```
adk web
```
Buka http://localhost:8000 di browser Anda untuk melakukan chat dengan agen Anda.

Jika Anda menggunakan Google Cloud Shell:

Dari direktori root project gws-adk-agent, mulai antarmuka web ADK dengan menerapkan port 8080 secara eksplisit:
```
adk web --port 8080 --allow_origins=*
```
Klik tombol Web Preview di kanan atas toolbar Cloud Shell dan pilih Preview on port 8080 untuk membuka antarmuka di tab baru.

Opsi 2: Mode CLI Terminal (Alternatif)

Jika Anda lebih suka tetap berada di terminal atau ingin menghindari penyiapan pratinjau browser web, ADK menyediakan mode chat REPL interaktif native.

Dari direktori root project gws-adk-agent, jalankan perintah berikut (perintah ini berfungsi sama di Komputer Lokal dan Google Cloud Shell):

adk run workspace_agent

Anda akan memasuki sesi chat interaktif langsung di shell Anda:

Running agent gws_adk_agent, type exit to exit.

[user]:

Mencoba Meminta Agen Anda

Terlepas dari antarmuka yang Anda pilih, coba uji agen dengan kueri yang memanfaatkan alat MCP Workspace:

What are my upcoming meetings this week?

Summarize the last 3 unread emails in my Gmail.

5. Deployment Produksi

Untuk men-deploy agen ke produksi, kita tidak dapat menggunakan token lokal yang dikodekan secara permanen. Sebagai gantinya, kita menggunakan header_provider ADK untuk mengekstrak token akses OAuth yang disisipkan secara dinamis oleh platform Gemini Enterprise saat pengguna berinteraksi dengan agen.

Membuat Kode Agen Produksi

Buat paket direktori bernama enterprise_ai dan buat file agent.py di dalamnya:

mkdir -p enterprise_ai

Tulis konten berikut ke 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
)

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

Men-deploy ke Runtime Agen GEAP

Deploy agen pro-code Anda menggunakan ADK CLI:

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

Tunggu hingga deployment selesai dan salin nama resource Reasoning Engine yang dihasilkan dari output terminal (misalnya, projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID).

6. Mendaftar di Gemini Enterprise

Sekarang, kita akan memasukkan agen ADK kustom ke Gemini Enterprise sehingga pengguna dapat melakukan chat dengannya secara native.

Membuat Client ID untuk Produksi (Aplikasi Web)

Untuk men-deploy agen ke produksi, Anda harus membuat client ID Aplikasi web. Tidak seperti klien desktop yang digunakan untuk pengujian lokal, klien aplikasi web memungkinkan alur OAuth sisi server yang aman. Hal ini memungkinkan agen yang dihosting di Runtime Agen GEAP menerima token autentikasi pengguna yang diteruskan oleh Gemini Enterprise secara aman, menggunakan URI pengalihan yang ditentukan. Penyiapan ini diperlukan agar agen dapat mengakses data Google Workspace secara aman atas nama pengguna di lingkungan produksi.

Di konsol Google Cloud, klik Navigation menu (ikon hamburger) di pojok kiri atas. Pilih Google Auth Platform > Clients (atau APIs & Services > Credentials jika Google Auth Platform tidak terlihat). Klik Create Credentials (atau Create Client) dan pilih OAuth client ID.
Pilih Web application sebagai jenis aplikasi.
Beri nama Workspace Agent Production.
Di bagian Authorized redirect URIs, tambahkan URI berikut:
- Klik Add URI dan masukkan https://vertexaisearch.cloud.google.com/oauth-redirect.
- Klik Add URI lagi dan masukkan https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
Klik Create. Di pop-up "OAuth client created" (atau dari daftar Clients ), salin Client ID dan Client Secret. Anda akan memerlukan informasi ini saat mendaftarkan agen di Gemini Enterprise.

Membuat Aplikasi Gemini Enterprise

Di konsol Google Cloud, buka halaman Gemini Enterprise:

Di kartu Gemini Enterprise, klik Manage.
Klik Create app.
Di bagian Gemini Enterprise, klik Create.
Di kolom Your app name, masukkan nama untuk aplikasi Anda. ID aplikasi akan muncul di bawah nama aplikasi.
Di kolom External name of your company or organization, masukkan nama perusahaan atau organisasi. Untuk tutorial ini, Anda dapat menggunakan Cymbal Bank.
Pilih global (Global) sebagai lokasi untuk aplikasi Anda.
Klik Continue.

Mendaftarkan Agen Kustom

Buka konsol Gemini Enterprise:

Pilih aplikasi aktif Anda, buka Agents, lalu klik + Add agent > Add Custom agent via Agent Runtime.

Di bagian Authorizations, klik Add authorization:

Nama otorisasi: workspace-adk-auth (Harus sama persis dengan CLIENT_AUTH_NAME dalam kode Python Anda)
Client ID: Tempel Client ID Aplikasi Web Produksi yang dibuat di atas.
Client secret: Tempel Client Secret Aplikasi Web Produksi yang dibuat di atas.
Token URI: https://oauth2.googleapis.com/token

Authorization URI: Buat URI dengan mengganti YOUR_CLIENT_ID dengan Client ID yang Anda salin pada langkah 5 di atas:

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

Klik Done, lalu klik Next.

Di bagian Configuration:

Agent name: Workspace Pro Agent

Description:

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: Tempel nama resource mesin yang Anda salin dari output adk deploy.

Klik Create.

Mencoba Agen di Gemini Enterprise

Anda dapat berinteraksi dengan agen menggunakan Pratinjau Konsol Google Cloud (tercepat untuk developer) atau Aplikasi Web Gemini Enterprise (pengalaman pengguna akhir).

Opsi 1: Pratinjau Konsol Google Cloud

Di konsol Google Cloud, buka halaman Gemini Enterprise:

Di menu navigasi, klik Apps , lalu pilih aplikasi yang baru saja Anda buat.
Klik Preview atau klik Open preview di kanan atas.

Di kotak penelusuran, masukkan kueri berikut:

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

Tekan Enter untuk mengirimkan kueri dan melihat hasilnya langsung di konsol.

Opsi 2: Aplikasi Web Gemini Enterprise

Buka antarmuka Aplikasi Web Gemini Enterprise Anda.
Buka Menu ☰ > Agents , lalu pilih Workspace Pro Agent di bagian From your organization.
Ketik kueri yang sama seperti pada opsi Pratinjau Konsol Google Cloud.
Klik Authorize saat diminta untuk melalui alur izin pengguna OAuth.
Agen akan menjalankan tugas dengan lancar di beberapa layanan menggunakan protokol MCP.

7. Pembersihan

Untuk menghindari biaya yang tidak perlu, bersihkan resource Anda:

Opsi Konsol

Buka Dasbor API & Layanan, pilih layanan MCP yang Anda aktifkan (misalnya, MCP Kalender, MCP Gmail), lalu klik Disable API. Hapus Client ID OAuth di bagian Google Auth Platform > Clients, dan hapus deployment Reasoning Engine dari Konsol Gemini Enterprise.

Opsi CLI

Jalankan perintah terminal berikut untuk menonaktifkan layanan MCP:

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

8. Selamat

Selamat! Anda telah berhasil membangun, menguji, dan men-deploy agen AI ADK pro-code yang terhubung langsung ke server MCP Google Workspace resmi.

Yang telah Anda pelajari

Cara mengaktifkan layanan MCP Google Workspace di Google Cloud.
Cara menangani kredensial OAuth untuk pengujian ADK lokal menggunakan header statis.
Cara menerapkan penyisipan token dinamis menggunakan header_provider untuk agen produksi.
Cara men-deploy agen ADK ke Runtime Agen GEAP dan mendaftarkannya di Gemini Enterprise.

Membangun Agen AI Google Workspace dengan ADK dan MCP

1. Pengantar

Yang akan Anda lakukan

Yang akan Anda butuhkan

2. Sebelum memulai

Membuat atau Memilih project Google Cloud

Opsi Konsol

Opsi CLI

Mengaktifkan API

Opsi Konsol

Opsi CLI Jalankan perintah terminal ini:

Mengonfigurasi Aplikasi Chat

3. Mengonfigurasi Izin dan Klien OAuth

Menyiapkan Layar Izin OAuth

Membuat Client ID untuk Pengembangan Lokal (Aplikasi Desktop)

4. Pengembangan dan Pengujian Agen

1. Menyiapkan Direktori Lingkungan

2. Menyiapkan File Kredensial

3. Mengautentikasi dan Membuat .env (auth.py)

Membuat Kode Agen

Menjalankan dan Menguji Agen Anda

Opsi 1: UI Web Interaktif

Jika Anda menggunakan Komputer Lokal:

Jika Anda menggunakan Google Cloud Shell:

Opsi 2: Mode CLI Terminal (Alternatif)

Mencoba Meminta Agen Anda

5. Deployment Produksi

Membuat Kode Agen Produksi

Men-deploy ke Runtime Agen GEAP

6. Mendaftar di Gemini Enterprise

Membuat Client ID untuk Produksi (Aplikasi Web)

Membuat Aplikasi Gemini Enterprise

Mendaftarkan Agen Kustom

Mencoba Agen di Gemini Enterprise

Opsi 1: Pratinjau Konsol Google Cloud

Opsi 2: Aplikasi Web Gemini Enterprise

7. Pembersihan

Opsi Konsol

Opsi CLI

8. Selamat

Yang telah Anda pelajari

Dokumen referensi

3. Mengautentikasi dan Membuat .env (`auth.py`)