Mengintegrasikan Agen Vertex AI dengan Google Workspace

1. Sebelum memulai

Apa itu Vertex AI?

Vertex AI adalah platform pengembangan terpadu Google Cloud untuk membangun, men-deploy, dan menskalakan agen dan aplikasi AI tingkat perusahaan. Platform ini menyediakan alat canggih yang diperlukan developer dan data scientist untuk merancang alur kerja agentic kustom yang terintegrasi secara mendalam dengan infrastruktur berskala global.

Akses Model Garden: Pilih dari lebih dari 150 model dasar, termasuk rangkaian model Gemini lengkap, model pihak ketiga, dan model open source khusus untuk menemukan model yang paling sesuai dengan tugas agen tertentu.
Merancang orkestrasi yang kompleks: Vertex AI menyediakan framework untuk mendesain agen otonom yang menggunakan penalaran untuk merencanakan, mengeksekusi tugas multi-langkah, dan memanggil API eksternal.
Perujukan tingkat perusahaan: Hubungkan agen ke data bisnis aktif, termasuk RAG (Retrieval-Augmented Generation) berperforma tinggi untuk menghilangkan halusinasi dan memastikan akurasi faktual.
DevOps: Integrasikan pengembangan agen dengan lancar ke dalam pipeline CI/CD yang ada dengan SDK, API, dan alat evaluasi yang andal untuk mengukur performa dan keamanan agen dalam skala besar.
Keamanan tingkat industri: Vertex AI memastikan bahwa data pelanggan yang digunakan untuk pelatihan atau perujukan tetap bersifat pribadi, dienkripsi, dan mematuhi persyaratan residensi global.
Infrastruktur yang dioptimalkan: Skalakan beban kerja agentik dengan mudah di seluruh cluster TPU dan GPU kelas dunia Google, sehingga memastikan performa latensi rendah bahkan untuk aplikasi global yang paling berat.

Apa itu Google Workspace?

Google Workspace adalah kumpulan solusi produktivitas dan kolaborasi berbasis cloud yang didesain untuk individu, sekolah, dan bisnis:

Komunikasi: Layanan email profesional (Gmail), konferensi video (Meet), dan pesan tim (Chat).
Pembuatan Konten: Alat untuk menulis dokumen (Dokumen), membuat spreadsheet (Spreadsheet), dan mendesain presentasi (Slide).
Organisasi: Kalender bersama (Kalender) dan pencatatan digital (Keep).
Penyimpanan: Ruang cloud terpusat untuk menyimpan dan membagikan file dengan aman (Drive).
Pengelolaan: Kontrol administratif untuk mengelola pengguna dan setelan keamanan (Konsol Admin Workspace).

Jenis integrasi kustom apa?

Google Workspace dan Vertex AI menciptakan siklus proses yang efektif, di mana Workspace menyediakan data real-time dan konteks kolaborasi, sementara Vertex AI menawarkan model, penalaran berbasis agen, dan orkestrasi yang diperlukan untuk mengotomatiskan alur kerja cerdas.

Konektivitas pintar: Penyimpanan data, API, dan server MCP (yang dikelola Google dan kustom) yang dikelola Google memungkinkan agen mengakses data Workspace secara aman dan lancar serta melakukan tindakan atas nama pengguna.
Agen kustom: Dengan menggunakan desainer tanpa kode atau framework pro-code, tim dapat membangun agen khusus yang didasarkan pada data dan tindakan Workspace yang diatur oleh admin.
Integrasi native: Add-on Workspace menjembatani kesenjangan antara sistem dan aplikasi AI seperti Chat dan Gmail, baik melalui komponen UI khusus maupun proses latar belakang. Hal ini memungkinkan agen bertemu dengan pengguna tepat di tempat mereka berada untuk mendapatkan bantuan instan yang sesuai dengan konteks.

Dengan menggabungkan ekosistem produktivitas yang andal dari Google Workspace dengan kemampuan berbasis agen yang canggih dari Vertex AI, organisasi dapat mengubah operasi mereka melalui agen AI kustom berbasis data yang mengotomatiskan alur kerja yang kompleks langsung dalam alat yang sudah digunakan tim mereka setiap hari.

Prasyarat

Jika ingin mengikuti semua langkah di lingkungan Anda sendiri, Anda memerlukan:

Pengetahuan dasar tentang Google Cloud dan Python.
Project Google Cloud yang Anda miliki dengan penagihan. Untuk memeriksa apakah penagihan diaktifkan pada project yang ada, lihat Memverifikasi status penagihan project Anda. Untuk membuat project dan menyiapkan penagihan, lihat Membuat project Google Cloud. Untuk mengubah kepemilikan project, lihat Mengelola anggota project atau mengubah kepemilikan project.
Akun Google Workspace Business atau Enterprise dengan akses ke Google Chat dan fitur smart diaktifkan.
Google Cloud CLI diinstal dan diinisialisasi untuk project Google Cloud Anda.
Python 3.11+ sudah diinstal, lihat petunjuk di situs resmi Python.

