Mengonfigurasi fitur Agent Platform untuk Cloud Run

Fitur Gemini Enterprise Agent Platform seperti Agent Identity dan Agent Registry menyediakan kemampuan bawaan untuk membangun, men-deploy, dan mengelola agen AI, server Model Context Protocol (MCP), dan alat. Dengan mengaktifkan fitur ini untuk resource Cloud Run, Anda dapat memanfaatkan identitas yang dikelola sistem dan pendaftaran otomatis untuk menyederhanakan penemuan dan keamanan untuk beban kerja agen Anda.

Panduan ini membahas cara:

Cloud Run mendukung fitur Agent Platform berikut:

  • Agent Identity: menetapkan identitas unik yang dapat diverifikasi secara kriptografis ke beban kerja Anda, sehingga memungkinkan koneksi yang aman ke agen, alat, dan Google Cloud API lainnya.
  • Agent Registry: secara otomatis mendaftarkan agen dan alat Anda agar dapat ditemukan oleh developer dan agen lain di organisasi Anda.

Sebelum memulai

  1. Login ke akun Anda. Google Cloud Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Instal Google Cloud CLI.

  5. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus terlebih dahulu login ke gcloud CLI dengan identitas gabungan Anda.

  6. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Instal Google Cloud CLI.

  10. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus terlebih dahulu login ke gcloud CLI dengan identitas gabungan Anda.

  11. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut: 

    gcloud init

  12. Aktifkan Cloud Run Admin API, Identity and Access Management API, Agent Registry API, dan App Hub API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Service Usage (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    Aktifkan API

  13. Pastikan Anda telah menyiapkan Agent Registry di project atau organisasi Anda.
  14. Instal dan lakukan inisialisasi gcloud CLI.
  15. Perbarui komponen: 
    gcloud components update
  16. Tinjau halaman harga Cloud Run untuk CPU, memori, dan traffic keluar jaringan. Ukuran total disk yang disediakan dan masa aktif instance yang menggunakannya akan berkontribusi pada biaya Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengonfigurasi fitur Agent Platform, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Kasus penggunaan

Gunakan fitur Agent Platform dengan Cloud Run dalam skenario berikut:

  • Autentikasi agen Anda ke agen, alat, dan Google Cloud API lainnya menggunakan identitas unik yang dikelola sistem dan terikat dengan siklus prosesnya.
  • Aktifkan penemuan otomatis agen dan server MCP dalam Agent Registry organisasi Anda.
  • Gunakan Identity-Aware Proxy sebagai kebijakan autentikasi untuk mengamankan server MCP.

Memahami jenis fungsional dan identitas

Anda mengonfigurasi fitur Agent Platform dengan menetapkan properti fungsional dan identitas pada resource Cloud Run Anda.

Kedua properti ini mengontrol cara mendaftarkan dan mengidentifikasi beban kerja:

  • Jenis fungsional: mendeklarasikan tujuan utama beban kerja. Setelah ditetapkan, properti ini tidak dapat diubah atau dihapus. Anda menetapkan salah satu jenis fungsional berikut ke beban kerja Anda:
    • agent: menetapkan beban kerja sebagai agen AI. Beban kerja jenis ini harus menggunakan jenis agent-identity.
    • mcp-server: menetapkan beban kerja sebagai server MCP yang dikelola pengguna. Jenis ini dapat menggunakan jenis identitas yang didukung.
  • Jenis identitas: menentukan jenis identitas yang ditetapkan ke beban kerja. Setelah ditetapkan, properti ini tidak dapat diubah atau dihapus. Anda menetapkan salah satu jenis identitas berikut ke beban kerja Anda:
    • agent-identity: menetapkan identitas agen yang dikelola sistem dan didesain untuk agen. Saat Anda men-deploy dengan agent-identity, Agent Platform akan mengaktifkan sertifikat identitas secara default. Untuk menonaktifkan, perbarui layanan Anda dengan tanda --no-identity-certificate atau tetapkan anotasi run.googleapis.com/identity-certificate-enabled: "false". Ikuti panduan untuk melakukan autentikasi ke alat dan resource bagi agen yang bertindak atas otoritasnya sendiri atau atas nama pengguna akhir. Untuk memahami konsep inti dan manfaat keamanan identitas agen yang dikelola sistem, pelajari lebih lanjut Agent Identity.
    • service-account: menggunakan akun layanan Google Cloud standar.

Perilaku konfigurasi

Perilaku properti fungsional dan identitas bergantung pada kombinasi yang Anda pilih:

Jenis fungsional Jenis identitas Perilaku yang dihasilkan
agent agent-identity Beban kerja terdaftar sebagai agen di Agent Registry dan ditetapkan identitas agen yang dikelola sistem.
agent Lainnya atau tidak ditentukan Error. Beban kerja dengan functional-type=agent harus menggunakan identity-type=agent-identity.
mcp-server agent-identity, service-account, atau tidak ditentukan Beban kerja terdaftar sebagai server MCP (/mcpServers) di Agent Registry. Jika tidak ditentukan, setelan defaultnya adalah identitas akun layanan.
Tidak ditentukan service-account Beban kerja berjalan sebagai layanan atau tugas Cloud Run standar.

Mengonfigurasi fitur pada layanan dan tugas

Anda mengonfigurasi fitur Agent Platform pada layanan dan tugas Cloud Run menggunakan Google Cloud CLI.

Layanan

  • Untuk men-deploy agen, tentukan --functional-type=agent dan --identity-type=agent-identity:

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=agent \
    --identity-type=agent-identity

    Ganti kode berikut:

    • SERVICE_NAME: nama layanan Cloud Run Anda.
    • IMAGE_URL: referensi ke image container, misalnya, us-docker.pkg.dev/cloudrun/container/hello:latest. Jika Anda menggunakan Artifact Registry, repositori REPO_NAME harus sudah dibuat. URL mengikuti format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

  • Untuk memperbarui layanan yang sudah ada agar menggunakan Agent Identity:

    gcloud beta run services update SERVICE_NAME \
    --functional-type=agent \
    --identity-type=agent-identity \
    --no-traffic

    Ganti kode berikut:

    • SERVICE_NAME: nama layanan Cloud Run Anda.
    • ORGANIZATION_ID: ID organisasi Anda Google Cloud.
    • PROJECT_NUMBER: nomor Google Cloud project Anda.
    • REGION: region tempat layanan Anda di-deploy.

  • Untuk men-deploy server MCP yang dikelola pengguna, tentukan --functional-type=mcp-server. Anda dapat secara opsional menentukan jenis identitas menggunakan --identity-type:

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=mcp-server \
    --identity-type=IDENTITY_TYPE

    Ganti kode berikut:

    • SERVICE_NAME: nama layanan Cloud Run Anda.
    • IMAGE_URL: referensi ke image container, misalnya, us-docker.pkg.dev/cloudrun/container/hello:latest. Jika Anda menggunakan Artifact Registry, repositori REPO_NAME harus sudah dibuat. URL mengikuti format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • IDENTITY_TYPE: Opsional. Jenis identitas yang ditetapkan ke beban kerja. Tentukan agent-identity atau service-account. Setelan defaultnya adalah service-account.

Pekerjaan

  • Untuk membuat tugas agen, tentukan --functional-type=agent dan --identity-type=agent-identity:

    gcloud beta run jobs create JOB_NAME \
  --image=IMAGE_URL \
  --functional-type=agent \
  --identity-type=agent-identity

    Ganti kode berikut:

    • JOB_NAME: nama tugas Cloud Run Anda.
    • IMAGE_URL: referensi ke image container.

Melihat identitas yang ditetapkan

Anda dapat melihat identitas agen yang ditetapkan dari Google Cloud konsol atau gcloud CLI.

Layanan

Konsol

  1. Di Google Cloud konsol, buka Cloud Run:

    Buka Cloud Run

  2. Pilih Services dari menu navigasi Cloud Run, lalu klik layanan Anda.

  3. Klik tab Revisions , lalu pilih revisi.

  4. Klik tab Security.

Kolom Identity menampilkan identitas agen yang ditetapkan.

gcloud

Untuk melihat identitas agen, jelaskan revisi layanan Anda:

gcloud beta run revisions describe REVISION_NAME

Ganti REVISION_NAME dengan nama revisi layanan Anda.

Identitas agen yang ditetapkan ditampilkan dalam output.

Pekerjaan

Konsol

  1. Di Google Cloud konsol, buka Cloud Run:

    Buka Cloud Run

  2. Pilih Jobs dari menu navigasi Cloud Run, lalu klik tugas Anda.

  3. Klik tab Executions , lalu pilih eksekusi.

  4. Lihat detail eksekusi.

Kolom Identity menampilkan identitas agen yang ditetapkan.

gcloud

Untuk melihat identitas agen untuk eksekusi tugas, jelaskan eksekusi:

gcloud beta run jobs executions describe EXECUTION_NAME

Ganti EXECUTION_NAME dengan nama eksekusi tugas Anda.

Identitas agen yang ditetapkan ditampilkan dalam output.

Melihat agen atau MCP di Agent Registry

Saat Anda men-deploy resource Cloud Run dengan --functional-type=agent atau --functional-type=mcp-server, resource tersebut akan otomatis terdaftar di Agent Registry organisasi Anda.

  • Agen terdaftar di katalog agen (/agents).
  • Server MCP terdaftar di katalog server MCP (/mcpServers).

Untuk melihat agen dan alat terdaftar Anda di registry, serta mempelajari cara menyimpan dan menemukan agen dan alat Anda dengan aman, jelajahi Agent Registry.

Langkah berikutnya