Cloud Run 用に Agent Platform の機能を構成する

プレビュー — Cloud Run 用の Agent Platform 機能を構成する

この機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

Gemini Enterprise Agent Platform の Agent Identity や Agent Registry などの機能は、AI エージェント、Model Context Protocol（MCP）サーバー、ツールを構築、デプロイ、管理するための組み込み機能を提供します。Cloud Run リソースでこれらの機能を有効にすると、システム管理 ID と自動登録を利用して、エージェント ワークロードの検出とセキュリティを簡素化できます。

このガイドでは、次の方法について説明します。

• 必要な IAM ロールを確立する
• 機能タイプと ID タイプについて
• サービスとジョブの機能を構成する
• 割り当てられた ID を表示する
• Agent Registry に登録されているエージェントとツールを表示する

Cloud Run は、次の Agent Platform 機能をサポートしています。

• エージェント ID: ワークロードに暗号で検証可能な一意の ID を割り当て、他のエージェント、ツール、Google Cloud APIs への安全な接続を可能にします。
• Agent Registry: エージェントとツールを自動的に登録し、組織内の他のデベロッパーやエージェントが検出できるようにします。

始める前に

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Google Cloud CLI をインストールします。

4. フェデレーション ID（連携 ID）を使用するように gcloud CLI を構成します。

   詳細については、連携 ID を使用して gcloud CLI にログインするをご覧ください。

5. gcloud CLI を初期化するには、次のコマンドを実行します。

   gcloud init

6. Cloud Run Admin API、Identity and Access Management API、Agent Registry API、App Hub API を有効にします。

   API を有効にするために必要なロール

   API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法をご覧ください。

   API を有効にする

7. プロジェクトまたは組織で Agent Registry が設定されていることを確認します。
8. gcloud CLI をインストールして初期化します。
9. コンポーネントを更新します。

   gcloud components update

10. CPU、メモリ、ネットワーク下りの料金については、Cloud Run の料金ページをご覧ください。プロビジョニングされたディスクの合計サイズと、それを使用しているインスタンスの存続期間が、費用に影響します。

必要なロール

Agent Platform の機能を構成するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

• Cloud Run リソースをデプロイして管理する: Cloud Run 管理者 （roles/run.admin）
• App Hub リソースを管理するには、次のいずれかが必要です。
  • App Hub 管理者 （roles/apphub.admin）
  • Agent Registry API 管理者 （roles/apiregistry.admin）
• 特定の ID でデプロイするには、次のいずれかが必要です。
  • IAM サービス アカウント ユーザー （roles/iam.serviceAccountUser）
  • IAM サービス アカウント管理者 （roles/iam.serviceAccountAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

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

ユースケース

次のシナリオでは、Cloud Run で Agent Platform の機能を使用します。

• ライフサイクルに関連付けられた一意のシステム管理 ID を使用して、他のエージェント、ツール、 Google Cloud API に対してエージェントを認証します。
• 組織の Agent Registry 内でエージェントと MCP サーバーの自動検出を有効にします。
• Identity-Aware Proxy を認証ポリシーとして使用して、MCP サーバーを保護します。

機能型と ID 型について

Agent Platform の機能を構成するには、Cloud Run リソースで機能プロパティと ID プロパティを設定します。

これらの 2 つのプロパティは、ワークロードの登録と識別方法を制御します。

• 機能タイプ: ワークロードの主な目的を宣言します。このプロパティは、一度設定すると変更または設定解除できません。ワークロードには、次の機能タイプのいずれかを割り当てます。
  • agent: ワークロードを AI エージェントとして指定します。このタイプのワークロードでは、agent-identity タイプを使用する必要があります。
  • mcp-server: ワークロードをユーザー管理の MCP サーバーとして指定します。このタイプでは、サポートされている任意の ID タイプを使用できます。
• ID タイプ: ワークロードに割り当てられた ID の種類を指定します。このプロパティは、一度設定すると変更または設定解除できません。ワークロードには、次のいずれかの ID タイプを割り当てます。
  • agent-identity: エージェント用に設計されたシステム管理エージェント ID を割り当てます。agent-identity を使用してデプロイすると、Agent Platform はデフォルトで ID 証明書を有効にします。オプトアウトするには、--no-identity-certificate フラグを使用してサービスを更新するか、run.googleapis.com/identity-certificate-enabled: "false" アノテーションを設定します。エージェントが独自の権限で、またはエンドユーザーに代わって行動する場合のツールとリソースに対する認証に関するガイドに沿って対応します。システム管理エージェント ID の基本コンセプトとセキュリティ上のメリットを理解するには、エージェント ID をご覧ください。
  • service-account: 標準の Google Cloud サービス アカウントを使用します。

構成の動作

機能プロパティと ID プロパティの動作は、選択した組み合わせによって異なります。

機能タイプ	ID タイプ	結果の動作
agent	agent-identity	ワークロードが Agent Registry にエージェントとして登録され、システム管理のエージェント ID が割り当てられます。
agent	その他または未指定	エラー。functional-type=agent を使用するワークロードは identity-type=agent-identity を使用する必要があります。
mcp-server	agent-identity、service-account、または未指定	ワークロードは、Agent Registry に MCP サーバー（/mcpServers）として登録されます。指定しない場合、デフォルトはサービス アカウント ID になります。
指定なし	service-account	ワークロードは、標準の Cloud Run サービスまたはジョブとして実行されます。

サービスとジョブの機能を構成する

Google Cloud CLI を使用して、Cloud Run サービスとジョブで Agent Platform の機能を構成します。

