Menelusuri agen, alat, dan keterampilan

Agent Registry memungkinkan Anda menelusuri agen terdaftar, kemampuan Agent2Agent (A2A), kemampuan mandiri, dan server Model Context Protocol (MCP) berdasarkan kata kunci, awalan, atau bahasa alami di konsol Google Cloud , Google Cloud CLI, atau Agent Registry API. Penelusuran kata kunci dan awalan membantu Anda menemukan resource dengan cepat berdasarkan nama, ID, atau metadata. Penelusuran semantik menemukan kapabilitas yang terkait secara konseptual di seluruh petunjuk dan deskripsi bahasa alami berdasarkan intent.

Kueri penelusuran mengevaluasi deskripsi kemampuan agen, server MCP, dan keterampilan, skema alat, dan petunjuk keterampilan. Anda tidak dapat menggunakan kueri penelusuran untuk menemukan endpoint; untuk mengetahui petunjuk tentang cara mencantumkan dan memfilter endpoint berdasarkan metadata, lihat Menemukan endpoint dan memfilter komponen berdasarkan metadata.

Sebelum memulai

1. Menyiapkan Agent Registry.

2. Untuk penyiapan project tunggal, dapatkan project ID dari project tata kelola tempat Agent Registry diaktifkan. Jika Anda mengonfigurasi batas pengelolaan untuk beberapa project, gunakan ID project pengelolaan Anda untuk penemuan dan pendaftaran di seluruh batas, atau tentukan ID project anggota untuk operasi project tunggal.

3. Daftarkan agen, server MCP, atau kemampuan di Agent Registry.

4. Untuk menggunakan perintah Google Cloud CLI dalam dokumen ini, siapkan lingkungan gcloud CLI Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk menelusuri agen, alat, dan keterampilan di Agent Registry, minta administrator untuk memberi Anda peran IAM Agent Registry API Viewer (roles/agentregistry.viewer) di project tata kelola tempat Agent Registry diaktifkan. 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.

Menelusuri agen dan alat

Untuk menemukan kemampuan dalam registry, Anda dapat menelusuri agen dan server MCP yang terdaftar di konsol Google Cloud , gcloud CLI, atau REST API.

Saat menelusuri agen atau server MCP, Anda dapat membuat kueri berdasarkan nama tampilan, deskripsi, atau kata kunci kemampuan:

• Agen: kueri penelusuran memeriksa nama tampilan, deskripsi, ID agen, serta nama, deskripsi, dan tag kemampuan A2A inline yang dideklarasikan dalam Kartu Agennya untuk menemukan kecocokan.
• Server MCP: kueri penelusuran memeriksa nama tampilan server, deskripsi, ID server MCP, serta nama dan deskripsi alatnya untuk menemukan kecocokan.

Telusuri menurut kata kunci

Anda dapat melakukan penelusuran kata kunci untuk menemukan resource yang berisi istilah tertentu di seluruh kemampuannya, seperti keterampilan A2A agen atau alat server MCP. Untuk memahami cara kemampuan ini disusun dalam registry, lihat skema JSON. Untuk mengetahui daftar lengkap kolom yang dapat ditelusuri, lihat referensi API.

Kueri kata kunci menerima string teks bebas dan mendukung operator logika AND, OR, dan NOT:

Konsol

1. Di konsol Google Cloud , buka Agent Registry:

   Buka Agent Registry

2. Dari pemilih project, pilih project Google Cloud Anda.

3. Di panel Search your registry di bagian atas halaman, masukkan kueri kata kunci minimal tiga karakter, seperti flight atau database, atau filter kolom, seperti Name:booking, lalu tekan Enter.

   Tabel hasil penelusuran menampilkan agen, server MCP, dan kemampuan mandiri yang cocok di seluruh lokasi yang Anda pilih.

gcloud

Berikan flag --search-string ke perintah gcloud agent-registry agents search atau gcloud agent-registry mcp-servers search.

