Batas lintas project

Batas pengelolaan lintas project (atau batas) memungkinkan Anda menemukan, mengelola, dan mengatur agen AI, server Model Context Protocol (MCP), dan alat di beberapa project Google Cloud . Agent Registry beroperasi dalam satu project tata kelola secara default, tetapi mengonfigurasi batas pengelolaan di Resource Manager memungkinkan project pengelolaan pusat menggabungkan agen, server MCP, dan alat di seluruh project anggota yang didistribusikan. Memahami cara batas pengelolaan menyusun peran project, agregasi resource, dan kontrol akses akan membantu Anda mendesain topologi multi-project yang skalabel.

Untuk mengonfigurasi batas pengelolaan, lihat Mengonfigurasi batas pengelolaan untuk beberapa project.

Model batas

Anda menentukan batas pengelolaan pada folder atau organisasi di Resource Manager:

  • Batasan seluruh folder atau seluruh organisasi: secara default, jika Anda membuat batasan pada folder atau organisasi tanpa mengonfigurasi filter tag, batasan tersebut akan mencakup semua project turunan dalam folder atau organisasi tersebut sebagai project anggota.
  • Batasan yang difilter tag (opsional): secara opsional, untuk mempartisi project turunan dalam folder atau organisasi menjadi beberapa batasan, Anda dapat memfilter keanggotaan batasan menggunakan tag Resource Manager. Misalnya, Anda dapat memisahkan lingkungan prod dan dev. Anda melampirkan tag ke Google Cloud project yang ingin Anda sertakan dalam setiap batasan. Jika project turunan dalam folder atau organisasi memiliki tag yang cocok dengan filter batasan, project tersebut akan menjadi project anggota dari batasan pengelolaan.

Saat Anda menggunakan tag untuk mempartisi batas pengelolaan, tag memberikan manfaat berikut:

  • Pendaftaran dinamis dan otomatis: lingkungan cloud sering mengubah project. Saat Anda memberi tag pada project dengan nilai tag yang terdaftar, seperti env=prod, Agent Registry akan otomatis menyertakan project tersebut sebagai project anggota dalam batasan tanpa memerlukan update manual pada definisi batasan.
  • Pemisahan dari hierarki folder: Struktur folder Resource Manager biasanya diatur untuk tujuan penagihan atau bisnis. Tag memisahkan definisi batas dari hierarki folder fisik, sehingga Anda dapat membuat perimeter pengelolaan lintas folder di folder atau organisasi induk.
  • Pewarisan dan skalabilitas: tag yang diterapkan ke organisasi atau folder otomatis diterapkan ke bawah hierarki resource ke folder dan project turunan. Model pewarisan ini memungkinkan Anda mendaftarkan seluruh cabang hierarki resource dengan satu penetapan tag.
  • Tata kelola terpusat: tag diatur oleh izin Identity and Access Management (IAM) terpusat. Dengan menggunakan tag untuk menentukan batas pengelolaan, Anda dapat mencegah setiap pengguna menambahkan atau menghapus project dari batas secara arbitrer.

Arsitektur dan referensi utama

Batas pengelolaan lintas project bergantung pada resource Resource Manager berikut:

  • Konfigurasi batas (resource BoundaryConfig): resource konfigurasi pada organisasi atau folder di Resource Manager yang menetapkan aturan partisi batas dalam folder atau organisasi tersebut. Jika Anda tidak menetapkan kunci tag pada resource BoundaryConfig, organisasi atau folder akan mendukung satu batas yang mencakup semua project turunannya. Untuk mempartisi project turunan menjadi beberapa batas yang difilter tag, resource BoundaryConfig menentukan kunci tag resource tunggal, seperti 123456789012/env, yang digunakan untuk mengevaluasi keanggotaan project dalam folder atau organisasi tersebut.

  • Batas (resource Boundary): perimeter project anggota dalam organisasi atau folder. Tanpa filter tag, batas mencakup semua project turunan di organisasi atau folder induk. Saat Anda mengonfigurasi kunci tag pada resource BoundaryConfig induk, resource Boundary menentukan filter nilai tag, seperti env=prod, dan project turunan yang mewarisi atau melampirkan nilai tag tersebut akan otomatis menjadi bagian dari batas. Karena resource BoundaryConfig induk menggunakan satu kunci tag dan project hanya dapat memiliki satu nilai tag yang efektif per kunci tag, project dapat menjadi bagian dari maksimal satu batas per folder atau organisasi induk.

  • Konfigurasi kemampuan (resource CapabilityConfig): resource yang ditentukan di organisasi, folder, atau project. Di level organisasi atau folder, kebijakan ini mengikat satu atau beberapa batasan ke project pengelolaan khusus dan menentukan kemampuan pengelolaan yang diaktifkan di seluruh batasan tersebut. Di level project, fitur ini memungkinkan kemampuan pengelolaan untuk satu project mandiri tanpa batasan. Untuk Agent Registry, Anda mengonfigurasi kemampuan AGENT_MANAGEMENT (Google Cloud CLI: agent-management), yang memungkinkan penemuan komponen terpusat, rollup penelusuran, dan tata kelola lintas project di Agent Registry, serta otomatis mengaktifkan agentregistry.googleapis.com di project pengelolaan.

