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 kemampuan, 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 sebesar 1.200 permintaan per menit, atau 20 kueri per detik, secara global dan per region.

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 diupdate 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 ini 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 pada 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 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 akan 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 500 KB, 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.

Kemampuan mandiri tidak muncul dalam daftar resource layanan atau agen

Error berikut terjadi jika Anda mengkueri daftar agen atau layanan untuk skill 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 alpha agent-registry skills list atau gcloud alpha 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 entitas 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 Registry Agen 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 region individual 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 didaftarkan. Gunakan global untuk server MCP jarak jauh yang terdaftar secara otomatis, atau gunakan region tertentu untuk server MCP yang terdaftar secara regional.

Pendaftaran manual atau pembuatan binding gagal di lokasi multi-region

Error berikut terjadi jika Anda mencoba mendaftarkan agen, server MCP, atau endpoint secara manual, atau membuat binding, di lokasi multi-region seperti us atau eu:

API akan menolak permintaan dengan error lokasi yang tidak didukung atau argumen yang tidak valid.

Untuk mengatasi masalah ini, tentukan lokasi regional yang didukung, seperti us-central1 atau europe-west1, atau lokasi global. Lokasi multi-region us dan eu hanya mendukung penemuan komponen yang terdaftar secara otomatis dan pendaftaran atau penemuan kemampuan mandiri. Untuk mengetahui daftar lokasi yang didukung, lihat Lokasi Agent Registry.

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.