Memecahkan masalah Agent Registry

Saat mendaftarkan, menemukan, atau menghubungkan komponen di Agent Registry, Anda dapat mendiagnosis dan menyelesaikan masalah umum seperti batas kuota, error validasi payload dan skill, ketidakcocokan lokasi, penundaan sinkronisasi, dan error izin.

Kuota kapasitas API terlampaui

Error berikut terjadi jika Anda melebihi batas rasio permintaan saat berinteraksi dengan Agent Registry API atau menavigasi Agent Registry dengan cepat di konsolGoogle Cloud :

429 Too Many Requests

Untuk mengatasi masalah ini, terapkan backoff eksponensial di klien API Anda untuk mengelola rasio permintaan. Agent Registry API memiliki kuota kapasitas default permintaan per menit per lokasi yang berlaku untuk resource Agent Registry Anda.

Jika Anda mengalami throttling saat beralih tab di konsol Google Cloud , tunggu beberapa saat, lalu coba lagi. Jika kasus penggunaan terprogram Anda memerlukan batas yang lebih tinggi, minta penambahan kuota untuk metrik RequestsPerMinute.

Error ukuran payload selama pendaftaran manual

Error berikut terjadi saat Anda mendaftarkan agen atau server MCP secara manual dengan file spesifikasi yang melebihi batas ukuran:

API akan menolak permintaan dengan error yang menyatakan bahwa payload terlalu besar.

Untuk mengatasi masalah ini, pastikan file agent-card.json atau toolspec.json Anda berukuran kurang dari 10 KB. Ukuran konten AgentSpec dan McpServerSpec dibatasi hingga 10 KB. Minifikasi file JSON Anda, hapus spasi kosong yang tidak perlu, atau ringkas deskripsi alat untuk mematuhi batas ini. Untuk mengetahui informasi selengkapnya, lihat skema JSON.

Agen atau server MCP tidak ada setelah pembuatan

Error berikut terjadi setelah Anda membuat agen atau server MCP di produk Google Cloud yang didukung, seperti Google Workspace atau Gemini Enterprise:

Resource tidak muncul dalam output saat Anda memanggil API ListAgents atau ListMcpServers.

Untuk mengatasi masalah ini, tunggu hingga sinkronisasi latar belakang selesai. Resource Anda diperbarui secara real time, tetapi tugas batch offline berkala mengisi integrasi lainnya. Jika resource Anda tidak muncul setelah beberapa jam, verifikasi setelan Service Usage project Anda dan pastikan API yang relevan diaktifkan.

Operasi yang berjalan lama tampak macet

Error berikut terjadi saat Anda men-deploy agen atau mengonfigurasi binding yang kompleks:

Operasi memerlukan waktu yang lama dan tampak macet.

Untuk mengatasi masalah ini, gunakan alat MCP get_operation atau endpoint API google.longrunning.Operations.GetOperation untuk melakukan polling status operasi. Beberapa pembuatan backend agen dan MCP memerlukan penyediaan infrastruktur yang signifikan, yang dapat menyebabkan waktu operasi yang berjalan lama (LRO) yang mungkin memerlukan waktu hingga 30 menit. Konfigurasikan setelan waktu tunggu klien Anda sebagai hasilnya dan lakukan polling flag boolean done untuk memverifikasi penyelesaian.

Hasil kosong saat mengambil binding yang tersedia

Error berikut terjadi jika Anda mengambil binding yang tersedia untuk penyedia autentikasi tanpa izin yang memadai pada resource AuthProvider target:

API akan menampilkan array kosong atau error akses, meskipun binding ada.

Untuk mengatasi masalah ini, pastikan akun utama Anda memiliki izin Identity and Access Management (IAM) yang benar pada resource AuthProvider target. API ini menerapkan pemeriksaan IAM yang ketat dan menghapus objek Binding yang mereferensikan penyedia autentikasi yang tidak dapat diakses oleh pemanggil. Pastikan akun utama Anda memiliki akses yang diperlukan di penyedia autentikasi dan peran roles/agentregistry.viewer di project.