Untuk mengetahui informasi selengkapnya tentang resource Resource Manager ini, lihat Ringkasan kemampuan dan batasan pengelolaan.

Diagram berikut mengilustrasikan cara resource Resource Manager menghubungkan project anggota ke project pengelolaan pusat:

Diagram yang menggambarkan cara resource Cloud Resource Manager menautkan project anggota ke project pengelolaan pusat.
Gambar 1. Arsitektur batas pengelolaan lintas project yang menghubungkan project anggota ke project pengelolaan pusat.

Pengelolaan multi-project

Batas pengelolaan memisahkan tata kelola administratif dari eksekusi komputasi di dua peran project yang berbeda: project pengelolaan pusat dan satu atau beberapa project anggota.

Struktur yang dipisahkan ini menerapkan isolasi multi-tenant. Tim membangun dan men-deploy agen di project anggota masing-masing tanpa memerlukan akses langsung ke project anggota lain, dan administrator serta orchestrator mempertahankan visibilitas terpadu di seluruh batas pengelolaan dari project pengelolaan.

Project pengelolaan

Project pengelolaan adalah project Google Cloud yang berfungsi sebagai project tata kelola pusat untuk batas pengelolaan. Layanan ini memusatkan konfigurasi API, kontrol akses, penagihan, konsumsi kuota, dan metadata komponen gabungan di seluruh batas tanpa perlu menghosting runtime komputasi yang mendasarinya.

Di Agent Registry, project pengelolaan menjalankan fungsi berikut:

  • Pengikatan batas dan kemampuan: mengaitkan dengan satu atau beberapa batas di Resource Manager melalui resource CapabilityConfig dengan kemampuan AGENT_MANAGEMENT diaktifkan. Untuk mengetahui langkah-langkah konfigurasi, lihat Mengonfigurasi batas pengelolaan.
  • Penemuan dan penelusuran terpusat: berfungsi sebagai project target untuk permintaan daftar dan penelusuran lintas project, sehingga memungkinkan orchestrator, developer, dan aplikasi klien berinteraksi dengan agen, server MCP, dan alat yang ditemukan secara otomatis di semua project anggota dalam batasan.
  • Pendaftaran resource di seluruh batas: menghosting resource Service yang didaftarkan secara manual, seperti agen kustom, server MCP eksternal, dan endpoint, serta resource Binding jika Anda ingin resource tersebut terlihat di seluruh batas pengelolaan.
  • Pengelolaan API, penagihan, dan kuota terpusat: menggabungkan aktivasi Agent Registry API, alokasi kuota, dan penagihan untuk operasi penemuan dan tata kelola tingkat batas.

Saat mengonfigurasi resource CapabilityConfig pada folder atau organisasi di Resource Manager, Anda dapat menyediakan project pengelolaan dengan salah satu cara berikut:

  • Project pengelolaan yang dikelola sendiri: Anda menetapkan projectGoogle Cloud yang ada yang Anda kelola dengan meneruskan flag --management-project saat membuat resource CapabilityConfig. Project harus berada langsung di folder atau organisasi induk yang sama dengan resource CapabilityConfig dan tidak boleh berfungsi sebagai project pengelolaan untuk resource CapabilityConfig lain. Jika nanti Anda menghapus resource CapabilityConfig, Resource Manager akan mempertahankan project yang dikelola sendiri dan mengembalikannya ke project standar.
  • Project pengelolaan yang dikelola Google: Anda menghilangkan flag --management-project saat membuat resource CapabilityConfig, dan Resource Manager akan otomatis membuat dan mengelola project baru untuk Anda di folder atau organisasi induk. Project yang dihasilkan memiliki awalan project ID google-mpf atau google-mpo. Jika nanti Anda menghapus resource CapabilityConfig, Resource Manager akan menghapus project yang dikelola Google ini.

Dalam kedua kasus tersebut, pembuatan resource CapabilityConfig dengan agent-management akan otomatis mengaktifkan agentregistry.googleapis.com di project pengelolaan.

Project anggota

Project anggota adalah project Google Cloud yang termasuk dalam batas pengelolaan. Project tersebut dapat berupa semua project turunan dalam folder atau organisasi induk batas, atau project turunan yang cocok dengan filter tag batas opsional seperti env=prod. Agen, server MCP, dan alat yang ditemukan secara otomatis berjalan di project anggota.