サービス

• エージェントをデプロイするには、--functional-type=agent と --identity-type=agent-identity を指定します。

  gcloud beta run deploy SERVICE_NAME \
      --image=IMAGE_URL \
      --functional-type=agent \
      --identity-type=agent-identity

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

  • SERVICE_NAME: Cloud Run サービスの名前。
  • IMAGE_URL: コンテナ イメージへの参照（us-docker.pkg.dev/cloudrun/container/hello:latest など）。Artifact Registry を使用する場合は、リポジトリ REPO_NAME がすでに作成されている必要があります。URL は LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG の形式です。

• 既存のサービスを更新してエージェント ID を使用するには:

  gcloud beta run services update SERVICE_NAME \
      --functional-type=agent \
      --identity-type=agent-identity \
      --no-traffic

  重要: 既存のサービスをサービス アカウントから agent-identity に更新すると、Cloud Run は、以前のサービス アカウントから権限を継承しない新しいプリンシパルを割り当てます。接続の中断を避けるには、Policy Analyzer を使用して必要なロールを特定し、更新前に principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME プリンシパルに事前割り当てするか、--no-traffic でサービスを更新して、トラフィックを移行する前に権限を割り当てます。

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

  • SERVICE_NAME: Cloud Run サービスの名前。
  • ORGANIZATION_ID: 組織 ID。 Google Cloud
  • PROJECT_NUMBER: Google Cloud プロジェクトの番号。
  • REGION: サービスがデプロイされているリージョン。

• ユーザー管理の MCP サーバーをデプロイするには、--functional-type=mcp-server を指定します。必要に応じて、--identity-type を使用して ID タイプを指定できます。

  gcloud beta run deploy SERVICE_NAME \
      --image=IMAGE_URL \
      --functional-type=mcp-server \
      --identity-type=IDENTITY_TYPE

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

  • SERVICE_NAME: Cloud Run サービスの名前。
  • IMAGE_URL: コンテナ イメージへの参照（us-docker.pkg.dev/cloudrun/container/hello:latest など）。Artifact Registry を使用する場合は、リポジトリ REPO_NAME がすでに作成されている必要があります。URL は LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG の形式です。
  • IDENTITY_TYPE: 省略可。ワークロードに割り当てられた ID のタイプ。agent-identity または service-account を指定します。デフォルトは service-account です。

ジョブ

注: MCP サーバーとして公開できるのは Cloud Run サービスのみです。Cloud Run ジョブは MCP サーバーとして公開できず、agent 機能タイプのみをサポートします。

• エージェント ジョブを作成するには、--functional-type=agent と --identity-type=agent-identity を指定します。

  gcloud beta run jobs create JOB_NAME \
    --image=IMAGE_URL \
    --functional-type=agent \
    --identity-type=agent-identity

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

  • JOB_NAME: Cloud Run ジョブの名前。
  • IMAGE_URL: コンテナ イメージへの参照。

割り当て済みの ID を表示する

割り当てられたエージェント ID は、 Google Cloud コンソールまたは gcloud CLI で確認できます。

サービス

コンソール

1. Google Cloud コンソールで Cloud Run に移動します。

   Cloud Run に移動

2. Cloud Run ナビゲーション メニューから [サービス] を選択し、サービスをクリックします。

3. [リビジョン] タブをクリックし、リビジョンを選択します。

4. [セキュリティ] タブをクリックします。

[Identity] フィールドに、割り当てられたエージェント ID が表示されます。

gcloud

エージェント ID を表示するには、サービスのリビジョンを説明します。

gcloud beta run revisions describe REVISION_NAME

REVISION_NAME は、サービス リビジョンの名前に置き換えます。

割り当てられたエージェント ID が出力に表示されます。

ジョブ

コンソール

1. Google Cloud コンソールで Cloud Run に移動します。

   Cloud Run に移動

2. Cloud Run ナビゲーション メニューから [ジョブ] を選択し、ジョブをクリックします。

3. [実行] タブをクリックして、実行を選択します。

4. 実行の詳細を表示します。

[Identity] フィールドに、割り当てられたエージェント ID が表示されます。

gcloud

ジョブ実行のエージェント ID を表示するには、実行の説明を取得します。

gcloud beta run jobs executions describe EXECUTION_NAME

EXECUTION_NAME は、ジョブ実行の名前に置き換えます。

割り当てられたエージェント ID が出力に表示されます。

Agent Registry でエージェントまたは MCP を表示する

--functional-type=agent または --functional-type=mcp-server を使用して Cloud Run リソースをデプロイすると、組織の Agent Registry に自動的に登録されます。

• エージェントは、エージェント カタログ（/agents）に登録されます。
• MCP サーバーは、MCP サーバー カタログ（/mcpServers）に登録されます。

レジストリに登録されているエージェントとツールを表示し、エージェントとツールを安全に保存して検出する方法については、Agent Registry をご覧ください。

次のステップ

• API とツールに対してエージェントを認証する方法について説明します。
• 安全な接続のために MCP サーバーを認証する方法を確認する。
• Cloud Run で MCP サーバーをホストする方法を学習する。
• Agent Development Kit を使用して、カスタム エージェントを構築し、レジストリに登録します。
• A2A 仕様に準拠するエージェントをビルドしてデプロイするには、A2A エージェントを Cloud Run にデプロイするをご覧ください。
• エージェントの登録または ID の割り当てで問題が発生した場合は、トラブルシューティング ガイドをご覧ください。