Download revisi keahlian gagal dengan error 302

Error berikut terjadi jika Anda mencoba mendownload payload revisi skill menggunakan GetSkillRevision API dengan parameter kueri ?alt=media dan klien HTTP Anda tidak mengikuti pengalihan:

{
  "error": {
    "code": 302,
    "message": "Unknown Error.",
    "status": "UNKNOWN"
  }
}

Untuk mengatasi masalah ini, pastikan klien HTTP Anda dikonfigurasi untuk mengikuti pengalihan secara otomatis. Endpoint ?alt=media memerlukan pengalihan 302 agar berhasil mendownload arsip skill. Misalnya, jika Anda menggunakan curl, tambahkan flag -L atau --location ke perintah Anda.

Validasi revisi skill gagal atau menampilkan status FAILED

Error berikut terjadi saat Anda membuat revisi skill baru dengan file ZIP yang tidak valid:

Revisi beralih ke status FAILED dan tidak dapat dimuat oleh agen.

Untuk mengatasi masalah ini, periksa log validasi atau periksa konten payload ZIP:

  • Pastikan file ZIP berisi file SKILL.md di root-nya.
  • Pastikan file SKILL.md memiliki blok front matter YAML yang valid dengan name dan description yang ditentukan.
  • Pastikan payload ZIP tidak melebihi batas ukuran: ukuran terkompresi harus kurang dari 1 MB, total ukuran tidak terkompresi kurang dari 10 MB, dan ukuran file individual kurang dari 1 MB.
  • Pastikan arsip tidak berisi link simbolis, elemen traversal direktori seperti .., atau jalur absolut.

Keterampilan mandiri tidak muncul dalam daftar resource layanan atau agen

Error berikut terjadi jika Anda mengkueri daftar agen atau layanan untuk kemampuan mandiri, seperti dengan menjalankan gcloud agent-registry services list atau gcloud agent-registry agents list:

Keterampilan mandiri tidak muncul dalam output.

Untuk mengatasi masalah ini, buat kueri koleksi skills:

  • Tidak seperti agen, server MCP, dan endpoint yang didaftarkan secara manual, keterampilan mandiri tidak menggunakan resource Service yang dapat ditulis atau resource penemuan Agent, McpServer, atau Endpoint. Sebagai gantinya, Agent Registry merepresentasikan kemampuan mandiri secara langsung sebagai resource Skill level teratas dan resource SkillRevision berversi.
  • Untuk mencantumkan, menelusuri, atau memeriksa skill mandiri, gunakan tab Skills di konsolGoogle Cloud , jalankan gcloud agent-registry skills list atau gcloud agent-registry skills search, atau panggil metode REST API skills. Untuk mengetahui petunjuknya, lihat Mengelola keahlian dan Menelusuri keahlian mandiri.
  • Jika Anda mencari kemampuan A2A inline yang dideklarasikan dalam Kartu Agen agen, periksa kolom skills pada resource penemuan Agent menggunakan gcloud agent-registry agents describe atau gcloud agent-registry agents search.

Error entity resource tidak ditemukan saat mengelola kebijakan IAP

Error berikut terjadi saat Anda menggunakan perintah gcloud iap web untuk mengelola kebijakan egress Identity-Aware Proxy (IAP) pada resource Agent Registry:

NOT_FOUND: Requested entity was not found

Untuk mengatasi masalah ini, verifikasi hal berikut:

  • Status pendaftaran: konfirmasi bahwa komponen target terdaftar di Agent Registry di lokasi yang diharapkan.
  • Format ID: pastikan perintah atau binding kebijakan Anda menentukan nama resource standar, bukan URN ID registry.
  • Resource flag: pastikan flag resource yang Anda teruskan ke gcloud iap web cocok dengan jenis resource turunan Agent Registry yang mendasarinya:
    • Untuk endpoint, seperti API eksternal atau titik egress Google API, gunakan flag --endpoint.
    • Untuk server Model Context Protocol, gunakan flag --mcp-server.
    • Untuk agen terdaftar, gunakan flag --agent.