Project anggota mempertahankan resource komputasi lokalnya sendiri, seperti mesin penalaran Agent Runtime, layanan Cloud Run, atau cluster GKE. Resource yang ditemukan otomatis diserap secara lokal dalam setiap project anggota dan digabungkan ke dalam project pengelolaan saat Anda mencantumkan atau menelusuri registry. Sebaliknya, resource yang didaftarkan secara manual yang Anda buat di project anggota hanya akan terlihat saat Anda mengirim permintaan ke project anggota tersebut.

Pengaitan project anggota dengan project pengelolaan dalam batas tunduk pada batasan sistem. Melebihi batas ini dapat menyebabkan error rolloup. Untuk mengetahui informasi selengkapnya, lihat Kuota dan batas sistem.

Pendaftaran dan rollup

Penemuan lintas project di Agent Registry membedakan antara resource yang ditemukan secara otomatis yang di-deploy di project anggota dan resource yang didaftarkan secara manual yang dicakupkan ke project tempat resource tersebut dibuat.

Resource yang ditemukan dan didaftarkan secara otomatis

Cara resource dicakup di seluruh batas pengelolaan bergantung pada cara resource tersebut didaftarkan:

  • Agen dan server MCP yang ditemukan otomatis: resource yang didukung yang di-deploy di project anggota, seperti mesin penalaran Agent Runtime, layanan Cloud Run, dan deployment GKE, otomatis diserap dalam project anggota tempat resource tersebut di-deploy dan digabungkan ke dalam project pengelolaan.

  • Resource dan binding yang didaftarkan secara manual: resource Service yang didaftarkan secara manual, seperti agen kustom, server MCP eksternal, endpoint, dan resource Binding dicakupkan ke project tempat resource tersebut dibuat:

    • Buat di project pengelolaan jika Anda ingin resource tersebut terlihat di seluruh batas pengelolaan.
    • Buat di project anggota jika Anda ingin agar hanya terlihat dalam project anggota tersebut.

  • Kemampuan, penayang, dan aplikasi AI mandiri: resource Skill, SkillRevision, Publisher, dan AiApplication mandiri kustom dicakupkan ke project tempat resource tersebut dibuat dan tidak digabungkan di seluruh project anggota dalam batas pengelolaan. Daftarkan kemampuan mandiri kustom dan aplikasi AI dalam project tempat agen atau developer Anda perlu menemukannya. Keterampilan mandiri yang dikelola Google dapat ditemukan di project mana pun secara otomatis.

Rollup kueri terpusat

Cara Agent Registry mencakup lokasi bergantung pada apakah Anda mengkueri project tata kelola mandiri, atau project anggota atau project pengelolaan dalam batas pengelolaan:

  • Project tata kelola mandiri dan project anggota: kueri di lokasi yang didukung Agent Registry, seperti us-central1, europe-west1, us, eu, atau global, hanya menampilkan resource di lokasi tersebut untuk satu project tersebut, tanpa rollup lintas project.

  • Project pengelolaan: saat Anda mengaktifkan resource CapabilityConfig dengan agent-management di project pengelolaan, rollup lintas project didukung di semua lokasi yang didukung Agent Registry. Membuat kueri lokasi di project pengelolaan akan menggabungkan resource di lokasi yang sama di seluruh project pengelolaan dan semua project anggota dalam batas pengelolaan. Rollup ini tidak menyertakan resource di berbagai lokasi:

    • Satu region: kueri di satu region, seperti us-central1 atau europe-west1, menggabungkan agen dan server MCP yang ditemukan otomatis yang di-deploy di satu region tersebut di seluruh project pengelolaan dan project anggotanya, bersama dengan resource Service dan Binding yang dibuat di region tersebut pada project pengelolaan.
    • Multi-region: kueri di multi-region, seperti us atau eu, menggabungkan agen dan server MCP yang ditemukan otomatis yang di-deploy di multi-region tersebut di seluruh project pengelolaan dan project anggotanya. Kueri di multi-region tidak menggabungkan resource yang di-deploy di satu region.
    • Global: kueri di lokasi global menggabungkan agen dan server MCP yang ditemukan secara otomatis yang di-deploy di global di seluruh project pengelolaan dan project anggotanya, bersama dengan resource Service dan Binding yang dibuat di global pada project pengelolaan. Kueri di global tidak menggabungkan resource yang di-deploy di multi-region atau satu region.

Saat Anda mencantumkan, menelusuri, atau mengambil komponen agen di suatu lokasi pada project pengelolaan, Agent Registry akan melakukan langkah-langkah berikut:

  1. Mengidentifikasi semua project anggota yang terkait dengan project pengelolaan melalui resource CapabilityConfig yang aktif.
  2. Kueri akan otomatis menemukan agen dan server MCP di lokasi tersebut di seluruh project pengelolaan dan setiap project anggota, bersama dengan resource Service yang didaftarkan secara manual yang dibuat di lokasi tersebut pada project pengelolaan.
  3. Menggabungkan resource yang cocok ke dalam kumpulan hasil terpadu.
  4. Menampilkan hasil gabungan kepada Anda.