Misalnya, telusuri agen yang dapat menangani pemesanan penerbangan:

gcloud agent-registry agents search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string="flight OR booking"

Telusuri server MCP yang menyediakan alat database:

gcloud agent-registry mcp-servers search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string="database"

Ganti kode berikut:

• PROJECT_ID: project ID.
• REGION: region registry atau global.

REST

Kirim permintaan POST ke endpoint agents:search atau mcpServers:search dengan kolom searchString di isi permintaan.

Misalnya, telusuri agen yang dapat menangani pemesanan penerbangan:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "flight OR booking"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

Telusuri server MCP yang menyediakan alat database:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "database"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/mcpServers:search"

Ganti kode berikut:

• PROJECT_ID: project ID.
• REGION: region registry atau global.

Menelusuri berdasarkan awalan

Penelusuran awalan dioptimalkan untuk latensi rendah, sehingga aplikasi Anda dapat mengambil agen dan alat yang relevan secara dinamis saat pengguna mengetik.

Jika Anda membangun antarmuka orchestrator atau fitur pelengkapan otomatis, Anda dapat melakukan penelusuran awalan di Agent Registry untuk menemukan hasil yang dimulai dengan string tertentu. Penelusuran awalan menggunakan simbol karakter pengganti akhiran * untuk menelusuri awal kata:

gcloud

Jalankan perintah gcloud agent-registry agents search atau gcloud agent-registry mcp-servers search dengan ekspresi awalan.

Misalnya, telusuri agen yang nama tampilannya diawali dengan Best_A2A_*:

gcloud agent-registry agents search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string="displayName:Best_A2A_*"

Demikian pula, telusuri server MCP yang nama tampilannya diawali dengan Prod_Server_*:

gcloud agent-registry mcp-servers search \
    --project=PROJECT_ID \
    --location=REGION \
    --search-string="displayName:Prod_Server_*"

Ganti kode berikut:

• PROJECT_ID: project ID.
• REGION: region registry atau global.

REST

Teruskan ekspresi awalan di kolom searchString pada isi permintaan:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "displayName:Best_A2A_*"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

Ganti kode berikut:

• PROJECT_ID: project ID.
• REGION: region registry atau global.

Menelusuri di seluruh batas pengelolaan

Pratinjau

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

Jika telah mengonfigurasi batas pengelolaan, Anda dapat menelusuri agen dan server MCP di suatu lokasi di semua project anggota dalam batas tersebut dari project pengelolaan:

gcloud agent-registry agents search \
    --project=MANAGEMENT_PROJECT_ID \
    --location=LOCATION \
    --search-string="analytics"

Ganti kode berikut:

• MANAGEMENT_PROJECT_ID: ID project pengelolaan Anda.
• LOCATION: lokasi untuk menelusuri batas pengelolaan, seperti region seperti us-central1, multi-region seperti us atau eu, atau global. Registry Agen menggabungkan resource di lokasi yang sama di seluruh project pengelolaan dan semua project anggota dalam batasan.

Untuk mempersempit hasil di project pengelolaan ke project anggota tertentu, teruskan flag --filter yang ditetapkan ke "project_id=MEMBER_PROJECT_ID". Untuk menelusuri secara eksklusif dalam satu project anggota tanpa rollup lintas project, tentukan ID project anggota tersebut dalam flag --project.

Saat Anda melakukan penelusuran dari project pengelolaan:

• Resource gabungan yang ditemukan otomatis: Agent Registry menelusuri agen dan server MCP yang ditemukan otomatis di lokasi yang ditentukan dari semua project anggota dalam batas pengelolaan, bersama dengan resource Service terdaftar yang dibuat di lokasi tersebut dalam project pengelolaan.
• Nama resource cakupan permintaan: dalam hasil penelusuran, setiap kolom name resource Agent atau McpServer yang ditampilkan mempertahankan ID komponen dan menggunakan project yang ditentukan dalam URL permintaan.
• Resource terdaftar yang tercakup dalam project: resource Service yang didaftarkan secara manual dan resource Binding yang dibuat dalam project anggota tetap tercakup dalam project anggota tersebut dan tidak muncul dalam hasil penelusuran project pengelolaan. Agar dapat terlihat di seluruh batas pengelolaan, buat resource tersebut di project pengelolaan.