Yang akan Anda bangun

Dalam codelab ini, kita akan membangun tiga solusi dengan agen Vertex AI yang terintegrasi erat dengan Google Workspace. Mereka akan mendemonstrasikan pola arsitektur yang dapat digunakan untuk berinteraksi dengan data, tindakan, dan UI.

Aplikasi Vertex AI Search

Agen ini memungkinkan pengguna menelusuri data dan mengambil tindakan untuk Workspace dalam bahasa alami mereka. Mengandalkan elemen berikut:

Model: Gemini.
Data & tindakan: Penyimpanan data Vertex AI untuk Google Workspace (Kalender, Gmail, Drive).
Host agen: Vertex AI Search.
UI: Widget Web Vertex AI Search.

Agen kustom

Agen ini memungkinkan pengguna menelusuri data dan melakukan tindakan untuk Workspace dalam bahasa alami mereka menggunakan alat dan aturan kustom. Mengandalkan elemen berikut:

Model: Gemini.
Data & tindakan: Penyimpanan data Vertex AI untuk Google Workspace (Kalender, Gmail, Drive), server Model Context Protocol (MCP) Vertex AI Search yang dikelola Google, fungsi alat kustom untuk mengirim pesan Google Chat (melalui Google Chat API).
Alat pembuatan agen: Agent Development Kit (ADK).
Host agen: Vertex AI Agent Engine.
UI: ADK Web.

Agen sebagai add-on Google Workspace

Agen ini memungkinkan pengguna menelusuri data untuk Workspace dalam bahasa alami mereka dalam konteks UI aplikasi Workspace. Mengandalkan elemen berikut:

Model: Gemini.
Data & tindakan: Penyimpanan data Vertex AI untuk Google Workspace (Kalender, Gmail, Drive), server Model Context Protocol (MCP) Vertex AI Search yang dikelola Google, fungsi alat kustom untuk mengirim pesan Google Chat (melalui Google Chat API).
Alat pembuatan agen: Agent Development Kit (ADK).
Host agen: Vertex AI Agent Engine.
UI: Add-on Google Workspace untuk Chat dan Gmail (dapat diperluas dengan mudah ke Kalender, Drive, Dokumen, Spreadsheet, dan Slide).
Add-on Google Workspace: Apps Script, Vertex AI Agent Engine API, kontekstual (pesan Gmail yang dipilih).

Yang akan Anda pelajari

Titik integrasi antara Vertex AI Search dan Google Workspace yang memungkinkan data dan tindakan.
Opsi untuk membangun agen kustom yang dihosting di Vertex AI.
Cara pengguna dapat mengakses agen seperti Widget Web Vertex AI Search dan aplikasi Google Workspace.

2. Siapkan

Sebelum membangun solusi, kita harus menginisialisasi setelan Aplikasi Vertex AI project, mengaktifkan API yang diperlukan, dan membuat penyimpanan data Vertex AI Workspace.

Tinjau konsep

Aplikasi Vertex AI

Aplikasi Vertex AI adalah solusi end-to-end terkelola di Google Cloud yang mengintegrasikan model machine learning (seperti agen AI generatif atau mesin telusur) dengan data perusahaan dan alat khusus untuk melakukan tugas kompleks seperti penelusuran semantik, pembuatan konten, atau interaksi pelanggan otomatis.

Penyimpanan data Vertex AI

Penyimpanan data Vertex AI adalah entitas yang berisi data yang diserap dari sumber data pihak pertama seperti Google Workspace atau aplikasi pihak ketiga seperti Jira atau Shopify. Penyimpanan data yang berisi data dari aplikasi pihak ketiga juga disebut konektor data.

Mulai setelan Aplikasi Vertex AI

Buka konsol Google Cloud di tab baru, lalu ikuti langkah-langkah berikut:

Pilih project Anda.
Di kolom penelusuran Google Cloud, buka AI Applications

Klik Continue and activate the API setelah meninjau dan menyetujui persyaratan.
Buka Settings.
Di tab Authentication, edit global.

Pilih Google Identity, lalu klik Save.

Mengaktifkan API

Penyimpanan data Vertex AI Workspace memerlukan pengaktifan API:

Di Konsol Google Cloud, aktifkan Calendar, Gmail, dan People API:

Klik Menu ☰ > APIs & Services > Enabled APIs & Services, lalu konfirmasi bahwa Google Calendar API, Gmail API, dan People API ada dalam daftar.

Membuat penyimpanan data

Buat penyimpanan data Google Drive:

Di konsol Google Cloud, buka AI Applications, lalu buka Data Stores.

Klik + Create data store.
Di bagian Sumber, di bagian Google Drive, klik Pilih.

Di bagian Data, pilih Semua, lalu klik Lanjutkan.

