Mengonfigurasi fitur Agent Platform untuk Cloud Run

Pratinjau — Mengonfigurasi fitur Platform Agen untuk Cloud Run

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Fitur Gemini Enterprise Agent Platform seperti Identitas Agen 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 agentik Anda.

Panduan ini membahas cara:

• Tetapkan peran IAM yang diperlukan
• Memahami jenis identitas dan fungsional
• Mengonfigurasi fitur untuk layanan dan tugas
• Melihat identitas yang ditetapkan
• Melihat agen dan alat terdaftar di Agent Registry

Cloud Run mendukung fitur Agent Platform berikut:

• Identitas Agen: menetapkan identitas unik yang dapat diverifikasi secara kriptografis ke workload 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

Login ke akun Google Cloud Anda. 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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Instal Google Cloud CLI.

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

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Instal Google Cloud CLI.

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

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

1. Aktifkan Cloud Run Admin API, Identity and Access Management API, Agent Registry API, dan Pusat Aplikasi API, jika ada yang belum diaktifkan.

   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 Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

   Aktifkan API

2. Pastikan Anda telah menyiapkan Agent Registry di project atau organisasi Anda.
3. Instal dan lakukan inisialisasi gcloud CLI.
4. Perbarui komponen:

   gcloud components update

5. Tinjau halaman harga Cloud Run untuk CPU, memori, dan traffic keluar jaringan. Seluruh ukuran disk yang disediakan dan masa aktif instance yang menggunakannya berkontribusi pada biaya Anda.

Peran yang diperlukan

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

• Untuk men-deploy dan mengelola resource Cloud Run: Admin Cloud Run (roles/run.admin)
• Untuk mengelola resource Pusat Aplikasi, salah satu hal berikut:
  • Admin Pusat Aplikasi (roles/apphub.admin)
  • Agent Registry API Admin (roles/apiregistry.admin)
• Untuk men-deploy dengan identitas tertentu, salah satu dari berikut ini:
  • Pengguna Akun Layanan IAM (roles/iam.serviceAccountUser)
  • IAM Service Account Admin (roles/iam.serviceAccountAdmin)

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:

• Mengautentikasi agen Anda ke agen, alat, dan Google Cloud API lainnya menggunakan identitas unik yang dikelola sistem dan terkait 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.

Dua properti ini mengontrol cara mendaftarkan dan mengidentifikasi workload:

• Jenis fungsional: mendeklarasikan tujuan utama workload. Setelah ditetapkan, properti ini tidak dapat diubah atau dibatalkan. Anda menetapkan salah satu jenis fungsional berikut untuk workload:
  • agent: menetapkan workload sebagai agen AI. Workload jenis ini harus menggunakan jenis agent-identity.
  • mcp-server: menetapkan workload sebagai server MCP yang dikelola pengguna. Jenis ini dapat menggunakan jenis identitas yang didukung.
• Jenis identitas: menentukan jenis identitas yang ditetapkan ke workload. Setelah ditetapkan, properti ini tidak dapat diubah atau dibatalkan. Anda menetapkan salah satu jenis identitas berikut ke workload Anda:
  • agent-identity: menetapkan identitas agen yang dikelola sistem dan dirancang untuk agen. Saat Anda men-deploy dengan agent-identity, Agent Platform mengaktifkan sertifikat identitas secara default. Untuk memilih tidak ikut, perbarui layanan Anda dengan flag --no-identity-certificate atau tetapkan anotasi run.googleapis.com/identity-certificate-enabled: "false". Ikuti panduan untuk mengautentikasi alat dan resource bagi agen yang bertindak atas otoritas mereka sendiri atau atas nama pengguna akhir. Untuk memahami konsep inti dan manfaat keamanan identitas agen yang dikelola sistem, pelajari lebih lanjut Identitas Agen.
  • 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	Workload terdaftar sebagai agen di Agent Registry dan diberi identitas agen yang dikelola sistem.
agent	Lainnya atau tidak ditentukan	Error. Workload dengan functional-type=agent harus menggunakan identity-type=agent-identity.
mcp-server	agent-identity, service-account, atau tidak ditentukan	Workload terdaftar sebagai server MCP (/mcpServers) di Agent Registry. Jika tidak ditentukan, 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 di 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 mengupdate layanan yang ada agar menggunakan Agent Identity:

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

  Penting: Saat Anda memperbarui layanan yang ada dari akun layanan ke agent-identity, Cloud Run akan menetapkan akun utama baru yang tidak mewarisi izin dari akun layanan sebelumnya. Untuk menghindari gangguan koneksi, gunakan Penganalisis Kebijakan untuk mengidentifikasi peran yang diperlukan dan menetapkannya terlebih dahulu ke pokok principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME sebelum memperbarui, atau perbarui layanan dengan --no-traffic untuk menetapkan izin sebelum memigrasikan traffic.

  Ganti kode berikut:

  • SERVICE_NAME: nama layanan Cloud Run Anda.
  • ORGANIZATION_ID: ID organisasi Google Cloud Anda.
  • PROJECT_NUMBER: nomor project Google Cloud 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 workload. Tentukan agent-identity atau service-account. Setelan defaultnya adalah service-account.

Pekerjaan

Catatan: Hanya layanan Cloud Run yang dapat diekspos sebagai server MCP. Tugas Cloud Run tidak dapat diekspos sebagai server MCP dan hanya mendukung jenis fungsional agent.

• 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 konsol Google Cloud atau gcloud CLI.

Layanan

Konsol

1. Di konsol Google Cloud , buka Cloud Run:

   Buka Cloud Run

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

3. Klik tab Revisi, lalu pilih revisi.

4. Klik tab Security.

Kolom Identitas 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 konsol Google Cloud , buka Cloud Run:

   Buka Cloud Run

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

3. Klik tab Eksekusi, lalu pilih eksekusi.

4. Lihat detail eksekusi.

Kolom Identitas 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 terdaftar secara otomatis di Agent Registry organisasi Anda.

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

Untuk melihat agen dan alat terdaftar Anda di registry, dan untuk mempelajari cara menyimpan dan menemukan agen dan alat Anda secara aman, pelajari Agent Registry.

Langkah berikutnya

• Pelajari cara mengautentikasi agen Anda ke API dan alat.
• Pelajari cara mengautentikasi server MCP untuk koneksi yang aman.
• Pelajari cara menghosting server MCP di Cloud Run.
• Gunakan Agent Development Kit untuk membangun dan mendaftarkan agen kustom di registry.
• Untuk membangun dan men-deploy agen yang sesuai dengan spesifikasi A2A, lihat Men-deploy agen A2A ke Cloud Run.
• Lihat panduan pemecahan masalah jika Anda mengalami masalah terkait pendaftaran agen atau penetapan identitas.