Menelusuri keterampilan mandiri

Pratinjau

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

Anda dapat menelusuri kemampuan mandiri yang terdaftar di Agent Registry. Fitur ini memungkinkan Anda menemukan kemampuan yang dapat digunakan kembali untuk dilampirkan ke agen Anda.

Saat menelusuri skill, Anda menelusuri revisi skill default. Untuk memperbarui revisi default keahlian, lihat Memperbarui metadata keahlian atau revisi default.

Mode penelusuran

Anda dapat menggunakan dua mode penelusuran untuk skill berdasarkan kebutuhan Anda:

• Penelusuran kata kunci: hanya memindai atribut metadata dasar seperti nama tampilan, deskripsi, nama resource, dan ID keterampilan. Mode ini dioptimalkan untuk penelusuran latensi rendah, pencarian persis, dan pelengkapan otomatis nama. Misalnya, lihat Menelusuri keterampilan berdasarkan kata kunci atau ekspresi.
• Penelusuran semantik: mengindeks konten lengkap payload SKILL.md secara otomatis, termasuk petunjuk bahasa alami, skrip, dan aset metadata. Mode ini mengidentifikasi tema konseptual dan dioptimalkan untuk agen orchestrator yang menemukan paket kemampuan yang relevan secara dinamis, berdasarkan intent Anda. Sebagai contoh, lihat Menelusuri keterampilan berdasarkan makna semantik.

Kolom penelusuran dan sintaksis

Saat menelusuri berdasarkan string metadata atau kata kunci, kolom berikut akan diindeks:

Nama kolom	Perilaku huruf	Penelusuran awalan	Penelusuran semua kolom	Deskripsi
displayName	Tidak peka huruf besar/kecil	Ya	Ya	Nama tampilan keahlian. Gunakan kolom ini untuk menelusuri nama umum.
description	Tidak peka huruf besar/kecil	Tidak	Ya	Deskripsi mendetail tentang tujuan dan fungsi keahlian. Gunakan kolom ini untuk menelusuri kata kunci.
name	Tidak peka huruf besar/kecil	Ya	Ya	Nama resource skill. Gunakan kolom ini untuk menelusuri berdasarkan nama resource.
skillId	Tidak peka huruf besar/kecil	Ya	Ya	ID keahlian keahlian. Gunakan kolom ini untuk menemukan aset penayang tertentu. Misalnya, format untuk keahlian yang dikelola Google adalah urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID.
publisher	Tidak peka huruf besar/kecil	Ya	Tidak	Penayang yang terkait dengan skill. Gunakan kolom ini untuk memfilter menurut organisasi publikasi.
frontmatter.name	Tidak peka huruf besar/kecil	Tidak	Tidak	Nama keterampilan yang ditentukan dalam front matter file SKILL.md.
frontmatter.description	Tidak peka huruf besar/kecil	Tidak	Tidak	Deskripsi keahlian yang ditentukan dalam front matter file SKILL.md.
frontmatter.compatibility	Tidak peka huruf besar/kecil	Tidak	Tidak	Kompatibilitas skill yang ditentukan di front matter file SKILL.md.
frontmatter.license	Tidak peka huruf besar/kecil	Tidak	Tidak	Lisensi keterampilan yang ditentukan dalam front matter file SKILL.md.
createTime	Tidak berlaku	Tidak	Tidak	Stempel waktu saat keahlian dibuat. Kolom ini hanya tersedia di filter. Mendukung operator rentang, seperti <, >, dan pencocokan persis.
updateTime	Tidak berlaku	Tidak	Tidak	Stempel waktu saat keterampilan terakhir diperbarui. Kolom ini hanya tersedia di filter. Mendukung operator rentang, seperti <, >, dan pencocokan persis.