Di Configuration, tetapkan Data connector name ke drive, lalu klik Continue setelah meninjau dan menyetujui biaya yang mungkin berlaku.

Di Harga, pilih model harga yang Anda inginkan, lalu klik Buat. Harga umum direkomendasikan dalam konteks codelab ini.
Anda akan otomatis dialihkan ke Data Stores tempat Anda dapat melihat penyimpanan data yang baru ditambahkan.

Buat penyimpanan data Google Kalender:

Klik + Create data store.
Di Sumber, telusuri Google Kalender, lalu klik Pilih.
Di bagian Actions, klik Skip.
Di bagian Konfigurasi, tetapkan Nama konektor data ke calendar.
Klik Buat.
Anda akan otomatis dialihkan ke Data Stores tempat Anda dapat melihat penyimpanan data yang baru ditambahkan.

Buat penyimpanan data Google Gmail:

Klik + New data store.
Di Sumber, telusuri Google Gmail, lalu klik Pilih.
Di bagian Actions, klik Skip.
Di bagian Konfigurasi, tetapkan Nama konektor data ke gmail.
Klik Buat.
Anda akan otomatis dialihkan ke Data Stores tempat Anda dapat melihat penyimpanan data yang baru ditambahkan.

3. Aplikasi Vertex AI Search

Agen ini memungkinkan pengguna menelusuri data dan mengambil tindakan untuk Workspace dalam bahasa alami mereka. Mengandalkan elemen berikut:

Model: Gemini.
Data & tindakan: Penyimpanan data Vertex AI untuk Google Workspace (Kalender, Gmail, Drive).
Host agen: Vertex AI Search.
UI: Widget Web Vertex AI Search.

Tinjau konsep

Aplikasi Vertex AI Search

Aplikasi Vertex AI Search memberikan hasil penelusuran, tindakan, dan agen kepada pengguna akhir Anda. Istilah aplikasi dapat digunakan secara bergantian dengan istilah mesin dalam konteks API. Aplikasi harus terhubung ke penyimpanan data agar dapat menggunakan data dari penyimpanan data tersebut untuk menayangkan hasil penelusuran, jawaban, atau tindakan.

Widget Web Vertex AI Search adalah komponen UI bawaan yang dapat disesuaikan dan memungkinkan developer menyematkan kotak penelusuran dan antarmuka hasil yang didukung AI langsung ke situs dengan sedikit coding.

Pratinjau Vertex AI Search

Pratinjau Vertex AI Search adalah lingkungan pengujian bawaan dalam Konsol Google Cloud yang memungkinkan developer memvalidasi konfigurasi penelusuran dan jawaban generatif sebelum men-deploy setelan yang sama secara lancar ke widget web Vertex AI Search yang siap produksi.

Meninjau arsitektur solusi

Buat aplikasi

Buka AI Applications > Apps dari Konsol Cloud, lalu ikuti langkah-langkah berikut:

Klik + Buat aplikasi.
Di Type, di bagian Custom search (general), klik Create.

Di Konfigurasi, centang Fitur edisi Enterprise dan Respons Generatif setelah meninjau dan menyetujui harga.
Tetapkan Nama aplikasi ke codelab.
ID dibuat berdasarkan nama dan ditampilkan di bawah kolom, salin ID tersebut.
Tetapkan Company name ke Codelab.
Tetapkan Multi-region ke global (Global).
Klik Lanjutkan.

Di bagian Data, pilih penyimpanan data drive, gmail, dan calendar, lalu klik Lanjutkan.

Di Harga, pilih model harga yang Anda inginkan, lalu klik Buat. Harga umum direkomendasikan dalam konteks codelab ini.
Aplikasi dibuat dan Anda akan otomatis dialihkan ke AI Applications > Apps > codelab > App overview.
Buka Connected data stores.
Setelah beberapa menit, semua status penyimpanan data yang terhubung akan menjadi Aktif.

Buka Konfigurasi.
Di tab UI, tetapkan Jenis penelusuran ke Telusuri dengan tindak lanjut, lalu klik Simpan dan publikasikan.

Coba aplikasi

Buka Preview, Web Widget akan ditampilkan.
Dalam percakapan, ketik Do I have any meetings today?, lalu tekan enter.
Dalam percakapan, ketik Did I receive an email on March 1st 2026?, lalu tekan enter.
Dalam percakapan, ketik Give me the title of the latest Drive file I created, lalu tekan enter.

4. Agen kustom

Agen ini memungkinkan pengguna menelusuri data dan melakukan tindakan untuk Workspace dalam bahasa alami mereka menggunakan alat dan aturan kustom. Mengandalkan elemen berikut:

Model: Gemini.
Data & tindakan: Penyimpanan data Vertex AI untuk Google Workspace (Kalender, Gmail, Drive), server Model Context Protocol (MCP) Vertex AI Search yang dikelola Google, fungsi alat kustom untuk mengirim pesan Google Chat (melalui Google Chat API).
Alat pembuatan agen: Agent Development Kit (ADK).
Host agen: Vertex AI Agent Engine.
UI: ADK Web.