Periksa nama resource yang ditampilkan oleh gcloud agent-registry endpoints list, gcloud agent-registry mcp-servers list, atau gcloud agent-registry agents list untuk mengonfirmasi apakah nama resource berisi /endpoints/, /mcpServers/, atau /agents/. Meneruskan flag resource yang salah, misalnya, meneruskan --endpoint untuk ID server MCP, akan menyebabkan error NOT_FOUND.

Izin ditolak saat menerapkan kebijakan IAM web IAP

Error berikut terjadi saat Anda menerapkan atau mengubah kebijakan IAM web IAP untuk resource Agent Registry tanpa peran administratif yang diperlukan:

ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED

Untuk mengatasi masalah ini, pastikan pengguna atau akun layanan aktif Anda memiliki izin yang diperlukan pada project yang menghosting registry dan gateway:

  • Pastikan pemanggil memiliki peran Admin Kebijakan IAP (roles/iap.admin) atau Admin IAM Project (roles/resourcemanager.projectIamAdmin) di project tata kelola pusat.
  • Pastikan pemanggil memiliki izin iap.web.setIamPolicy dan resourcemanager.projects.setIamPolicy.

Server MCP jarak jauh tidak ditemukan di lokasi regional

Error berikut terjadi jika Anda mengkueri server MCP jarak jauh Google atau Google Cloud yang terdaftar secara otomatis, atau menerapkan kebijakan egress IAP ke server tersebut, di lokasi regional seperti us-central1:

Permintaan akan menampilkan error NOT_FOUND atau daftar kosong, meskipun layanan menyediakan endpoint regional (REP) atau saat traffic dirutekan melalui Agent Gateway regional.

Saat Agent Registry otomatis mendaftarkan server MCP Google atau Google Cloud jarak jauh untuk API yang diaktifkan, Agent Registry akan membuat resource McpServer hanya di lokasi global, bukan di masing-masing region seperti us-central1. Jika layanan menyediakan endpoint regional, seperti https://SERVICE.REGION.rep.googleapis.com/mcp, Agent Registry akan mencantumkan URL regional tersebut di kolom interfaces dari satu resource global McpServer tersebut.

Untuk menyelesaikan masalah ini, lakukan salah satu tindakan berikut:

  • Gunakan global untuk server yang terdaftar secara otomatis: tentukan lokasi global saat Anda mengkueri server di Agent Registry dengan --location=global atau menerapkan kebijakan egress IAP ke server tersebut dengan --region=global, bahkan saat agen panggilan merutekan traffic melalui gateway regional.
  • Daftarkan di region untuk residensi data: jika Anda perlu menyimpan metadata registry di region tertentu, deploy server MCP kustom ke runtime Cloud Run atau Google Kubernetes Engine (GKE) regional, atau daftarkan secara manual server MCP dan URL endpoint regionalnya di region tersebut, lalu terapkan kebijakan IAP Anda di region yang sama. Saat Agent Gateway me-resolve URL target, entri registry regional lebih diprioritaskan daripada entri global.

Error ketidakcocokan region saat mengonfigurasi Model Armor di Agent Gateway

Error berikut terjadi saat Anda mengonfigurasi filter kebijakan Model Armor di Agent Gateway di seluruh region yang tidak cocok:

Pembuatan kebijakan otorisasi gagal dengan error ketidakcocokan region, atau traffic yang dirutekan melalui gateway ke server MCP gagal dalam evaluasi kebijakan.

