エージェント、ツール、スキルを検索する

エージェント エコシステムが拡大するにつれて、適切なエージェントやツールを見つけることが重要になります。Agent Registry には、エージェント、スキル、Model Context Protocol（MCP）サーバー全体で高度なキーワード検索、プレフィックス検索、セマンティック検索を実行できる検索機能が用意されています。

このドキュメントでは、環境内の機能を検出するための検索クエリを作成する方法について説明します。

始める前に

Agent Registry でエージェント、ツール、スキルを検索する前に、エージェントまたは MCP サーバーを登録します。これらのタスクを実行するには、プロジェクト ID も必要です。

このドキュメントの gcloud CLI コマンドを使用するには、Google Cloud CLI 環境を設定していることを確認してください。

必要なロール

エージェント レジストリでエージェント、ツール、スキルを検索するために必要な権限を取得するには、プロジェクトに対する Agent Registry API 閲覧者 （roles/agentregistry.viewer）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

エージェントとツールを検索する

レジストリ内の機能を見つけるには、登録済みのエージェントと MCP サーバーを検索します。

エージェントの検索では、エージェントの基本メタデータ、説明、AgentCard でインラインで宣言された説明的な A2A スキルが照合されます。MCP サーバーを検索すると、説明と決定論的なツールが一致します。

キーワード検索を実行して、エージェントの A2A スキルや MCP サーバーのツールなど、機能全体で特定の用語に一致するリソースを見つけることができます。これらの機能がレジストリでどのように構造化されているかについては、JSON スキーマをご覧ください。検索可能なフィールドの一覧については、API リファレンスをご覧ください。

キーワードで検索するには、--search-string フラグを指定します。このパラメータはフリーテキスト クエリを受け入れ、論理演算子（AND、OR、NOT）をサポートしています。

たとえば、フライトの予約を処理できるエージェントを検索します。

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

提供される特定のツールまたは説明に基づいて MCP サーバーを検索することもできます。たとえば、データベース ツールを提供する MCP サーバーを検索します。

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

次のように置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • REGION: レジストリ リージョン。

プレフィックス検索はレイテンシが最適化されているため、ユーザーの入力中にアプリケーションが関連するエージェントとツールを動的に取得できます。

オーケストレーター インターフェースまたはオートコンプリート機能を構築する場合は、Agent Registry で接頭辞検索を実行して、クエリ文字列の先頭に一致する結果を取得できます。プレフィックス検索では、接尾辞ワイルドカード記号（*）を使用して単語の先頭を照合します。

たとえば、表示名が特定の接頭辞（Best_A2A_* など）で始まるエージェントを検索します。

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

同様に、表示名が特定の接頭辞（Prod_Server_* など）で始まる MCP サーバーを検索できます。

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

次のように置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • REGION: レジストリ リージョン。

スタンドアロン スキルを検索する

Agent Registry に登録されているスタンドアロンのスキルを検索できます。この機能を使用すると、エージェントに接続する再利用可能な機能を見つけることができます。

スキルを検索すると、デフォルトのスキル リビジョンが検索されます。スキルのデフォルト リビジョンを更新するには、スキルのメタデータまたはデフォルト リビジョンを更新するをご覧ください。

検索モード

要件に応じて、スキルに 2 つの検索モードを使用できます。

  • キーワード検索: 表示名、説明、名前（URN）、スキル ID などの基本的なメタデータ属性のみをスキャンします。このモードは、低レイテンシの検索、照合、名前の自動補完に最適化されています。例については、キーワードまたは式でスキルを検索するをご覧ください。
  • セマンティック検索: 自然言語の指示、コード構造、アセットなど、SKILL.md ペイロードのコンテンツ全体を自動的にインデックス登録します。このモードは概念的なテーマに一致し、ユーザーの意図に基づいて関連する機能バンドルを動的に検出するオーケストレーター エージェント向けに最適化されています。例については、意味的意味でスキルを検索するをご覧ください。

検索フィールドと構文

メタデータまたはキーワード文字列で検索する場合、次のフィールドがインデックスに登録されます。

フィールド名 ケースの動作 接頭辞検索 すべてのフィールドを検索 説明
displayName 大文字 / 小文字の区別なし ○ ○ ユーザー向けのスキルの名前。このフィールドを使用して、一般的な名前を検索します。
description 大文字 / 小文字の区別なし × ○ スキルの目的と機能の詳細な説明。このフィールドを使用してキーワードを照合します。
name 大文字 / 小文字の区別なし ○ ○ スキルのプログラム識別子。このフィールドは、識別子文字列の一致に使用します。
skillId 大文字 / 小文字の区別なし ○ ○ スキルの論理 Uniform Resource Name（URN）。このフィールドを使用して、特定のパブリッシャーのアセットを検索します。たとえば、Google が作成したスキルの形式は urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID です。
publisher 大文字 / 小文字の区別なし ○ × スキルに関連付けられているパブリッシャー。このフィールドを使用して、公開組織でフィルタします。
frontmatter.name 大文字 / 小文字の区別なし × × SKILL.md ファイルの frontmatter で定義されたスキルの名前。
frontmatter.description 大文字 / 小文字の区別なし × × SKILL.md ファイルのフロントマターで定義されたスキルの説明。
frontmatter.compatibility 大文字 / 小文字の区別なし × × SKILL.md ファイルの frontmatter で定義されたスキルの互換性。
frontmatter.license 大文字 / 小文字の区別なし × × SKILL.md ファイルの frontmatter で定義されたスキルのライセンス。
createTime 該当なし × × スキルが作成されたときのタイムスタンプ。このフィールドはフィルタでのみ使用できます。範囲演算子（<、> など）と完全一致をサポートします。
updateTime 該当なし × × スキルが最後に更新されたときのタイムスタンプ。このフィールドはフィルタでのみ使用できます。範囲演算子（<、> など）と完全一致をサポートします。

スキルを検索するには、gcloud CLI の --query フラグまたは REST API の searchString パラメータを使用して、クエリ文字列を指定します。検索リクエストでは、次の構文要素を使用できます。

  • ブール演算子: AND、OR、NOT 演算子を含めて、要件を連結します。
  • フィールド固有のフィルタ: : 演算子を使用してフィールドをターゲットにします（例: displayName:database）。
  • プレフィックス マッチング: 接尾辞ワイルドカード記号（*）を使用して、特定のプレフィックスで始まる一致を検索します（例: displayName:cloud-*）。

キーワードや表現でスキルを検索する

たとえば、表示名の接頭辞と説明のキーワードに一致するスキルを検索します。

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

次のように置き換えます。

  • PROJECT_ID: プロジェクト ID
  • REGION: レジストリ リージョン

意味で学習内容を検索する

たとえば、セマンティック検索を使用して、リレーショナル データベースの管理に関連するスキルを見つけます。

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

次のように置き換えます。

  • PROJECT_ID: プロジェクト ID
  • REGION: レジストリ リージョン

公開スキル

Google が提供する公開スキルはグローバルであり、どのプロジェクトからでも検出できます。利用可能な公開スキルの一覧については、GitHub の google/skills リポジトリをご覧ください。

検索すると、Agent Registry は、出力内の公開スキルのリソース名を動的に書き換えて、ローカル プロジェクトでホストされているように表示します。このプロセスにより、統合が簡素化されます。