Tinjau konsep

Agent Development Kit (ADK)

Agent Development Kit (ADK) adalah rangkaian alat dan framework khusus yang dirancang untuk menyederhanakan pembuatan agen AI otonom dengan menyediakan modul siap pakai untuk penalaran, pengelolaan memori, dan integrasi alat.

Model Context Protocol (MCP)

Model Context Protocol (MCP) adalah standar terbuka yang dirancang untuk memungkinkan integrasi yang lancar dan aman antara aplikasi AI dan berbagai sumber data atau alat melalui antarmuka "plug-and-play" universal.

Alat Fungsi

Alat fungsi adalah rutin yang dapat dieksekusi yang telah ditentukan sebelumnya yang dapat dipicu oleh model AI untuk melakukan tindakan tertentu atau mengambil data real-time dari sistem eksternal, sehingga memperluas kemampuannya di luar pembuatan teks sederhana.

ADK Web

Web ADK adalah UI dev bawaan yang disertakan dengan ADK SDK untuk mempermudah pengembangan dan proses debug.

Tinjau arsitektur solusi

Tinjau kode sumber

agent.py

...
MODEL = "gemini-2.5-flash"

# Access token for authentication
ACCESS_TOKEN = os.environ.get("ACCESS_TOKEN")
if not ACCESS_TOKEN:
    raise ValueError("ACCESS_TOKEN environment variable must be set")

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def send_direct_message(email: str, message: str) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=ACCESS_TOKEN)
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT,
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    ),
    tool_filter=['search']
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

Download Kode Sumber

Download repositori GitHub ini.

Di terminal, buka direktori solutions/enterprise-ai-agent-local.

Aktifkan API

Solusi ini memerlukan pengaktifan API tambahan:

Di konsol Google Cloud, aktifkan Vertex AI, Cloud Resource Manager, dan Google Chat API:

Klik Menu ☰ > APIs & Services > Enabled APIs & Services, lalu konfirmasi bahwa Vertex AI API, Cloud Resource Manager API, dan Google Chat API ada dalam daftar.

Solusi ini memerlukan konfigurasi layar izin:

Di konsol Google Cloud, klik Menu ☰ > Google Auth platform > Branding.

Klik Mulai.
Di bagian App Information, tetapkan App name ke Codelab .
Di bagian Email dukungan pengguna, pilih alamat email dukungan yang dapat dihubungi pengguna jika mereka memiliki pertanyaan tentang izin mereka.
Klik Berikutnya.
Di bagian Audiens, pilih Internal.
Klik Berikutnya.
Di bagian Informasi Kontak, masukkan Alamat email tempat Anda dapat menerima notifikasi tentang perubahan apa pun pada project Anda.
Klik Berikutnya.
Di bagian Selesai, tinjau Kebijakan Data Pengguna Layanan Google API dan jika Anda setuju, pilih Saya menyetujui Layanan Google API: Kebijakan Data Pengguna.
Klik Lanjutkan, lalu Buat.

Konfigurasi disimpan dan Anda akan otomatis dialihkan ke Google Auth Platform > Overview.

Untuk mempelajari lebih lanjut, lihat panduan lengkap Mengonfigurasi izin OAuth.

Buat kredensial klien OAuth

Buat klien OAuth aplikasi Desktop baru untuk mengautentikasi pengguna di lingkungan lokal:

Di konsol Google Cloud, klik Menu ☰ > Google Auth platform > Clients.

Klik + Buat klien.
Untuk Application type, pilih Desktop app.
Tetapkan Name ke codelab.
Klik Buat. Kredensial yang baru dibuat akan muncul.
Klik Download JSON dan simpan file sebagai client_secret.json di direktori solutions/enterprise-ai-agent-local.

Mengaktifkan MCP Vertex AI Search

Di terminal, jalankan:

gcloud beta services mcp enable discoveryengine.googleapis.com \
     --project=$(gcloud config get-value project)

Mengonfigurasi aplikasi Chat

Di Konsol Google Cloud, telusuri Google Chat API di kolom penelusuran Google Cloud, klik Google Chat API, klik Manage, lalu klik Configuration.

Tetapkan Nama aplikasi dan Deskripsi ke Vertex AI.
Tetapkan Avatar URL ke https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
Batalkan pilihan Aktifkan fitur Interaktif, lalu klik Nonaktifkan di dialog modal yang muncul.
Pilih Log errors to Logging.
Klik Simpan.

Menjalankan Agen di Web ADK

Di terminal, buka direktori solutions/enterprise-ai-agent-local, lalu jalankan:

# 1. Authenticate with all the required scopes
gcloud auth application-default login \
  --client-id-file=client_secret.json \
   --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.messages

# 2. Configure environment
export ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export GOOGLE_CLOUD_LOCATION=us-central1

