Memecahkan masalah Agent Registry

Halaman ini menampilkan cara menyelesaikan masalah pada Agent Registry.

Kuota kapasitas API terlampaui

Anda mungkin mengalami masalah ini jika berinteraksi dengan Agent Registry API atau menavigasi Agent Registry di konsol dengan cepat: Google Cloud 

429 Too Many Requests

Untuk mengatasi masalah ini, terapkan backoff eksponensial di klien API Anda untuk mengelola kapasitas permintaan. Agent Registry API memiliki kuota kapasitas default sebesar 1.200 permintaan per menit secara global dan per region (20 kueri per detik).

Jika Anda mengalami pembatasan saat beralih tab di Google Cloud konsol, 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

Anda mungkin mengalami masalah ini jika mendaftarkan agen atau server MCP secara manual: API 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 diperlukan, atau ringkas deskripsi alat untuk mematuhi batas ini. Untuk mengetahui informasi selengkapnya, lihat skema JSON.

Agen atau server MCP tidak ada setelah pembuatan

Anda mungkin mengalami masalah ini jika membuat agen atau server MCP di produk yang didukung Google Cloud , seperti Google Workspace atau Gemini Enterprise: resource tidak muncul saat memanggil ListAgents atau ListMcpServers API.

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

Operasi yang berjalan lama tampak macet

Anda mungkin mengalami masalah ini jika men-deploy agen atau mengonfigurasi binding yang kompleks: operasi memerlukan waktu yang cukup lama dan tampak macet.

Untuk mengatasi masalah ini, gunakan alat MCP get_operation atau endpoint google.longrunning.Operations.GetOperation API 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. Konfigurasi setelan waktu tunggu klien Anda sebagai hasilnya dan lakukan polling flag boolean done untuk memverifikasi penyelesaian.

Hasil kosong saat mengambil binding yang tersedia

Anda mungkin mengalami masalah ini jika mengambil binding yang tersedia untuk penyedia autentikasi: API menampilkan empty array atau error akses, meskipun Anda telah memverifikasi bahwa binding ada.

Untuk mengatasi masalah ini, pastikan pokok 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 pokok Anda memiliki akses yang diperlukan pada penyedia autentikasi dan peran roles/agentregistry.viewer pada project.

Download revisi keterampilan gagal dengan error 302

Anda mungkin mengalami masalah ini jika mencoba mendownload payload revisi keterampilan menggunakan GetSkillRevision API dengan parameter kueri ?alt=media: permintaan gagal dan menampilkan error yang mirip dengan yang berikut:

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

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

Validasi revisi keterampilan gagal atau menampilkan status FAILED

Anda mungkin mengalami masalah ini setelah membuat revisi keterampilan baru: revisi bertransisi ke status FAILED dan tidak dapat dimuat oleh agen.

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

  • Pastikan arsip ZIP berisi file SKILL.md di root-nya.
  • Pastikan file SKILL.md memiliki blok frontmatter YAML yang valid dengan name dan description yang ditentukan.
  • Pastikan payload ZIP tidak melebihi batas ukuran: ukuran terkompresi harus kurang dari 500 KB, ukuran total yang tidak dikompresi 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.

Error entity resource tidak ditemukan saat mengelola kebijakan IAP

Anda mungkin mengalami masalah ini jika menggunakan perintah gcloud iap web untuk mengelola kebijakan keluar pada resource Agent Registry:

NOT_FOUND: Requested entity was not found

Untuk mengatasi masalah ini, 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 keluar Google API, gunakan flag --endpoint.
  • Untuk server Model Context Protocol, gunakan flag --mcp-server.
  • Untuk agen terdaftar, gunakan flag --agent.

Periksa URI resource yang ditampilkan oleh gcloud agent-registry [endpoints|mcp-servers|agents] list untuk mengonfirmasi apakah jalur 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

Anda mungkin mengalami masalah ini jika menerapkan atau mengubah kebijakan IAM web Identity-Aware Proxy untuk resource Agent Registry:

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

Untuk mengatasi masalah ini, pastikan akun layanan atau pengguna 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) pada project tata kelola pusat.
  • Pastikan pemanggil memiliki izin iap.web.setIamPolicy dan resourcemanager.projects.setIamPolicy.