エージェントを管理

エージェントのフリートを効果的に管理するには、ワークロードの進化に合わせてエージェントの詳細を表示して更新し、メタデータをオーバーライドするか、使用されなくなったエージェントを削除して、レジストリを正確に保つ必要があります。

このドキュメントでは、登録済みエージェントの詳細と構成を表示して変更する方法について説明します。

始める前に

エージェントを管理する前に、エージェント レジストリにエージェントが登録されていることを確認してください。これらのタスクを行うには、プロジェクト ID も必要です。

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

必要なロール

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

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

利用可能なエージェントを検出する

エージェントを登録すると、環境内でエージェントを検出して、エンドポイント、スキル、関連するメタデータなどの詳細な構成を表示できます。

エージェントの一覧表示と確認

環境に登録されているすべてのエージェントを一覧表示し、エンドポイント、スキル、関連するメタデータなどの詳細な構成を表示できます。

コンソール

  1. Google Cloud コンソールで、[エージェント レジストリ] に移動します。

    Agent Registry に移動

  2. プロジェクト選択ツールから、エージェント レジストリを設定した Google Cloud プロジェクトを選択します。

  3. [エージェント] タブを選択します。

    このページには、登録されているすべてのエージェントのリストが表示されます。リストには、エージェントの名前、識別子、タイプ、説明、バージョン、ランタイム、ロケーションが含まれます。

  4. エージェントの詳細を表示するには、エージェントの名前をクリックします。

gcloud

特定のロケーションにあるすべてのエージェントを一覧表示するには、agents list コマンドを使用します。

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

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

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

登録済みエージェントをフィルタする

複数のエージェントがある場合や、特定のエージェントの登録を確認する場合は、エージェントのメタデータでリストをフィルタできます。

コンソール

  1. Google Cloud コンソールで、[エージェント レジストリ] に移動します。

    Agent Registry に移動

  2. プロジェクト選択ツールから、エージェント レジストリを設定した Google Cloud プロジェクトを選択します。

  3. [エージェント] タブを選択します。

    このページには、登録されているすべてのエージェントのリストが表示されます。リストには、エージェントの名前、識別子、タイプ、説明、バージョン、ランタイム、ロケーションが含まれます。

  4. エージェントのロケーションまたはランタイム リソースでリストをフィルタします。

    • 地域でフィルタするには、[地域] メニューをクリックし、フィルタする地域を選択して、[適用] をクリックします。
    • ランタイムでフィルタするには、[ランタイム] メニューをクリックし、フィルタするランタイムを選択して、[適用] をクリックします。

    このページには、選択した条件でフィルタされた登録済みエージェントのリストが表示されます。

gcloud

--filter フラグを使用して、特定のメタデータに一致するリソースのみを返すようにエージェント リストをフィルタします。

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

FILTER_EXPRESSION は、フィルタするエージェントのフィルタ式に置き換えます。たとえば、次のフィルタを使用できます。

  • 表示名でフィルタするには、displayName='DISPLAY_NAME' を使用します。
  • グローバルに一意の識別子（URN）で検索するには、agentId='urn:agent:AGENT_URN' を使用します。

エージェントの詳細を表示する

特定のエージェントの詳細（プロトコル、スキル、ID など）を表示します。

