Cari catatan registri

Parameter Permintaan

Filter metadata

Operator:$eq,$ne,$in. Logis:$and,$or. Bidang: nama, DescriptorType, versi.

Contoh: {"descriptorType": {"$eq": "MCP"}}

Gabungan: {"$and": [{"descriptorType": {"$eq": "MCP"}}, {"version": {"$eq": "1.0"}}]}

Konsol

AWS CLI (Registri dengan Otorisasi Masuk berbasis IAM)

aws bedrock-agentcore search-registry-records \
  --search-query "weather" \
  --registry-ids "<registryARN>" \
  --region us-east-1

AWS SDK (Registri dengan Otorisasi Masuk berbasis IAM)

import boto3

client = boto3.client('bedrock-agentcore')

response = client.search_registry_records(
    registryIds=['<registryARN>'],
    searchQuery='weather',
    maxResults=10
)
for record in response['registryRecords']:
    print(f"{record['name']} - {record['descriptorType']} - {record['status']}")

Klien HTTP (Registri dengan Otorisasi Masuk berbasis OAuth)

Pertama, dapatkan token pembawa:

SECRET_HASH=$(echo -n "<username><appClientId>" | openssl dgst -sha256 -hmac "<appClientSecret>" -binary | base64)

aws cognito-idp initiate-auth \
  --client-id "<appClientId>" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME="<username>",PASSWORD='<password>',SECRET_HASH="$SECRET_HASH" \
  --region us-east-1 | jq -r '.AuthenticationResult.AccessToken'

Kemudian cari dengan token pembawa:

curl -X POST "https://bedrock-agentcore.<region>.amazonaws.com/registry-records/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"registryIds": ["<registryARN>"], "searchQuery": "weather", "maxResults": 10}'

Konsistensi akhirnya di AWS Pencarian Agen Registry

AWS Agent Registry menggunakan model yang akhirnya konsisten untuk pengindeksan pencarian. Saat Anda menyetujui catatan registri dengan menelepon UpdateRegistryRecordStatus atau melalui konsol, catatan tidak muncul SearchRegistryRecords atau langsung InvokeRegistryMcp muncul. Biasanya diperlukan beberapa detik untuk catatan yang disetujui untuk diindeks dan dapat ditemukan, tetapi dalam beberapa kasus dapat memakan waktu hingga beberapa menit.

Selama waktu ini, Anda mungkin mengamati perilaku berikut:

Hanya catatan dalam status Disetujui yang disertakan dalam hasil penelusuran. Catatan dalam Draf, Persetujuan Tertunda, Ditolak, atau status Usang tidak pernah dikembalikan oleh atau. SearchRegistryRecords InvokeRegistryMcp Anda dapat memverifikasi status rekaman saat ini dengan meneleponGetRegistryRecord, yang selalu menampilkan revisi terbaru terlepas dari status pengindeksan.

Untuk menangani konsistensi akhir dalam aplikasi Anda, kami merekomendasikan hal berikut:

Untuk panduan umum tentang mengonfigurasi perilaku coba lagi di AWS SDK, lihat Coba lagi perilaku di Panduan Referensi AWS SDK dan Alat.

Bagaimana atribut rekaman memengaruhi relevansi penelusuran

AWS Agen Registry menggunakan pencarian hibrida yang menggabungkan pemahaman semantik dengan pencocokan kata kunci untuk mengembalikan hasil yang relevan. Jika rekaman yang Anda harapkan tidak muncul di hasil penelusuran, memahami atribut rekaman mana yang memengaruhi penelusuran dapat membantu.

Atribut rekaman mana yang digunakan untuk pencarian

Atribut berikut dari catatan registri Anda digunakan untuk menentukan relevansi penelusuran:

Bagaimana kueri penelusuran diproses

Saat Anda meneleponSearchRegistryRecords, AWS Agent Registry menjalankan dua penelusuran secara paralel terhadap kumpulan rekaman yang diindeks yang sama dan menggabungkan hasilnya:

Jika Anda menyertakan filter metadata dalam permintaan Anda, filter diterapkan ke kedua pencarian sebelum hasil dinilai dan diberi peringkat. Ini berarti filter mengurangi kumpulan kandidat tempat pencarian semantik dan kata kunci beroperasi, daripada memfilter hasil setelah peringkat.

Bagaimana hasil diberi peringkat

