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 agentik kustom yang terintegrasi secara mendalam dengan infrastruktur skala global.

• Akses Model Garden: Pilih dari lebih dari 150 model dasar, termasuk seluruh rangkaian model Gemini, model pihak ketiga, dan model open source khusus untuk menemukan model yang paling sesuai untuk tugas agen tertentu.
• Merancang orkestrasi yang kompleks: Vertex AI menyediakan framework untuk mendesain agen otonom yang menggunakan penalaran untuk merencanakan, menjalankan tugas bertahap, dan memanggil API eksternal.
• Grounding tingkat perusahaan: Hubungkan agen ke data bisnis aktif, termasuk RAG (Retrieval-Augmented Generation) berperforma tinggi untuk menghilangkan halusinasi dan memastikan akurasi faktual.
• DevOps: Mengintegrasikan 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: Menskalakan beban kerja berbasis agen dengan mudah di seluruh cluster TPU dan GPU kelas dunia Google, sehingga memastikan performa latensi rendah bahkan untuk aplikasi global yang paling menuntut.

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 loop umpan balik yang efektif. 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 cerdas: Penyimpanan data, API, dan server MCP yang dikelola Google (yang dikelola Google dan kustom) memungkinkan agen mengakses data Workspace dengan 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 admin.
• Integrasi native: Add-on Workspace menjembatani kesenjangan antara sistem AI dan aplikasi seperti Chat dan Gmail, baik melalui komponen UI khusus maupun proses latar belakang. Hal ini memungkinkan agen bertemu dengan pengguna di mana pun 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 mentransformasi 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+ terinstal, lihat petunjuk di situs resmi Python.

Yang akan Anda buat

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 melakukan 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.

Akses mudah ke codelab ini

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

Lakukan inisialisasi setelan Aplikasi Vertex AI untuk mengaktifkan pembuatan agen.

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

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

Buka Vertex AI Applications

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

6. Pilih Google Identity, lalu klik Save.

Mengaktifkan API

Penyimpanan data Vertex AI Workspace memerlukan pengaktifan API:

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

Aktifkan Calendar, Gmail, dan People API

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

Buka APIs & Services > Enabled APIs & Services

Membuat penyimpanan data

Buat penyimpanan data Google Drive:

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

Buka Vertex AI Applications > Data Stores

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

4. Di bagian Data, pilih Semua, lalu klik Lanjutkan.

5. Di Konfigurasi, tetapkan Nama konektor data ke drive, lalu klik Lanjutkan setelah meninjau dan menyetujui biaya yang mungkin berlaku.

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

Buat penyimpanan data Google Kalender:

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

Buat penyimpanan data Google Gmail:

1. Klik + New data store.
2. Di bagian Sumber, telusuri Google Gmail, lalu klik Pilih.
3. Di bagian Actions, klik Skip.
4. Di bagian Konfigurasi, tetapkan Nama konektor data ke gmail.
5. Klik Buat.
6. 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 melakukan 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

Widget Web Vertex AI Search adalah komponen UI bawaan yang dapat disesuaikan dan memungkinkan developer menyematkan kotak penelusuran yang didukung AI dan antarmuka hasil 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

Buat aplikasi penelusuran baru untuk menyambungkan penyimpanan data Anda.

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

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

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

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

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

Mengonfigurasi Widget Web

Mengonfigurasi tampilan visual dan perilaku widget penelusuran.

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

Coba aplikasi

Uji aplikasi penelusuran langsung di konsol Google Cloud.

1. Buka Preview, Web Widget akan ditampilkan.
2. Dalam percakapan, ketik Do I have any meetings today?, lalu tekan enter.
3. Dalam percakapan, ketik Did I receive an email on March 1st 2026?, lalu tekan enter.
4. 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 pen-debug-an.

Tinjau arsitektur solusi

Tinjau kode sumber

agent.py

Kode berikut melakukan autentikasi dengan Vertex AI, menginisialisasi alat MCP dan Chat API Vertex AI Search, serta menentukan perilaku agen.

1. Autentikasi: Mengambil ACCESS_TOKEN dari variabel lingkungan untuk mengautentikasi panggilan MCP dan API.
2. Penyiapan Alat: Menginisialisasi vertexai_mcp, sekumpulan alat yang terhubung ke server Model Context Protocol (MCP) Vertex AI Search, dan alat send_direct_message. Hal ini memberi agen kemampuan untuk menelusuri penyimpanan data yang terhubung dan mengirim pesan Google Chat.
3. Definisi Agen: Menentukan root_agent menggunakan model gemini-2.5-flash. Petunjuk ini memberi tahu agen untuk memprioritaskan penggunaan alat penelusuran untuk pengambilan informasi dan alat send_direct_message untuk tindakan, sehingga secara efektif meng-grounding agen pada data perusahaan Anda.

...
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 kode contoh ke lingkungan lokal Anda untuk memulai.

1. Download repositori GitHub ini.

file_downloadDownload zip

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

Aktifkan API

Solusi ini memerlukan pengaktifan API tambahan:

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

Mengaktifkan Vertex AI API, Cloud Resource Manager API, dan Google Chat API

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

Buka APIs & Services > Enabled APIs & Services

Mengonfigurasi layar izin OAuth

Solusi ini memerlukan konfigurasi layar izin:

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

Buka Branding

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

12. 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:

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

Buka Klien

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

Mengaktifkan MCP Vertex AI Search

1. Di terminal, jalankan:

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

Mengonfigurasi aplikasi Chat

Konfigurasi aplikasi Google Chat dengan detail informasi dasarnya.

1. Di Konsol Google Cloud, telusuri Google Chat API di kolom penelusuran Google Cloud, klik