# 3. Create and activate a new virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 4. Install poetry and project dependencies
pip install poetry
poetry install

# 5. Start ADK Web
adk web

Coba agen

Di browser Internet, buka situs ADK.
Dalam percakapan, ketik Please find my meetings for today, I need their titles and links, lalu tekan enter.
Agen akan menjawab dengan daftar acara Kalender (bergantung pada akun pengguna).
Dalam percakapan, ketik Please send a Chat message to someone@example.com with the following text: Hello!, lalu tekan enter.
Agen akan menjawab dengan pesan konfirmasi.

5. Agent sebagai add-on Google Workspace

Agen ini memungkinkan pengguna menelusuri data untuk Workspace dalam bahasa alami mereka dalam konteks UI aplikasi Workspace. Mengandalkan elemen berikut:

Model: Gemini.
Data & tindakan: Penyimpanan data Vertex AI untuk Google Workspace (Kalender, Gmail, Drive), server Model Context Protocol (MCP) Vertex AI Search yang dikelola Google, fungsi alat kustom untuk mengirim pesan Google Chat (melalui Google Chat API).
Alat pembuatan agen: Agent Development Kit (ADK).
Host agen: Vertex AI Agent Engine.
UI: Add-on Google Workspace untuk Chat dan Gmail (dapat diperluas dengan mudah ke Kalender, Drive, Dokumen, Spreadsheet, dan Slide).
Add-on Google Workspace: Apps Script, Vertex AI Agent Engine API, kontekstual (pesan Gmail yang dipilih).

Tinjau konsep

Add-on Google Workspace

Add-on Google Workspace adalah aplikasi yang disesuaikan yang memperluas satu atau beberapa aplikasi Google Workspace (Gmail, Chat, Kalender, Dokumen, Drive, Meet, Spreadsheet, dan Slide).

Apps Script

Apps Script adalah platform JavaScript berbasis cloud yang didukung oleh Google Drive yang memungkinkan Anda berintegrasi dengan dan mengotomatiskan tugas di seluruh produk Google.

Framework Kartu Google Workspace

Framework kartu di Google Workspace memungkinkan developer membuat antarmuka pengguna yang interaktif dan kaya. Dengan library ini, Anda dapat membuat kartu yang teratur dan menarik secara visual yang dapat menyertakan teks, gambar, tombol, dan widget lainnya. Kartu ini meningkatkan pengalaman pengguna dengan memberikan informasi terstruktur dan memungkinkan tindakan cepat langsung dalam aplikasi Workspace.

Meninjau arsitektur solusi

Tinjau kode sumber

Agent

agent.py

...
MODEL = "gemini-2.5-flash"

# Client injects a bearer token into the ToolContext state.
# The key pattern is "CLIENT_AUTH_NAME_<random_digits>".
# We dynamically parse this token to authenticate our MCP and API calls.
CLIENT_AUTH_NAME = "enterprise-ai"

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def _get_access_token_from_context(tool_context: ToolContext) -> str:
    """Helper method to dynamically parse the intercepted bearer token from the context state."""
    escaped_name = re.escape(CLIENT_AUTH_NAME)
    pattern = re.compile(fr"^{escaped_name}_\d+$")
    # Handle ADK varying state object types (Raw Dict vs ADK State)
    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]:
    token = _get_access_token_from_context(tool_context)
    return {"Authorization": f"Bearer {token}"}

def send_direct_message(email: str, message: str, tool_context: ToolContext) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=_get_access_token_from_context(tool_context))
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT
    ),
    tool_filter=['search'],
    # The auth_header_provider dynamically injects the bearer token from the ToolContext
    # into the MCP call for authentication.
    header_provider=auth_header_provider
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

Klien

appsscript.json

...
"addOns": {
    "common": {
      "name": "Vertex AI",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png"
    },
    "chat": {},
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onAddonEvent"
        }
      ]
    }
  },
  "oauthScopes": [
   "https://www.googleapis.com/auth/script.external_request",
   "https://www.googleapis.com/auth/cloud-platform",
   "https://www.googleapis.com/auth/gmail.addons.execute",
   "https://www.googleapis.com/auth/gmail.addons.current.message.readonly"
 ]
...

Chat.gs

...
// Service that handles Google Chat operations.

// Handle incoming Google Chat message events, actions will be taken via Google Chat API calls
function onMessage(event) {
  if (isInDebugMode()) {
    console.log(`MESSAGE event received (Chat): ${JSON.stringify(event)}`);
  }
  // Extract data from the event.
  const chatEvent = event.chat;
  setChatConfig(chatEvent.messagePayload.space.name);

  // Request AI agent to answer the message
  requestAgent(chatEvent.messagePayload.message);
  // Respond with an empty response to the Google Chat platform to acknowledge execution
  return null; 
}

// --- Utility functions ---

// The Chat direct message (DM) space associated with the user
const SPACE_NAME_PROPERTY = "DM_SPACE_NAME"

