# レジストリレコードを検索する **今後の名前空間の移行** AWS エージェントレジストリは現在、bedrock-agentcore 名前空間のパブリックプレビュー中です。2026 年 8 月 6 日以降、サービスはエージェントレジストリ名前空間に移動します。 AWS エージェントレジストリを使用する場合は、エンドポイント、IAM ポリシー、SDK クライアント、CLI スクリプト、レジストリデータを更新する必要があります。パブリックプレビューからの移行の詳細については、[「包括的なレジストリ移行ガイド](registry-faq.md)」を参照してください。 ## リクエストパラメーター + **searchQuery** (必須): 1～256 文字の任意の自然言語クエリを使用できます + **registryIds** (必須): 検索を実行するレジストリ。1 つのレジストリ ARN または ID のみをサポート + **maxResults** (オプション): 検索レスポンスで返されるレコードの数。1～20 の任意の値を取ることができ、デフォルトは 10 です + **filters** (オプション) — メタデータフィルター式 ## メタデータフィルター 演算子: `$eq` 、`$ne`、`$in`。論理: `$and` 、`$or`。フィールド: name、descriptorType、version。 例: `{"descriptorType": {"$eq": "MCP"}}` 組み合わせ: `{"$and": [{"descriptorType": {"$eq": "MCP"}}, {"version": {"$eq": "1.0"}}]}` ## コンソール 1. レジストリの詳細ページを開きます。 1. **レコードの検索**タブを選択します。 1. 検索クエリを入力して結果を表示します。 **注記** コンソール検索は、IAM 認可レジストリでのみ使用できます。JWT 認可レジストリの場合は、HTTP クライアント ( など) と有効な JWT ベアラートークンで検索 API `curl` を直接使用するか、MCP クライアント経由でレジストリの MCP エンドポイントを使用します。 ## AWS CLI (IAM ベースのインバウンド認可を使用したレジストリ) ``` aws bedrock-agentcore search-registry-records \ --search-query "weather" \ --registry-ids "" \ --region us-east-1 ``` ## AWS SDK (IAM ベースのインバウンド認可を使用したレジストリ) ``` import boto3 client = boto3.client('bedrock-agentcore') response = client.search_registry_records( registryIds=[''], searchQuery='weather', maxResults=10 ) for record in response['registryRecords']: print(f"{record['name']} - {record['descriptorType']} - {record['status']}") ``` ## HTTP クライアント (OAuth ベースのインバウンド認可を使用したレジストリ) まず、ベアラートークンを取得します。 ``` SECRET_HASH=$(echo -n "" | openssl dgst -sha256 -hmac "" -binary | base64) aws cognito-idp initiate-auth \ --client-id "" \ --auth-flow USER_PASSWORD_AUTH \ --auth-parameters USERNAME="",PASSWORD='',SECRET_HASH="$SECRET_HASH" \ --region us-east-1 | jq -r '.AuthenticationResult.AccessToken' ``` 次に、ベアラートークンで検索します。 ``` curl -X POST "https://bedrock-agentcore..amazonaws.com/registry-records/search" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"registryIds": [""], "searchQuery": "weather", "maxResults": 10}' ``` ## AWS エージェントレジストリ検索の結果整合性 AWS エージェントレジストリは、検索インデックス作成に結果整合性モデルを使用します。コンソールから `UpdateRegistryRecordStatus`または を呼び出してレジストリレコードを承認すると、レコードは `SearchRegistryRecords`または の結果に`InvokeRegistryMcp`すぐには表示されません。通常、承認されたレコードのインデックスが作成されて検出可能になるまでに数秒かかりますが、場合によっては数分かかることがあります。 この間、次の動作が見られる場合があります。 + `SearchRegistryRecords` クエリは、承認されたばかりのレコードを返しません。 + レジストリ MCP エンドポイント () `InvokeRegistryMcp` には、最近承認されたレコードがツール結果に含まれていません。 **承認済み**ステータスのレコードのみが検索結果に含まれます。下書き、承認保留中、拒否済み、または非推奨ステータスのレコードは、 `SearchRegistryRecords`または `InvokeRegistryMcp` によって返されません。レコードの現在のステータスを確認するには`GetRegistryRecord`、 を呼び出します。これにより、インデックス作成状態に関係なく常に最新のリビジョンが返されます。 アプリケーションの結果整合性を処理するには、以下をお勧めします。 + レコードを承認したら、エクスポネンシャルバックオフを含む再試行戦略`SearchRegistryRecords`で を呼び出して、それが検出可能であることを確認します。 + 承認直後に検索結果に表示されない場合は、レジストリにレコードがないと想定しないでください。を呼び出し`GetRegistryRecord`て、レコードのステータスを確認します。 + Amazon EventBridge と を使用して承認ワークフローを統合する場合は、ダウンストリームシステムが新しく承認されたレコードの検索 API `UpdateRegistryRecordStatus` をクエリする前に、短い遅延を追加します。 AWS SDKs「 SDK およびツールリファレンスガイド」の[「再試行動作](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)」を参照してください。 * AWS SDKs * ## レコード属性が検索の関連性に与える影響 AWS エージェントレジストリは、セマンティック理解とキーワードマッチングを組み合わせて関連する結果を返すハイブリッド検索を使用します。検索するレコードが検索結果に表示されない場合は、どのレコード属性が検索に影響するかを理解することが役立ちます。 ### 検索に使用されるレコード属性 レジストリレコードの次の属性は、検索の関連性を判断するために使用されます。 + **名前** — キーワードの一致に使用されます。リソースが何をするかを示す明確でわかりやすい名前は、完全および部分的な名前検索の検出可能性を向上させます。 + **説明** — キーワードマッチングとセマンティックマッチングの両方に使用されます。リソースの目的と一般的なユースケースを説明する自然言語で記述された説明は、複雑な技術ラベルよりも発見可能です。 + **記述子** — プロトコル定義 (MCP サーバー定義、エージェントカード、スキルドキュメント、またはカスタム JSON) の完全なコンテンツがセマンティックマッチングに使用されます。これには、ツール名、ツールの説明、入力パラメータ名、機能の概要が含まれます。 + **バージョンと記述子タイプ** — フィルタリング可能なフィールドとして使用できます。コンシューマーは、、、`descriptorType`および `name` のメタデータフィルターを使用して結果を絞り込むことができます`version`。 ### 検索クエリの処理方法 を呼び出すと`SearchRegistryRecords`、 AWS Agent Registry はインデックス付きレコードの同じセットに対して 2 つの検索を並行して実行し、結果をマージします。 + **セマンティック検索** — クエリはベクトル表現に変換され、インデックス付きレコードのベクトル表現と比較されます。これにより、クエリ内の正確な単語がレコードに表示されない場合でも、概念的に関連したレコードが見つかります。たとえば、「フライトを予約する」のクエリは、「travel-reservation-service」という名前のレコードと一致することができます。 + **キーワード検索** — クエリは、従来のキーワードの関連性を使用してレコードフィールドのテキストコンテンツと照合されます。これは、正確な名前検索と特定の技術用語に対して有効です。たとえば、「 weather-api-v2」のクエリは、その正確なテキストを含むレコードと一致します。 リクエストにメタデータフィルターを含めると、結果がスコアリングおよびランク付けされる前に、両方の検索にフィルターが適用されます。つまり、フィルターは、ランキング後に結果をフィルタリングするのではなく、セマンティック検索とキーワード検索の両方が動作する候補セットを減らします。 ### 結果のランク付け方法 セマンティック検索とキーワード検索の両方の結果が 1 つのランク付けされたリストに結合され、最も関連性の高いレコードが最初に関連性の高い順に返されます。各結果の最終位置は、両方の検索における関連性によって決まります。セマンティック結果とキーワード結果の両方で高いランク付けを行うレコードは、1 つのみ高いランク付けを行うレコードよりも高くなります。キーワード検索では、レコード名はランク付けに最も大きく影響し、説明と記述子の内容が続きます。どちらの検索モードも常に実行され、最終的なランキングに反映されるため、クエリの記述方法は、どのレコードが表示されるかに影響します。以下のガイダンスは、インテントに応じてより良い結果を得るのに役立ちます。 ### 有効な検索クエリの記述 **正確な名前または識別子がわかっている場合**は、短い特定のクエリを使用します。キーワード検索は、正確なテキストをレコード名、説明、記述子コンテンツと照合します。"™-api-v2" や "pdf-processing" などの短いクエリは、名前でレコードを検索するのに有効です。 **機能またはユースケース で探索する場合は**、必要なものに関する自然言語の説明を使用します。セマンティック検索は概念的な意図を理解しているため、「フライトを予約できるツールを見つける」や「構造化データを PDF ドキュメントから抽出する」などのクエリは、正確な単語がレコードメタデータに表示されていなくても、関連するレコードと一致する可能性があります。 **同じクエリでフィルターのような制約とわかりやすいインテントを混在させないようにしてください。**「天気予報のすべての MCP サーバーを検索する」などのクエリは、セマンティック検索とキーワード検索の両方を通じて文全体を送信します。セマンティックコンポーネントは、完全な文を概念的な意図として解釈します。これにより、概念的に関連しているが、制約する特定の属性と一致しないレコードが表示される可能性があります。代わりに、属性ベースの制約にメタデータフィルターを使用し、クエリをトピックに集中させます。[「メタデータフィルターとクエリテキストを使用するタイミング](#registry-search-filters-vs-query)」を参照してください。 ### 検出可能なレコードの書き込み + リソースの動作と解決される問題を説明する説明を記述します。セマンティック検索はインテントを理解しているため、「お客様がパッケージの配信を追跡するのに役立ちます」は「delivery-status-endpoint」よりも検出可能です。 + MCP サーバーの完全なツール定義を提供します。ツールの説明と入力パラメータの説明はすべて、検索の関連性に影響します。 + 関連するキーワードを名前と説明に含めます。キーワード検索は正確なテキストと一致するため、コンシューマーが特定の用語を検索する可能性が高い場合は、それらの用語がレコードに表示されていることを確認してください。 ### メタデータフィルターとクエリテキストを使用するタイミング レコードタイプ、名前、バージョンなどの既知の属性によって結果を制限する場合は、メタデータフィルターを使用します。クエリテキスト自体にフィルターのような制約を埋め込まないでください。たとえば、天候に関連するすべての MCP サーバーを検索する場合は、レコードタイプのメタデータフィルターとトピックのクエリを使用します。 ``` { "searchQuery": "weather forecast", "filters": { "descriptorType": { "$eq": "MCP" } } } ``` 「天気予報のためにすべての MCP サーバーを検索する」などのクエリテキストに制約を置かないでください。長いクエリはセマンティックマッチングに傾くため、「MCP サーバー」という単語は、正確なフィルターとしてではなく、概念的なインテントの一部として解釈されます。これにより、セマンティックコンポーネントは、概念的に完全な文に関連し、フィルタリングする特定の属性と一致しないレコードを返す可能性があります。たとえば、MCP サーバーレコードとともに天気に関するエージェントレコードを返すなどです。属性ベースの制約にも同じことが当てはまります。特定の名前、バージョン、またはタイプのレコードが必要な場合は、クエリにそれらの用語を含めるのではなく、対応するメタデータフィルターを使用します。 次のフィールドでフィルタリングできます。 + `name` — レコードを正確な名前で一致させます。 + `descriptorType` — リソースタイプ (、、、 など) `MCP` `A2A` `SKILL` でレコード`CUSTOM`を一致させます。 + `version` — レコードをバージョン文字列で一致させます。 フィルターは`$eq`、 (等しい）、 `$ne` (等しくない）、 `$in` (リスト内の任意の値に一致) 演算子をサポートし、 `$and`および `$or` ロジックを使用して結合できます。 たとえば、気象関連の MCP サーバーのみを検索するには: ``` { "searchQuery": "weather forecast", "filters": { "descriptorType": { "$eq": "MCP" } } } ``` 特定のリソースタイプを除外するには: ``` { "searchQuery": "", "filters": { "descriptorType": { "$ne": "CUSTOM" } } } ``` 複数のバージョンのいずれかに一致するには: ``` { "filters": { "version": { "$in": ["1.0", "1.1", "2.0"] } } } ``` ### 検索は承認されたレコードのみを返します **承認済み**ステータスのレコードのみが検索結果と MCP エンドポイントに表示されます。ドラフト、保留中の承認、拒否、または廃止ステータスのレコードは返されません。最近承認されたレコードが結果に表示されない場合は、[AWS 「エージェントレジストリ検索の結果整合性](#registry-search-eventual-consistency)」を参照してください。