翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

レジストリレコードを検索する

コンシューマーは、SearchDiscoverableRegistryRecordsデータプレーン API を使用してレジストリの承認済みレコードを検索できます。API は自然言語クエリを受け入れ、セマンティック理解とキーワードマッチングを組み合わせたハイブリッド検索を適用し、最新のリビジョンのステータスが「承認済み」であるレコードに限定されたランク付け結果を返します。ドラフト、保留中の承認、拒否、または廃止ステータスのレコードは返されません。クエリなしでカタログを参照するには、 ListDiscoverableRegistryRecords と を使用します。BatchGetDiscoverableRegistryRecord代わりに、「承認済みレコードの参照」を参照してください。

MCP 互換クライアントを使用して、レジストリの MCP エンドポイント (InvokeRegistryMcp) を介して検出データプレーン APIs を呼び出すこともできます。エンドポイントはSearchDiscoverableRegistryRecords、、ListDiscoverableRegistryRecords、 を直接呼び出すことができる MCP ツールBatchGetDiscoverableRegistryRecordとして を公開します。

リクエストパラメーター

メタデータフィルター

演算子: $eq、$ne、$in。論理: $and、$or。フィールド: name、recordType、recordVersion。

例: {"recordType": {"$eq": "MCP"}}

組み合わせ: {"$and": [{"recordType": {"$eq": "MCP"}}, {"recordVersion": {"$eq": "1.0"}}]}

コンソール

AWS CLI (IAM ベースのインバウンド認可を使用したレジストリ)

AWS SDK (IAM ベースのインバウンド認可を使用したレジストリ)

HTTP クライアント (OAuth ベースのインバウンド認可を使用したレジストリ)

まず、ベアラートークンを取得します。

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'

次に、ベアラートークンで検索します。

AWS エージェントレジストリ検索の結果整合性

AWS エージェントレジストリは、検索インデックス作成に結果整合性モデルを使用します。コンソールから UpdateRegistryRecordStatusまたは を呼び出してレジストリレコードを承認すると、レコードは SearchDiscoverableRegistryRecordsまたは の結果にInvokeRegistryMcpすぐには表示されません。通常、承認されたレコードのインデックスが作成されて検出可能になるまでに数秒かかりますが、場合によっては数分かかることがあります。

この間、次の動作が見られる場合があります。

検出可能な結果には、承認済みステータスのレコードのみが含まれます。下書き、承認保留中、拒否済み、または非推奨ステータスのレコードは、検出可能なデータプレーン APIs または によって返されませんInvokeRegistryMcp。レコードの現在のステータスを確認するには、 を呼び出します。これによりGetRegistryRecord、インデックス作成状態に関係なく常に最新のリビジョンが返されます。

アプリケーションの結果整合性を処理するには、以下をお勧めします。

AWS SDKs「 SDK およびツールリファレンスガイド」の「再試行動作」を参照してください。 AWS SDKs

レコード属性が検索の関連性に与える影響

AWS エージェントレジストリは、セマンティック理解とキーワードマッチングを組み合わせて関連する結果を返すハイブリッド検索を使用します。検索するレコードが検索結果に表示されない場合は、どのレコード属性が検索に影響するかを理解することが役立ちます。

検索に使用されるレコード属性

レジストリレコードの次の属性は、検索の関連性を判断するために使用されます。

検索クエリの処理方法

を呼び出すとSearchDiscoverableRegistryRecords、 AWS Agent Registry はインデックス付きレコードの同じセットに対して 2 つの検索を並行して実行し、結果をマージします。

リクエストにメタデータフィルターを含めると、結果がスコアリングおよびランク付けされる前に、両方の検索にフィルターが適用されます。つまり、フィルターは、ランキング後に結果をフィルタリングするのではなく、セマンティック検索とキーワード検索の両方が動作する候補セットを減らします。

結果のランク付け方法

セマンティック検索とキーワード検索の両方の結果が 1 つのランク付けされたリストに結合され、最も関連性の高いレコードが最初に関連性の高い順に返されます。各結果の最終位置は、両方の検索における関連性によって決まります。セマンティック結果とキーワード結果の両方で高いランク付けを行うレコードは、1 つのみ高いランク付けを行うレコードよりも高くなります。キーワード検索では、レコード名はランク付けに最も大きく影響し、説明と記述子の内容が続きます。どちらの検索モードも常に実行され、最終的なランキングに反映されるため、クエリの記述方法は、どのレコードが表示されるかに影響します。以下のガイダンスは、インテントに応じてより良い結果を得るのに役立ちます。

有効な検索クエリの記述

正確な名前または識別子がわかっている場合は、短い特定のクエリを使用します。キーワード検索は、正確なテキストをレコード名、説明、記述子コンテンツと照合します。"™-api-v2" や "pdf-processing" などの短いクエリは、名前でレコードを検索するのに有効です。

機能またはユースケース で探索する場合は、必要なものに関する自然言語の説明を使用します。セマンティック検索は概念的な意図を理解しているため、「フライトを予約できるツールを見つける」や「構造化データを PDF ドキュメントから抽出する」などのクエリは、正確な単語がレコードメタデータに表示されていなくても、関連するレコードと一致する可能性があります。

同じクエリでフィルターのような制約とわかりやすいインテントを混在させないようにしてください。「天気予報のすべての MCP サーバーを検索する」などのクエリは、セマンティック検索とキーワード検索の両方を通じて文全体を送信します。セマンティックコンポーネントは、完全な文を概念的な意図として解釈します。これにより、概念的に関連しているが、制約する特定の属性と一致しないレコードが表示される可能性があります。代わりに、属性ベースの制約にメタデータフィルターを使用し、クエリをトピックに集中させます。「メタデータフィルターとクエリテキストを使用するタイミング」を参照してください。

検出可能なレコードの書き込み

メタデータフィルターとクエリテキストを使用するタイミング

レコードタイプ、名前、バージョンなどの既知の属性によって結果を制限する場合は、メタデータフィルターを使用します。クエリテキスト自体にフィルターのような制約を埋め込まないでください。たとえば、天候に関連するすべての MCP サーバーを検索する場合は、レコードタイプのメタデータフィルターとトピックのクエリを使用します。

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

「天気予報のためにすべての MCP サーバーを検索する」などのクエリテキストに制約を置かないでください。長いクエリはセマンティックマッチングに傾くため、「MCP サーバー」という単語は、正確なフィルターとしてではなく、概念的なインテントの一部として解釈されます。これにより、セマンティックコンポーネントは、概念的に完全な文に関連し、フィルタリングする特定の属性と一致しないレコードを返す可能性があります。たとえば、MCP サーバーレコードとともに天気に関するエージェントレコードを返すなどです。属性ベースの制約にも同じことが当てはまります。特定の名前、バージョン、またはタイプのレコードが必要な場合は、クエリにそれらの用語を含めるのではなく、対応するメタデータフィルターを使用します。

次のフィールドでフィルタリングできます。

フィルターは$eq、 (等しい）、 $ne (等しくない）、 $in (リスト内の任意の値に一致) 演算子をサポートし、 $andおよび $or ロジックを使用して結合できます。

たとえば、気象関連の MCP サーバーのみを検索するには:

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

特定のリソースタイプを除外するには:

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

複数のバージョンのいずれかに一致するには:

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

検索は承認されたレコードのみを返します

承認済みステータスのレコードのみが検索結果と MCP エンドポイントに表示されます。ドラフト、保留中の承認、拒否、または廃止ステータスのレコードは返されません。最近承認されたレコードが結果に表示されない場合は、AWS 「エージェントレジストリ検索の結果整合性」を参照してください。