Untuk menelusuri keterampilan, berikan string kueri menggunakan flag --query di gcloud CLI atau parameter searchString di REST API. Anda dapat menggunakan elemen sintaksis berikut dalam permintaan penelusuran:

• Operator Boolean: menyertakan operator AND, OR, atau NOT untuk merangkai persyaratan.
• Filter khusus kolom: menargetkan kolom menggunakan operator :, misalnya, displayName:database.
• Penelusuran awalan: gunakan simbol karakter pengganti akhiran * untuk menemukan nilai yang dimulai dengan awalan tertentu, misalnya, displayName:cloud-*.

Telusuri keterampilan berdasarkan kata kunci atau ekspresi

Telusuri keterampilan yang memiliki awalan nama tampilan dan kata kunci deskripsi tertentu:

gcloud

Jalankan perintah gcloud alpha agent-registry skills search dengan --search-type=keyword:

gcloud alpha agent-registry skills search \
    --project=PROJECT_ID \
    --location=REGION \
    --query="displayName:cloud-* AND description:database" \
    --search-type=keyword

Ganti kode berikut:

• PROJECT_ID: project ID.
• REGION: region registry atau global.

REST

Kirim permintaan GET ke endpoint skills:search dengan searchString dan searchType=KEYWORD:

curl -G -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "searchString=displayName:cloud-* AND description:database" \
    --data-urlencode "searchType=KEYWORD" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/REGION/skills:search"

Ganti kode berikut:

• PROJECT_ID: project ID.
• REGION: region registry atau global.

Menelusuri keterampilan berdasarkan makna semantik

Temukan keterampilan yang terkait dengan pengelolaan database relasional menggunakan penelusuran semantik:

gcloud

Jalankan perintah gcloud alpha agent-registry skills search dengan --search-type=semantic:

gcloud alpha agent-registry skills search \
    --project=PROJECT_ID \
    --location=REGION \
    --query="manage and configure relational databases" \
    --search-type=semantic

Ganti kode berikut:

• PROJECT_ID: project ID.
• REGION: region registry atau global.

REST

Kirim permintaan GET ke endpoint skills:search dengan searchString dan searchType=SEMANTIC:

curl -G -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "searchString=manage and configure relational databases" \
    --data-urlencode "searchType=SEMANTIC" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/REGION/skills:search"

Ganti kode berikut:

• PROJECT_ID: project ID.
• REGION: region registry atau global.

Keahlian yang dikelola Google

Keahlian yang dikelola Google dapat ditemukan dari project mana pun. Untuk mengetahui daftar keahlian yang dikelola Google yang tersedia, lihat repositori google/skills di GitHub.

Menemukan endpoint dan memfilter komponen berdasarkan metadata

Anda juga dapat menemukan komponen apa pun di Agent Registry, termasuk endpoint terdaftar, dengan mencantumkan koleksinya dan memfilter kolom metadata terstruktur:

• Menemukan endpoint: karena resource Endpoint tidak mendukung kueri :search, Anda dapat menemukannya dengan menjelajahi tab Endpoints di konsolGoogle Cloud , menjalankan gcloud agent-registry endpoints list --filter, atau memanggil metode REST endpoints.list. Untuk petunjuk lengkap, lihat Mengelola dan menemukan endpoint.
• Memfilter agen, server MCP, dan skill: jika Anda mengetahui ID registry (URN), nama tampilan, atau atribut komponen, filter koleksi di konsolGoogle Cloud atau teruskan --filter ke gcloud agent-registry agents list, gcloud agent-registry mcp-servers list, atau gcloud alpha agent-registry skills list. Untuk mengetahui detailnya, lihat Mengelola agen, Mengelola server dan alat MCP, dan Mengelola kemampuan.