コンソール

  1. Google Cloud コンソールで、[エージェント レジストリ] に移動します。

    Agent Registry に移動

  2. プロジェクト選択ツールから、エージェント レジストリを設定した Google Cloud プロジェクトを選択します。

  3. [エージェント] タブを選択します。

    このページには、登録されているすべてのエージェントのリストが表示されます。リストには、エージェントの名前、識別子、タイプ、説明、バージョン、ランタイム、ロケーションが含まれます。

  4. 表示するエージェントの名前をクリックします。

    詳細ページには、エージェントの詳細のタブが表示されます。

  5. 対応するタブをクリックして、特定のエージェントの詳細を表示します。

    利用できる機能はランタイムによって異なります。[セッション]、[プレイグラウンド]、[メモリ]、[評価] などのタブは、Vertex AI Agent Engine などのマネージド ランタイムで構築されたエージェントに表示される特定の機能です。

    • 概要: エージェントのコアの詳細（エージェントの名前、識別子、ロケーション、説明、ランタイムなど）。概要には、スキルとリソース URI も表示されます。これらは、トポロジグラフでクエリを構築するために必要です。
    • オブザーバビリティ: レイテンシ、トラフィック、エラー、トークン費用など、アプリケーション中心の分析情報。このタブは Google Cloud Observability ツールと統合され、リアルタイムのパフォーマンス指標とシステムレベルの使用率が表示されるため、費用とユーザー エクスペリエンスの管理に役立ちます。詳細については、オブザーバビリティの概要をご覧ください。
    • トレース: 会話の正確なパスをステップごとに示します。入力とアシスタント メッセージの詳細な形式を含み、複雑なマルチエージェント推論ループやツール呼び出しエラーをリアルタイムでデバッグできます。詳細については、エージェントのトレースを表示するをご覧ください。
    • セキュリティ: Model Armor と Security Command Center からの検出結果（コンテンツ ポリシー違反、データ漏洩のリスク、コンプライアンス評価など）。セキュリティの詳細については、セキュリティの検出結果を表示するをご覧ください。
    • トポロジ: エージェント、割り当てられたエージェント ゲートウェイ、エージェントがやり取りする MCP サーバー間の関係とトラフィック フローの視覚的なマップ。エージェント ゲートウェイの詳細については、エージェント ゲートウェイの概要をご覧ください。トポロジの詳細については、登録済みエージェントのグラフを表示するをご覧ください。
    • ID: ポリシーの適用に使用されるエージェント プリンシパル。この ID は、たとえば、ツールとリソースに対する認証の認証プロバイダ バインディングを構成するために使用します。
    • セッション: 永続的な会話履歴と、エージェントとのアクティブなインタラクションの追跡。
    • プレイグラウンド: エージェントの動作をテストするための直接チャット インターフェース。
    • メモリ: エージェントとの過去の会話から詳細を生成または呼び出し、やり取り全体でコンテキストを保持する長期的なパーソナライズ機能。
    • 評価: すべてのエージェント評価タスクの詳細。このタブでは、新しい評価タスクの作成、指標のアップロード、ライブ トラフィックまたは合成シミュレーションに対するエージェントの認知パフォーマンスとモデルの信頼性の評価を行うことができます。

gcloud

特定のエージェントの詳細なメタデータを表示するには、agents describe コマンドを使用します。

gcloud alpha agent-registry agents describe AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION

AGENT_NAME は、エージェントの名前に置き換えます（例: my-custom-agent）。

エージェントのメタデータとエンドポイントを更新する

エージェントのランタイム URL が変更された場合や、表示名、説明、仕様をオーバーライドする場合は、エージェントのメタデータを更新できます。

Agent Registry API の場合、検出には Agent リソースが使用されます。したがって、登録済みの Service リソースを直接更新する必要があります。

特定のフラグを指定して Google Cloud CLI を使用し、エージェントのパラメータを変更します。

  • 表示名と説明を更新する: --display-name フラグと --description フラグを使用します。例:

    gcloud alpha agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="New display name" \
  --description="Updated description of the agent's purpose."

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

    • AGENT_NAME: エージェントの名前（例: my-support-agent）。
    • PROJECT_ID: プロジェクト ID。
    • REGION: レジストリ リージョン。

  • エンドポイント URL を更新する: --interfaces フラグを使用して新しいエンドポイントを指定します。例:

    gcloud alpha agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

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

    • ENDPOINT_URL: 新しいエージェント エンドポイント URL（例: https://new-api.example.com/agent）。
    • PROTOCOL: エンドポイントのプロトコル バインディング。有効な値は HTTP_JSON、GRPC、JSONRPC です。

  • エージェントの仕様を更新する: --agent-spec-content フラグを使用します。たとえば、新しいエージェントカードがある場合は、次のようになります。

    gcloud alpha agent-registry services update AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --agent-spec-content=@AGENT_SPEC

    AGENT_SPEC は、新しいエージェント仕様の名前に置き換えます（例: new-agent-card.json）。

エージェントを削除する

エージェント レジストリに自動的に登録されたエージェントを削除するには、特定 Google Cloud ランタイムで基盤となるエージェントを削除する必要があります。エージェントはレジストリから自動的に削除されます。

手動で登録したエージェントをレジストリから削除するには、基盤となる Service リソースを削除する必要があります。この操作により、エージェントが検索結果から削除され、他のツールから検出できなくなります。

gcloud alpha agent-registry services delete AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION

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

  • AGENT_NAME: 削除するエージェントの名前（例: my-support-agent）。
  • PROJECT_ID: プロジェクト ID。
  • REGION: レジストリ リージョン。

次のステップ