Untuk mengatasi masalah ini, verifikasi keselarasan regional resource gateway dan binding kebijakan target Anda:

  • Menyelaraskan region gateway dan Model Armor: pastikan Agent Gateway, template Model Armor, serta ekstensi dan kebijakan otorisasi semuanya berada di region yang sama, seperti us-central1.
  • Merutekan ke server MCP global atau regional: Anda tidak perlu mendaftarkan ulang server MCP global di suatu region hanya untuk menggunakan Model Armor. Karena Model Armor memeriksa payload permintaan dan respons di gateway regional, gateway regional dapat memeriksa dan mengatur traffic yang dirutekan ke server MCP yang terdaftar di lokasi global serta tujuan regional.
  • Cocokkan binding egress IAP dengan lokasi pendaftaran target: terapkan binding otorisasi egress IAP di lokasi tempat resource McpServer target terdaftar. Gunakan global untuk server MCP jarak jauh yang terdaftar secara otomatis, atau gunakan region tertentu untuk server MCP yang terdaftar secara regional.

Kegagalan saat mengakses Agent Registry dengan Workforce Identity Federation

Error berikut terjadi jika Anda mengakses Agent Registry di konsolGoogle Cloud atau menggunakan Google Cloud CLI saat diautentikasi dengan Workforce Identity Federation:

KonsolGoogle Cloud menampilkan error pemuatan umum, seperti berikut:

  • "Terjadi error saat memuat..."
  • "Server tidak dapat memenuhi permintaan Anda"
  • "Gagal dimuat"

Selain itu, perintah gcloud mungkin menampilkan error internal, seperti error 13: an internal error has occurred.

Untuk menyelesaikan masalah ini, lakukan autentikasi dengan Akun Google standar yang dikelola melalui Cloud Identity atau Google Workspace. Pastikan akun memiliki izin yang diperlukan, seperti roles/agentregistry.admin atau roles/agentregistry.viewer.

Layanan tata kelola Gemini Enterprise Agent Platform memiliki dukungan terbatas untuk identitas gabungan. Memberikan peran IAM yang lebih luas ke akun utama gabungan tidak akan menyelesaikan masalah.

Download revisi keahlian diblokir karena temuan keamanan

Error berikut terjadi jika Anda mencoba mendownload payload revisi skill saat kebijakan pemindaian skill ditetapkan ke ENABLED_BLOCKING dan revisi memiliki temuan keamanan:

FAILED_PRECONDITION: cannot download skill revision with scan findings when scanning policy is ENABLED_BLOCKING

Untuk menyelesaikan masalah ini, lakukan salah satu tindakan berikut:

  1. Periksa temuan keamanan yang terdeteksi pada revisi dengan menjalankan perintah gcloud agent-registry findings list. Perintah ini memerlukan peran roles/agentregistry.admin.
  2. Perbaiki temuan dalam file sumber lokal Anda, seperti menghapus kode egress jaringan yang tidak sah, menghapus kredensial yang terekspos, atau menghilangkan pola injeksi perintah.
  3. Mengupload dan mendaftarkan revisi keahlian baru.
  4. Atau, jika Anda bekerja di lingkungan pengujian atau staging yang diizinkan, perbarui kebijakan pemindaian skill ke ENABLED_NONBLOCKING menggunakan --scanning-policy=enabled-nonblocking. Untuk mengetahui informasi selengkapnya, lihat Memindai skill untuk menemukan masalah keamanan.

Gagal menetapkan revisi default atau mengaktifkan kebijakan pemblokiran

Error berikut terjadi jika Anda memperbarui pointer revisi default skill (--default-revision) atau mengubah kebijakan pemindaian skill menjadi ENABLED_BLOCKING saat revisi memiliki temuan atau hasil pemindaian yang tertunda:

API menampilkan error FAILED_PRECONDITION dengan salah satu pesan berikut:

  • cannot set default revision to a revision with scan findings when scanning policy is ENABLED_BLOCKING
  • cannot set default revision to a revision with pending scan results when scanning policy is ENABLED_BLOCKING
  • cannot set scanning policy to ENABLED_BLOCKING when default revision has scan findings
  • cannot set scanning policy to ENABLED_BLOCKING when default revision has pending scan results