Jika beberapa batasan dilampirkan ke resource CapabilityConfig yang sama, Agent Registry akan menggabungkan project anggota dari semua batasan yang dilampirkan ke registry project pengelolaan yang sama. Untuk mempersempit daftar atau hasil penelusuran di project pengelolaan menjadi satu project anggota, teruskan --filter="project_id=MEMBER_PROJECT_ID". Jika dua lingkungan memerlukan visibilitas terpisah, buat resource CapabilityConfig dan project pengelolaan terpisah untuk setiap batasan.

Penemuan project tunggal dan penemuan lintas project menggunakan metode API yang sama. Cakupan penelusuran bergantung pada apakah project yang ditargetkan adalah project anggota atau project pengelolaan.

Nama resource di seluruh batas pengelolaan

Saat komponen disertakan dalam project anggota, Agent Registry akan menetapkan ID untuk komponen tersebut, seperti AGENT_ID atau SERVER_ID. Saat Anda mencantumkan, menelusuri, atau mendapatkan komponen di seluruh batas pengelolaan, Agent Registry mempertahankan ID komponen tersebut dan memformat nama resource terkait berdasarkan project yang Anda gunakan:

  • Project pengelolaan: saat Anda mencantumkan, menelusuri, atau mendapatkan komponen menggunakan project pengelolaan, setiap nama resource menggunakan project pengelolaan.
  • Project anggota: saat Anda mencantumkan, menelusuri, atau mendapatkan komponen menggunakan project anggota tempat resource di-deploy, setiap nama resource menggunakan project anggota tersebut.

Tabel berikut menunjukkan URL permintaan dan nama resource terkait untuk resource yang ditemukan otomatis yang di-deploy dalam project anggota:

Jenis resource Minta URL Nama resource terkait
Agen projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/agents/AGENT_ID projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/agents/AGENT_ID
projects/MEMBER_PROJECT_ID/locations/LOCATION/agents/AGENT_ID projects/MEMBER_PROJECT_ID/locations/LOCATION/agents/AGENT_ID
Server MCP projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID
projects/MEMBER_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID projects/MEMBER_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID

Nama resource terkait mencerminkan project dalam permintaan Anda. Namun, ID registry dan referensi runtime komponen tetap tidak dapat diubah dan selalu mempertahankan project anggota tempat workload yang mendasarinya berjalan.

Visualisasi topologi dan aliran traffic

Administrator platform dan arsitek AI dapat memvisualisasikan hubungan multi-agen dan traffic lintas project menggunakan diagram topologi.

Diagram topologi memvisualisasikan dimensi arsitektur berikut:

  • Korelasi referensi runtime: menghubungkan ID agen logis dengan referensi runtime fisiknya. Korelasi ini memungkinkan operator melacak agen di Agent Registry langsung ke mesin penalaran Agent Runtime, layanan Cloud Run, atau deployment GKE yang mendasarinya.
  • Cross-project bindings: menampilkan binding antara agen orchestrator di satu project dan server MCP atau alat downstream di project lain.
  • Verifikasi perimeter: membantu administrator memverifikasi bahwa komunikasi agen mematuhi perimeter Kontrol Layanan VPC dan dirutekan melalui endpoint Agent Gateway yang ditetapkan.

Kontrol akses

Dalam batas pengelolaan, Anda memberikan peran penemuan IAM pada project pengelolaan sehingga pengguna dan orchestrator dapat menelusuri seluruh batas tanpa memerlukan akses IAM langsung ke setiap project anggota. Karena resource Service dan Binding yang didaftarkan secara manual yang dibuat dalam project anggota tidak di-roll up ke project pengelolaan, administrator keamanan juga dapat membatasi pembuatan Service dan Binding lokal di project anggota menggunakan batasan kebijakan organisasi atau kebijakan penolakan IAM. Saat agen dalam project anggota memanggil alat atau berkomunikasi dengan agen di project lain di seluruh batas, traffic dapat dirutekan melalui Agent Gateway pusat.

Untuk resource dalam batas pengelolaan, pembatasan Kontrol Layanan VPC hanya berlaku untuk interaksi Agent Registry dalam project pengelolaan. Agent Registry dapat menemukan agen dan server MCP di semua project anggota dalam batas pengelolaan, meskipun project anggota tersebut tidak berada dalam perimeter layanan yang sama dengan project pengelolaan.

Untuk mengetahui informasi selengkapnya tentang peran yang diperlukan untuk penyiapan batasan, akses registry, dan batasan penulisan project anggota, lihat Peran untuk batasan pengelolaan lintas project.

Langkah berikutnya