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

Agent Registry を使用すると、 Google Cloud コンソール、Google Cloud CLI、または Agent Registry API で、キーワード、接頭辞、または自然言語を使用して、登録済みのエージェント、Agent2Agent（A2A）スキル、スタンドアロン スキル、Model Context Protocol（MCP）サーバーを検索できます。キーワード検索と接頭辞検索を使用すると、名前、識別子、メタデータでリソースをすばやく見つけることができます。セマンティック検索では、インテントに基づいて、自然言語の指示と説明全体で概念的に関連する機能が検索されます。

検索クエリは、エージェント、MCP サーバー、スキル機能の説明、ツールスキーマ、スキル指示を評価します。検索クエリを使用してエンドポイントを検出することはできません。メタデータでエンドポイントを一覧表示してフィルタする手順については、メタデータでエンドポイントを検出してコンポーネントをフィルタするをご覧ください。

始める前に

  1. Agent Registry を設定する。

  2. 単一プロジェクトの設定の場合は、Agent Registry が有効になっているガバナンス プロジェクトのプロジェクト ID を取得します。複数のプロジェクトに管理境界を構成した場合は、境界全体の検出と登録に管理プロジェクトの ID を使用するか、単一プロジェクトのオペレーションにメンバー プロジェクト ID を指定します。

  3. Agent Registry にエージェント、MCP サーバー、またはスキルを登録する。

  4. このドキュメントの Google Cloud CLI コマンドを使用するには、gcloud CLI 環境を設定します。

必要なロール

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

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

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

レジストリ内の機能を検出するには、 Google Cloud コンソール、gcloud CLI、または REST API で登録済みのエージェントと MCP サーバーを検索します。

エージェントまたは MCP サーバーを検索する場合は、表示名、説明、機能キーワードでクエリを実行できます。

  • エージェント: 検索クエリは、エージェントの表示名、説明、エージェント ID、エージェント カードで宣言されたインライン A2A スキルの名前、説明、タグをチェックして、一致するものを探します。
  • MCP サーバー: 検索クエリは、サーバーの表示名、説明、MCP サーバー識別子、ツールの名前と説明をチェックして、一致するものを探します。

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

キーワード クエリはフリーテキスト文字列を受け入れ、論理演算子 AND、OR、NOT をサポートします。

コンソール

  1. Google Cloud コンソールで [Agent Registry] に移動します。

    [Agent Registry] に移動

  2. プロジェクト選択ツールで、 Google Cloud プロジェクトを選択します。

  3. ページ上部の [レジストリを検索] バーに、3 文字以上のキーワード クエリ（flight や database など）またはフィールド フィルタ（Name:booking など）を入力し、Enter を押します。

    [検索結果] テーブルには、選択したロケーションで一致するエージェント、MCP サーバー、スタンドアロン スキルが表示されます。

gcloud

gcloud agent-registry agents search コマンドまたは gcloud agent-registry mcp-servers search コマンドに --search-string フラグを指定します。

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

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

データベース ツールを提供する MCP サーバーを検索します。

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

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

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

REST

リクエスト本文に searchString フィールドを指定して、agents:search または mcpServers:search エンドポイントに POST リクエストを送信します。

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

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "flight OR booking"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

データベース ツールを提供する MCP サーバーを検索します。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "database"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/mcpServers:search"

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

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

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

オーケストレーター インターフェースまたは予測入力機能を構築している場合は、Agent Registry で前方一致検索を実行して、指定された文字列で始まる結果を見つけることができます。接頭辞検索では、* 接尾辞ワイルドカード記号を使用して単語の先頭を検索します。

gcloud

接頭辞式を指定して gcloud agent-registry agents search コマンドまたは gcloud agent-registry mcp-servers search コマンドを実行します。

たとえば、表示名が 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: レジストリ リージョンまたは global。

REST

リクエスト本文の searchString フィールドに接頭辞式を渡します。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "displayName:Best_A2A_*"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

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

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

管理境界を越えて検索する

管理境界を構成した場合は、管理プロジェクトから、その境界内のすべてのメンバー プロジェクトのロケーションでエージェントと MCP サーバーを検索できます。