Untuk mengatasi masalah ini, lakukan langkah berikut:

  • Jika pemindaian masih tertunda (RUNNING), tunggu hingga pemindaian latar belakang selesai dan pastikan scanResult.scanState di-resolve ke SUCCEEDED tanpa findings sebelum menetapkan revisi sebagai default atau mengaktifkan ENABLED_BLOCKING.
  • Jika revisi default target atau saat ini memiliki temuan keamanan, publikasikan revisi baru dengan masalah keamanan yang telah diselesaikan, verifikasi bahwa scanResult.scanState-nya di-resolve ke SUCCEEDED tanpa findings yang tercantum, dan tetapkan revisi yang bersih tersebut sebagai defaultRevision skill.

Revisi skill ditolak karena batas ukuran yang tidak dikompresi

Error berikut terjadi saat Anda mengupload revisi keahlian yang melebihi batas ukuran pemindaian maksimum yang tidak dikompresi:

Operasi yang berjalan lama gagal dengan error INVALID_ARGUMENT, atau scanResult.scanState revisi bertransisi ke UNSUPPORTED_FORMAT.

Untuk menyelesaikan masalah ini, lakukan salah satu tindakan berikut:

  • Periksa file yang tidak dikompresi dalam paket ZIP Anda. Hapus set data besar, biner model, atau aset yang tidak diperlukan agar setiap file tetap berukuran di bawah 1 MB dan total paket yang diekstrak di bawah 10 MB.
  • Jika alur kerja pengembangan Anda memerlukan upload file besar untuk pembuatan prototipe cepat dalam project, perbarui kebijakan pemindaian skill ke DISABLED menggunakan --scanning-policy=disabled, jika diizinkan oleh kebijakan organisasi Anda.

Tidak dapat menonaktifkan pemindaian keterampilan karena kebijakan organisasi

Error berikut terjadi jika Anda membuat atau memperbarui skill dengan kebijakan pemindaiannya yang ditetapkan ke DISABLED, atau jika Anda memperbarui kolom apa pun pada skill yang ada yang scanningConfig.policy-nya sebelumnya ditetapkan ke DISABLED:

Permintaan gagal dengan error pelanggaran batasan kebijakan organisasi kustom.

Untuk mengatasi masalah ini, lakukan langkah berikut:

  • Organisasi Anda telah menerapkan batasan kebijakan organisasi kustom, seperti custom.skillsScanningEnforcement, pada agentregistry.googleapis.com/Skill yang menolak resource.scanningConfig.policy == "DISABLED".
  • Jika Anda memperbarui keahlian yang ada yang scanningConfig.policy-nya ditetapkan ke DISABLED sebelum kebijakan organisasi diterapkan, sertakan pembaruan pada scanningConfig.policy, dengan menetapkannya ke ENABLED_BLOCKING atau nilai yang diizinkan, dalam permintaan UpdateSkill Anda.
  • Untuk mengizinkan pemindaian dinonaktifkan di lingkungan pengujian atau sandbox, minta Administrator Kebijakan Organisasi Anda untuk menambahkan tag pengecualian bersyarat, seperti exempt-scanning-enforcement: true, ke project Anda.

Untuk mengetahui informasi selengkapnya, lihat Menerapkan pemindaian menggunakan Organization Policy Service.

Revisi skill tidak dipindai setelah mengaktifkan pemindaian

Error berikut terjadi jika Anda mengaktifkan pemindaian pada keahlian yang ada yang memiliki revisi yang diupload sebelumnya:

Status pemindaian (scanResult.scanState) untuk revisi yang ada tetap DISABLED, revisi tidak dipindai, dan tidak ada temuan keamanan yang dihasilkan.

Mengaktifkan pemindaian untuk skill hanya berlaku untuk revisi skill yang dibuat setelah pemindaian diaktifkan. Registry Agen tidak memindai revisi yang dibuat sebelum pemindaian diaktifkan secara retroaktif.

Untuk mengatasi masalah ini, upload dan daftarkan revisi skill baru untuk skill tersebut. Saat Anda mengupload revisi baru, Agent Registry akan memindai payload sesuai dengan konfigurasi pemindaian yang diperbarui untuk keterampilan tersebut. Untuk mengetahui informasi selengkapnya, lihat Membuat revisi skill dan Memindai skill untuk menemukan masalah keamanan.

