Menelusuri agen, alat, dan keterampilan

Seiring berkembangnya ekosistem agen Anda, menemukan agen atau alat yang tepat menjadi sangat penting. Agent Registry menyediakan kemampuan penelusuran yang memungkinkan Anda melakukan penelusuran semantik, awalan, dan kata kunci lanjutan di seluruh agen, keterampilan, dan server Model Context Protocol (MCP) Anda.

Dokumen ini menjelaskan cara membuat kueri penelusuran untuk menemukan kemampuan dalam lingkungan Anda.

Sebelum memulai

Sebelum Anda menelusuri agen, alat, atau kemampuan di Agent Registry, daftarkan agen atau server MCP. Anda juga memerlukan project ID Anda untuk melakukan tugas ini.

Untuk menggunakan perintah gcloud CLI dalam dokumen ini, pastikan Anda telah menyiapkan lingkungan Google Cloud CLI.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna menelusuri agen, alat, dan keterampilan di Agent Registry, minta administrator untuk memberi Anda peran IAM Agent Registry API Viewer (roles/agentregistry.viewer) di project. Untuk mengetahui informasi selengkapnya tentang cara memberikan 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.

Penelusuran agen mencocokkan metadata dasar, deskripsi, dan kemampuan A2A deskriptif yang dideklarasikan secara inline di Kartu Agen mereka. Penelusuran server MCP yang cocok dengan deskripsi dan alat deterministiknya.

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

Untuk menelusuri berdasarkan kata kunci, berikan tanda --search-string. Parameter ini menerima kueri teks bebas dan mendukung operator logis: AND, OR, dan NOT.

Misalnya, telusuri agen yang dapat menangani pemesanan penerbangan:

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

Anda juga dapat menelusuri server MCP berdasarkan alat tertentu yang ditawarkannya atau deskripsinya. Misalnya, 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 registri.

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

Jika Anda membuat antarmuka orkestrator atau fitur pelengkapan otomatis, Anda dapat melakukan penelusuran awalan di Agent Registry untuk mendapatkan hasil yang cocok dengan awal string kueri. Penelusuran awalan menggunakan simbol karakter pengganti akhiran (*) untuk mencocokkan awal kata.

Misalnya, telusuri agen yang nama tampilannya dimulai dengan awalan tertentu, seperti Best_A2A_*:

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

Demikian pula, Anda dapat menelusuri server MCP yang nama tampilannya diawali dengan awalan tertentu, seperti 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 registri.

Menelusuri keterampilan mandiri

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

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

Mode penelusuran

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

  • Penelusuran kata kunci: Hanya memindai atribut metadata dasar seperti nama tampilan, deskripsi, nama (URN), dan ID skill. Mode ini dioptimalkan untuk penelusuran, pencocokan, dan pelengkapan otomatis nama dengan latensi rendah. Untuk contoh, lihat Menelusuri keterampilan berdasarkan kata kunci atau ekspresi.
  • Penelusuran semantik: Mengindeks secara otomatis seluruh konten payload SKILL.md, termasuk petunjuk bahasa natural, struktur kode, dan aset. Mode ini mencocokkan tema konseptual dan dioptimalkan untuk agen orkestrator yang menemukan paket kemampuan yang relevan secara dinamis, berdasarkan maksud Anda. Untuk contohnya, lihat Menelusuri keterampilan berdasarkan makna semantik.

Kolom dan sintaksis penelusuran

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

Nama kolom Perilaku casing Penelusuran awalan Penelusuran semua kolom Deskripsi
displayName Tidak peka huruf besar/kecil Ya Ya Nama skill yang ditampilkan kepada pengguna. 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 mencocokkan kata kunci.
name Tidak peka huruf besar/kecil Ya Ya ID terprogram untuk skill. Gunakan kolom ini untuk kecocokan pada string ID.
skillId Tidak peka huruf besar/kecil Ya Ya Nama Resource Seragam (URN) logis dari skill. Gunakan kolom ini untuk menemukan aset penayang tertentu. Misalnya, format untuk skill buatan 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 penerbit.
frontmatter.name Tidak peka huruf besar/kecil Tidak Tidak Nama skill yang ditentukan di frontmatter file SKILL.md.
frontmatter.description Tidak peka huruf besar/kecil Tidak Tidak Deskripsi skill yang ditentukan dalam frontmatter file SKILL.md.
frontmatter.compatibility Tidak peka huruf besar/kecil Tidak Tidak Kompatibilitas keterampilan yang ditentukan dalam frontmatter file SKILL.md.
frontmatter.license Tidak peka huruf besar/kecil Tidak Tidak Lisensi skill yang ditentukan dalam frontmatter file SKILL.md.
createTime Tidak berlaku Tidak Tidak Stempel waktu saat keahlian dibuat. Kolom ini hanya tersedia di filter. Mendukung operator rentang, seperti <, >, dan kecocokan persis.
updateTime Tidak berlaku Tidak Tidak Stempel waktu saat skill terakhir diperbarui. Kolom ini hanya tersedia di filter. Mendukung operator rentang, seperti <, >, dan kecocokan persis.

Untuk menelusuri keterampilan, berikan string kueri menggunakan tanda --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 menggabungkan persyaratan.
  • Filter khusus kolom: menargetkan kolom menggunakan operator :, misalnya, displayName:database.
  • Pencocokan imbuhan: gunakan simbol karakter pengganti akhiran (*) untuk menemukan kecocokan yang dimulai dengan imbuhan tertentu, misalnya, displayName:cloud-*.

Menelusuri keterampilan berdasarkan kata kunci atau ekspresi

Misalnya, telusuri keterampilan yang cocok dengan awalan nama tampilan dan kata kunci deskripsi:

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: the project ID
  • REGION: region pendaftaran

Menelusuri keterampilan berdasarkan makna semantik

Misalnya, temukan keterampilan yang terkait dengan pengelolaan database relasional menggunakan penelusuran semantik:

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: the project ID
  • REGION: region pendaftaran

Keahlian publik

Skill publik yang disediakan oleh Google bersifat global dan dapat ditemukan dari project mana pun. Untuk mengetahui daftar keahlian publik yang tersedia, lihat repositori google/skills di GitHub.

Saat Anda melakukan penelusuran, Agent Registry secara dinamis menulis ulang nama resource skill publik dalam output sehingga skill tersebut tampak dihosting di project lokal Anda. Proses ini menyederhanakan integrasi.