// Sets the Chat DM space name for subsequent operations.
function setChatConfig(spaceName) {
  const userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty(SPACE_NAME_PROPERTY, spaceName);
  console.log(`Space is set to ${spaceName}`);
}

// Retrieved the Chat DM space name to sent messages to.
function getConfiguredChat() {
  const userProperties = PropertiesService.getUserProperties();
  return userProperties.getProperty(SPACE_NAME_PROPERTY);
}

// Finds the Chat DM space name between the Chat app and the given user.
function findChatAppDm(userName) {
  return Chat.Spaces.findDirectMessage(
    { 'name': userName },
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

// Creates a Chat message in the configured space.
function createMessage(message) {
  const spaceName = getConfiguredChat();
  console.log(`Creating message in space ${spaceName}...`);
  return Chat.Spaces.Messages.create(
    message,
    spaceName,
    {},
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

...
// Service that handles Gmail operations.

// Triggered when the user opens the Gmail Add-on or selects an email.
function onAddonEvent(event) {
  // If this was triggered by a button click, handle it
  if (event.parameters && event.parameters.action === 'send') {
    return handleSendMessage(event);
  }

  // Otherwise, just render the default initial sidebar
  return createSidebarCard();
}

// Creates the standard Gmail sidebar card consisting of a text input and send button.
// Optionally includes an answer section if a response was generated.
function createSidebarCard(optionalAnswerSection) {
  const card = CardService.newCardBuilder();
  const actionSection = CardService.newCardSection();

  // Create text input for the user's message
  const messageInput = CardService.newTextInput()
    .setFieldName("message")
    .setTitle("Message")
    .setMultiline(true);

  // Create action for sending the message
  const sendAction = CardService.newAction()
    .setFunctionName('onAddonEvent')
    .setParameters({ 'action': 'send' });

  const sendButton = CardService.newTextButton()
    .setText("Send message")
    .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
    .setOnClickAction(sendAction);

  actionSection.addWidget(messageInput);
  actionSection.addWidget(CardService.newButtonSet().addButton(sendButton));

  card.addSection(actionSection);

  // Attach the response at the bottom if we have one
  if (optionalAnswerSection) {
    card.addSection(optionalAnswerSection);
  }

  return card.build();
}

// Handles clicks from the Send message button.
function handleSendMessage(event) {
  const commonEventObject = event.commonEventObject || {};
  const formInputs = commonEventObject.formInputs || {};
  const messageInput = formInputs.message;

  let userMessage = "";
  if (messageInput && messageInput.stringInputs && messageInput.stringInputs.value.length > 0) {
    userMessage = messageInput.stringInputs.value[0];
  }

  if (!userMessage || userMessage.trim().length === 0) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Please enter a message."))
      .build();
  }

  let finalQueryText = `USER MESSAGE TO ANSWER: ${userMessage}`;

  // If we have an email selected in Gmail, append its content as context
  if (event.gmail && event.gmail.messageId) {
    try {
      GmailApp.setCurrentMessageAccessToken(event.gmail.accessToken);
      const message = GmailApp.getMessageById(event.gmail.messageId);

      const subject = message.getSubject();
      const bodyText = message.getPlainBody() || message.getBody();

      finalQueryText += `\n\nEMAIL THE USER HAS OPENED ON SCREEN:\nSubject: ${subject}\nBody:\n---\n${bodyText}\n---`;
    } catch (e) {
      console.error("Could not fetch Gmail context: " + e);
      // Invalidate the token explicitly so the next prompt requests the missing scopes
      ScriptApp.invalidateAuth();

      CardService.newAuthorizationException()
        .setResourceDisplayName("Enterprise AI")
        .setAuthorizationUrl(ScriptApp.getAuthorizationUrl())
        .throwException();
    }
  }

  try {
    const response = queryAgent({ text: finalQueryText });

    // We leverage the 'showdown' library to parse the LLM's Markdown output into HTML
    // We also substitute markdown listings with arrows and adjust newlines for clearer rendering in the sidebar
    let displayedText = substituteListingsFromMarkdown(response.text);
    displayedText = new showdown.Converter().makeHtml(displayedText).replace(/\n/g, '\n\n');

    const textParagraph = CardService.newTextParagraph();
    textParagraph.setText(displayedText);

    const answerSection = CardService.newCardSection()
      .addWidget(textParagraph);

    const updatedCard = createSidebarCard(answerSection);

    return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();

  } catch (err) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Error fetching response: " + err.message))
      .build();
  }
}
...

AgentHandler.gs

...
// Service that handles Vertex AI Agent operations.

// Submits a query to the AI agent and returns the response string synchronously
function queryAgent(input) {
 let systemPrompt = "SYSTEM PROMPT START Do not respond with tables but use bullet points instead." +
   " Do not ask the user follow-up questions or converse with them as history is not kept in this interface." +
   " SYSTEM PROMPT END\n\n";

 const requestPayload = {
   "class_method": "async_stream_query",
   "input": {
     "user_id": "vertex_ai_add_on",
     "message": { "role": "user", "parts": [{ "text": systemPrompt + input.text }] },
     "state_delta": {
       "enterprise-ai_999": `${ScriptApp.getOAuthToken()}`
     }
   }
 };

 const responseContentText = UrlFetchApp.fetch(
   `https://${getLocation()}-aiplatform.googleapis.com/v1/${getReasoningEngine()}:streamQuery?alt=sse`,
   {
     method: 'post',
     headers: { 'Authorization': `Bearer ${ScriptApp.getOAuthToken()}` },
     contentType: 'application/json',
     payload: JSON.stringify(requestPayload),
     muteHttpExceptions: true
   }
 ).getContentText();
  if (isInDebugMode()) {
   console.log(`Response: ${responseContentText}`);
 }

 const events = responseContentText.split('\n').map(s => s.replace(/^data:\s*/, '')).filter(s => s.trim().length > 0);
 console.log(`Received ${events.length} agent events.`);

 let author = "default";
 let answerText = "";
 for (const eventJson of events) {
   if (isInDebugMode()) {
     console.log("Event: " + eventJson);
   }
   const event = JSON.parse(eventJson);

   // Retrieve the agent responsible for generating the content
   author = event.author;
  
   // Ignore events that are not useful for the end-user
   if (!event.content) {
     console.log(`${author}: internal event`);
     continue;
   }

   // Handle text answers
   const parts = event.content.parts || [];
   const textPart = parts.find(p => p.text);
   if (textPart) {
     answerText += textPart.text;
   }
 }
 return { author: author, text: answerText };
}
...

Men-deploy Agen di Vertex AI Agent Engine

Di terminal, buka direktori solutions/enterprise-ai-agent dari sumber yang didownload pada langkah sebelumnya, lalu jalankan:

# 1. Create and activate a new virtual environment
deactivate
python3 -m venv .venv
source .venv/bin/activate

# 2. Install poetry and project dependencies
pip install poetry
poetry install

# 3. Deploy the agent
adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Enterprise AI" \
  enterprise_ai

Saat Anda melihat baris Deploying to agent engine... di log, buka terminal baru dan jalankan perintah berikut untuk menambahkan izin yang diperlukan ke Vertex AI Reasoning Engine Service Agent:

# 1. Get the current Project ID
PROJECT_ID=$(gcloud config get-value project)

# 2. Extract the Project Number for that ID
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# 3. Construct the Service Account name
SERVICE_ACCOUNT="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# 4. Apply the IAM policy binding
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:$SERVICE_ACCOUNT" \
     --role="roles/discoveryengine.viewer"

Tunggu hingga perintah adk deploy selesai, lalu salin nama resource agen yang baru di-deploy dari output perintah berwarna hijau.

Mulai akun layanan

Di konsol Google Cloud, ikuti langkah-langkah berikut:

Klik Menu ☰ > IAM & Admin > Service Accounts > + Create service account.

Tetapkan Service account name ke vertexai-add-on.

Klik Selesai. Anda akan dialihkan ke halaman Service accounts dan dapat melihat akun layanan yang dibuat.

Pilih akun layanan yang baru dibuat, lalu tab Kunci.
Klik Tambahkan kunci, lalu Buat kunci baru.
Pilih JSON, lalu klik Buat.

Dialog akan ditutup dan pasangan kunci publik/pribadi yang baru dibuat akan otomatis didownload ke lingkungan lokal Anda sebagai file JSON.

Membuat dan Mengonfigurasi Project Apps Script

Klik tombol berikut untuk membuka project Apps Script add-on AI Enterprise:

Klik Ringkasan > Buat salinan.
Di project Apps Script Anda, klik Setelan Project > Edit properti skrip > Tambahkan properti skrip untuk menambahkan properti skrip.
Tetapkan REASONING_ENGINE_RESOURCE_NAME ke nama resource agen Vertex AI yang disalin pada langkah sebelumnya. Formatnya adalah sebagai berikut:

projects/<PROJECT_NUMBER>/locations/us-central1/reasoningEngines/<AGENT_ID>

Tetapkan APP_SERVICE_ACCOUNT_KEY ke kunci JSON dari file akun layanan yang didownload pada langkah sebelumnya.
Klik Simpan properti skrip

Men-deploy ke Gmail dan Chat

Di project Apps Script Anda, ikuti langkah-langkah berikut:

Klik Deploy > Test deployments, lalu Install. Sekarang tersedia di Gmail.
Klik Copy di bagian Head Deployment ID.

Di konsol Google Cloud, ikuti langkah-langkah berikut:

Telusuri Google Chat API di kolom penelusuran Google Cloud, klik Google Chat API, klik Manage, lalu klik Configuration.

Pilih Aktifkan fitur Interaktif.
Batalkan pilihan Join spaces and group conversations.
Di bagian Connection settings, pilih Apps Script.
Tetapkan Deployment ID ke Head Deployment ID yang disalin di langkah sebelumnya.
Di bagian Visibilitas, pilih Jadikan aplikasi Chat ini tersedia untuk orang dan grup tertentu di Domain Workspace Anda, lalu masukkan alamat email Anda.
Klik Simpan.

Coba Add-On

Buka Google Chat di tab baru, lalu ikuti langkah-langkah berikut:

Buka ruang pesan langsung dengan aplikasi Chat Vertex AI.

Klik Konfigurasi dan ikuti alur autentikasi.
Ketik What are my meetings for today?, lalu tekan enter. Aplikasi Chat Vertex AI akan membalas dengan hasil.

Buka Gmail di tab baru, lalu ikuti langkah-langkah berikut:

Kirim email ke diri Anda sendiri dengan Subjek yang disetel ke We need to talk dan Isi yang disetel ke Are you available today between 8 and 9 AM?
Buka pesan email yang baru diterima.
Buka sidebar add-on Vertex AI.
Tetapkan Message ke Do I have any meeting conflicts?
Klik Kirim pesan.
Jawaban ditampilkan setelah tombol.

6. Pembersihan

Hapus project Google Cloud

Agar tidak menimbulkan biaya pada Akun Google Cloud Anda untuk resource yang digunakan dalam codelab ini, sebaiknya hapus project Google Cloud tersebut.

Di konsol Google Cloud, ikuti langkah-langkah berikut:

Klik Menu ☰ > IAM & Admin > Settings.

Klik Shut down.
Masukkan project ID.
Klik Shut down anyway.

7. Selamat

Selamat! Anda telah membangun solusi yang memanfaatkan kecanggihan integrasi Vertex AI dan Google Workspace untuk pekerja.

Apa langkah selanjutnya?

Kami hanya menunjukkan kasus penggunaan yang paling umum dalam codelab ini, tetapi ada banyak area ekspansi yang mungkin ingin Anda pertimbangkan dalam solusi Anda, seperti berikut:

Gunakan alat developer yang didukung AI seperti Gemini CLI dan Antigravity.
Terintegrasi dengan framework dan alat agen lainnya seperti MCP kustom, panggilan fungsi kustom, dan UI generatif.
Mengintegrasikan dengan model AI lain, termasuk model kustom, yang dihosting di platform khusus seperti Vertex AI.
Mengintegrasikan dengan agen lain, yang dihosting di platform khusus seperti Dialogflow atau oleh pihak ketiga melalui Cloud Marketplace.
Publikasikan agen di Cloud Marketplace untuk mendukung tim, organisasi, atau pengguna publik.

Pelajari lebih lanjut

Ada banyak referensi yang tersedia untuk developer seperti video YouTube, situs dokumentasi, contoh kode, dan tutorial:

Mengintegrasikan Agen Vertex AI dengan Google Workspace

1. Sebelum memulai

Apa itu Vertex AI?

Apa itu Google Workspace?

Jenis integrasi kustom apa?

Prasyarat

Yang akan Anda bangun

Aplikasi Vertex AI Search

Agen kustom

Agen sebagai add-on Google Workspace

Yang akan Anda pelajari

2. Siapkan

Tinjau konsep

Aplikasi Vertex AI

Penyimpanan data Vertex AI

Mulai setelan Aplikasi Vertex AI

Mengaktifkan API

Membuat penyimpanan data

3. Aplikasi Vertex AI Search

Tinjau konsep

Aplikasi Vertex AI Search

Widget Web Vertex AI Search

Pratinjau Vertex AI Search

Meninjau arsitektur solusi

Buat aplikasi

Mengonfigurasi Widget Web

Coba aplikasi

4. Agen kustom

Tinjau konsep

Agent Development Kit (ADK)

Model Context Protocol (MCP)

Alat Fungsi

ADK Web

Tinjau arsitektur solusi

Tinjau kode sumber

agent.py

Download Kode Sumber

Aktifkan API

Mengonfigurasi layar izin OAuth

Buat kredensial klien OAuth

Mengaktifkan MCP Vertex AI Search

Mengonfigurasi aplikasi Chat

Menjalankan Agen di Web ADK

Coba agen

5. Agent sebagai add-on Google Workspace

Tinjau konsep

Add-on Google Workspace

Apps Script

Framework Kartu Google Workspace

Meninjau arsitektur solusi

Tinjau kode sumber

Agent

agent.py

Klien

appsscript.json

Chat.gs

Sidebar.gs

AgentHandler.gs

Men-deploy Agen di Vertex AI Agent Engine

Mulai akun layanan

Membuat dan Mengonfigurasi Project Apps Script

Men-deploy ke Gmail dan Chat

Coba Add-On

6. Pembersihan

Hapus project Google Cloud

7. Selamat

Apa langkah selanjutnya?

Pelajari lebih lanjut