Tidak dapat mengonfigurasi CMEK karena keterampilan sudah ada

Error berikut terjadi jika Anda mencoba menetapkan atau memperbarui SkillEncryptionSpec untuk lokasi yang sudah memiliki keahlian:

FAILED_PRECONDITION: crypto_key_name can only be set or updated when no Skills exist in this location

Anda dapat mengonfigurasi atau memperbarui kunci enkripsi yang dikelola pelanggan (CMEK) dalam project dan lokasi hanya jika tidak ada skill di lokasi tersebut.

Untuk mengatasi masalah ini, konfigurasikan SkillEncryptionSpec di lokasi target sebelum mendaftarkan skill pertama Anda di sana, atau hapus skill yang ada di lokasi tersebut sebelum menetapkan atau memperbarui kunci Cloud Key Management Service. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi CMEK untuk skill.

Lokasi kunci Cloud KMS tidak valid untuk skill

Error berikut terjadi jika Anda mengonfigurasi SkillEncryptionSpec dengan kunci Cloud KMS yang tidak berada di lokasi Cloud KMS yang diperlukan, atau di lokasi skill yang tidak didukung:

Permintaan akan gagal dengan error INVALID_ARGUMENT yang menyatakan salah satu hal berikut:

  • crypto_key_name "..." is in location "...", but Skills in location "..." can only be encrypted with a Cloud KMS key in location "..."
  • customer-managed encryption keys aren't supported for Skills in location "..."

Untuk mengatasi masalah ini, pastikan Anda mengonfigurasi CMEK di lokasi skill yang didukung (us atau eu) dan kunci Cloud KMS Anda berada di lokasi multi-region Cloud KMS yang diperlukan:

Lokasi keahlian Lokasi kunci Cloud KMS yang diperlukan
us us
eu europe

Cloud KMS menggunakan europe sebagai ID lokasi untuk multi-region Uni Eropa. CMEK tidak didukung untuk lokasi lain, termasuk global. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi CMEK untuk skill.

Pembuatan skill diblokir oleh kebijakan organisasi CMEK

Error berikut terjadi saat Anda membuat skill atau revisi skill dalam project yang tunduk pada batasan kebijakan organisasi CMEK:

Permintaan gagal dengan error FAILED_PRECONDITION yang menyatakan salah satu hal berikut:

  • constraint "constraints/gcp.restrictNonCmekServices" violated for value "agentregistry.googleapis.com". See https://cloud.google.com/kms/docs/cmek-org-policy#require-cmek for more information.
  • constraint "constraints/gcp.restrictCmekCryptoKeyProjects" violated for value "projects/KMS_PROJECT_ID". See https://cloud.google.com/kms/docs/cmek-org-policy#restrict-cmek-projects for more information.

Untuk mengatasi masalah ini, lakukan langkah berikut:

  • Jika constraints/gcp.restrictNonCmekServices dilanggar, organisasi Anda memerlukan perlindungan CMEK untuk Agent Registry. Buat skill di lokasi yang didukung CMEK (us atau eu) dan konfigurasikan SkillEncryptionSpec untuk lokasi tersebut sebelum membuat skill apa pun di sana.
  • Jika constraints/gcp.restrictCmekCryptoKeyProjects dilanggar, kunci Cloud KMS yang dikonfigurasi di SkillEncryptionSpec lokasi akan menjadi milik project yang tidak diizinkan oleh kebijakan constraints/gcp.restrictCmekCryptoKeyProjects organisasi Anda. Perbarui SkillEncryptionSpec jika tidak ada skill di lokasi tersebut untuk mereferensikan kunci Cloud KMS dari project yang diizinkan, atau hubungi Administrator Kebijakan Organisasi Anda untuk mengizinkan project kunci.

Untuk mengetahui informasi selengkapnya, lihat Menerapkan CMEK menggunakan Layanan Kebijakan Organisasi.