gcloud agent-registry agents search \
    --project=MANAGEMENT_PROJECT_ID \
    --location=LOCATION \
    --search-string="analytics"

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

  • MANAGEMENT_PROJECT_ID: 管理プロジェクトの ID。
  • LOCATION: 管理境界をまたいで検索するロケーション。us-central1 などのリージョン、us や eu などのマルチリージョン、global など。Agent Registry は、管理プロジェクトと境界内のすべてのメンバー プロジェクトにわたって、同じロケーションのリソースを集約します。

管理プロジェクトの結果を特定のメンバー プロジェクトに絞り込むには、--filter フラグを "project_id=MEMBER_PROJECT_ID" に設定して渡します。プロジェクト間のロールアップを行わずに、単一のメンバー プロジェクト内のみを検索するには、代わりに --project フラグにそのメンバー プロジェクトの ID を指定します。

管理プロジェクトから検索する場合:

  • 自動検出されたリソースの集計: Agent Registry は、管理境界内のすべてのメンバー プロジェクトから、指定されたロケーションにある自動検出されたエージェントと MCP サーバーを検索します。また、管理プロジェクトのそのロケーションに作成された登録済みの Service リソースも検索します。
  • リクエスト スコープのリソース名: 検索結果で、返された各 Agent リソースまたは McpServer リソースの name フィールドは、コンポーネントの ID を保持し、リクエスト URL で指定されたプロジェクトを使用します。
  • プロジェクトを対象とした登録済みリソース: 手動で登録された Service リソースと、メンバー プロジェクトで作成された Binding リソースは、そのメンバー プロジェクトを対象としたままになり、管理プロジェクトの検索結果には表示されません。管理境界を越えて表示できるようにするには、管理プロジェクトで作成します。

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

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

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

検索モード

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

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

検索フィールドと構文

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

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

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

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

キーワードまたは表現でスキルを検索する

特定の表示名の接頭辞と説明キーワードを持つスキルを検索します。

gcloud

--search-type=keyword を指定して gcloud alpha agent-registry skills search コマンドを実行します。

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

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

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

REST

searchString と searchType=KEYWORD を使用して、skills:search エンドポイントに GET リクエストを送信します。

curl -G -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "searchString=displayName:cloud-* AND description:database" \
    --data-urlencode "searchType=KEYWORD" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/REGION/skills:search"

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

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

セマンティックな意味でスキルを検索する

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

gcloud

--search-type=semantic を指定して gcloud alpha agent-registry skills search コマンドを実行します。

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

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

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

REST

searchString と searchType=SEMANTIC を使用して、skills:search エンドポイントに GET リクエストを送信します。

curl -G -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "searchString=manage and configure relational databases" \
    --data-urlencode "searchType=SEMANTIC" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/REGION/skills:search"

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

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

Google が管理するスキル

Google が管理するスキルは、どのプロジェクトからでも検出できます。利用可能な Google が管理するスキルのリストについては、GitHub の google/skills リポジトリをご覧ください。

エンドポイントを検出し、メタデータでコンポーネントをフィルタする

また、コレクションを一覧表示し、構造化メタデータ フィールドでフィルタリングすることで、登録済みのエンドポイントなど、Agent Registry 内のコンポーネントを検出することもできます。

  • エンドポイントを検出する: Endpoint リソースは :search クエリをサポートしていないため、Google Cloud コンソールの [エンドポイント] タブを閲覧するか、gcloud agent-registry endpoints list --filter を実行するか、endpoints.list REST メソッドを呼び出して検出します。詳しい手順については、エンドポイントを管理して検出するをご覧ください。
  • エージェント、MCP サーバー、スキルをフィルタする: コンポーネントのレジストリ ID（URN）、表示名、属性がわかっている場合は、Google Cloud コンソールでコレクションをフィルタするか、--filter を gcloud agent-registry agents list、gcloud agent-registry mcp-servers list、gcloud alpha agent-registry skills list に渡します。詳細については、エージェントを管理する、MCP サーバーとツールを管理する、スキルを管理するをご覧ください。