Hasil dari pencarian semantik dan kata kunci digabungkan menjadi satu daftar peringkat dan dikembalikan dalam urutan relevansi, dengan catatan yang paling relevan terlebih dahulu. Posisi akhir setiap hasil ditentukan oleh relevansinya di kedua pencarian — catatan yang berperingkat tinggi dalam hasil semantik dan kata kunci akan muncul lebih tinggi daripada catatan yang berperingkat tinggi hanya dalam satu. Dalam pencarian kata kunci, nama rekaman memiliki pengaruh terkuat pada peringkat, diikuti oleh deskripsi dan konten deskriptor, yang berkontribusi sama. Karena kedua mode penelusuran selalu berjalan dan berkontribusi pada peringkat akhir, cara Anda menulis kueri memengaruhi catatan mana yang muncul. Panduan berikut dapat membantu Anda mendapatkan hasil yang lebih baik tergantung pada niat Anda.

Menulis kueri penelusuran yang efektif

Saat Anda mengetahui nama atau pengenal yang tepat, gunakan kueri singkat dan spesifik. Pencarian kata kunci cocok dengan teks yang tepat dengan nama rekaman, deskripsi, dan konten deskriptor. Kueri singkat seperti “weather-api-v2" atau “pdf-processing” efektif untuk menemukan catatan berdasarkan nama.

Saat Anda menjelajahi berdasarkan kemampuan atau kasus penggunaan, gunakan deskripsi bahasa alami tentang apa yang Anda butuhkan. Pencarian semantik memahami maksud konseptual, sehingga kueri seperti “temukan alat yang dapat memesan penerbangan” atau “ekstrak data terstruktur dari dokumen PDF” dapat cocok dengan catatan yang relevan meskipun kata-kata yang tepat itu tidak muncul dalam metadata rekaman.

Hindari mencampur batasan seperti filter dengan maksud deskriptif dalam kueri yang sama. Kueri seperti “temukan semua server MCP untuk ramalan cuaca” mengirimkan seluruh kalimat melalui pencarian semantik dan kata kunci. Komponen semantik menafsirkan kalimat lengkap sebagai maksud konseptual, yang dapat memunculkan catatan yang terkait secara konseptual tetapi tidak cocok dengan atribut spesifik yang ingin Anda batasi. Sebagai gantinya, gunakan filter metadata untuk batasan berbasis atribut dan jaga agar kueri tetap fokus pada topik. Lihat Kapan menggunakan filter metadata versus teks kueri.

Menulis catatan yang dapat ditemukan

Kapan menggunakan filter metadata versus teks kueri

Gunakan filter metadata ketika maksud Anda adalah untuk membatasi hasil dengan atribut yang dikenal seperti jenis rekaman, nama, atau versi. Jangan menyematkan batasan seperti filter dalam teks kueri itu sendiri. Misalnya, jika Anda ingin menemukan semua server MCP yang terkait dengan cuaca, gunakan filter metadata untuk jenis rekaman dan kueri untuk topik:

{
  "searchQuery": "weather forecast",
  "filters": {
    "descriptorType": { "$eq": "MCP" }
  }
}

Hindari memasukkan kendala ke dalam teks kueri seperti “temukan semua server MCP untuk prakiraan cuaca”. Karena kueri yang lebih panjang condong ke arah pencocokan semantik, kata-kata “server MCP” ditafsirkan sebagai bagian dari maksud konseptual daripada sebagai filter yang tepat. Hal ini dapat menyebabkan komponen semantik mengembalikan catatan yang secara konseptual terkait dengan kalimat lengkap tetapi tidak cocok dengan atribut spesifik yang ingin Anda filter — misalnya, mengembalikan catatan agen tentang cuaca bersama catatan server MCP. Hal yang sama berlaku untuk kendala berbasis atribut apa pun. Jika Anda menginginkan catatan dengan nama, versi, atau jenis tertentu, gunakan filter metadata yang sesuai daripada menyertakan istilah tersebut dalam kueri.

Anda dapat memfilter pada bidang berikut:

Filter mendukung $eq (sama), $ne (tidak sama), dan $in (cocok dengan nilai apa pun dalam daftar) operator, dan dapat digabungkan menggunakan $and dan $or logika.

Misalnya, untuk mencari server MCP terkait cuaca saja:

{
  "searchQuery": "weather forecast",
  "filters": {
    "descriptorType": { "$eq": "MCP" }
  }
}

Untuk mengecualikan jenis sumber daya tertentu:

{
  "searchQuery": "<your query>",
  "filters": {
    "descriptorType": { "$ne": "CUSTOM" }
  }
}

Untuk mencocokkan salah satu dari beberapa versi:

{
  "filters": {
    "version": { "$in": ["1.0", "1.1", "2.0"] }
  }
}

Pencarian hanya mengembalikan catatan yang disetujui

Hanya catatan dalam status Disetujui yang muncul di hasil penelusuran dan melalui titik akhir MCP. Catatan dalam Draf, Persetujuan Tertunda, Ditolak, atau Status Usang tidak dikembalikan. Jika catatan yang baru disetujui tidak muncul di hasil, lihat Konsistensi akhir dalam pencarian AWS Agen Registri.