Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Agent Runtime でエージェント ID を使用する

Agent Runtime でエージェント ID を使用すると、エージェントごとに安全な ID が提供され、アクセス管理に最小権限のアプローチを適用できます。このドキュメントでは、エージェント ID を持つエージェントを作成し、Google Cloud API へのアクセスを認可して、サードパーティサービスの認証情報を管理する方法について説明します。

概要

Agent Identity は、エージェントごとに ID を提供します。これにより、最小権限のアプローチが可能になり、エージェントのライフサイクルに関連付けられます。これにより、Agent Identity はサービスアカウントよりも安全なセキュリティプリンシパルになります。IAM による既存のアクセス管理コントロールは、エージェント ID をサポートし、強力なガバナンスを実現します。

エージェント ID の認証情報は、Google が管理するコンテキストアウェアアクセス（CAA）ポリシーによってデフォルトで保護されます。このポリシーは mTLS バインディングを適用して、証明書バインドトークンの形式のエージェントの認証情報が、意図した信頼できるランタイム環境（Cloud Run コンテナなど）からのみ使用できるようにします。このセキュリティベースラインにより、盗まれた認証情報は再利用できなくなり、認証情報の盗難やアカウントの乗っ取り（ATO）から保護されます。

このページでは、次のトピックについて説明します。

エージェント ID を使用してエージェントを作成する: Agent Runtime にデプロイするときに、エージェントが一意の ID を自動的に受け取るようにエージェントを作成します。
エージェント ID を使用して Google Cloud API へのアクセスを認可する: プロビジョニングされたエージェント ID を使用して、 Google Cloudのファーストパーティツール、API、リソースへのエージェントアクセスを許可または拒否します。これには、Agent2Agent（A2A）プロトコルを使用して Agent Runtime でホストされている他のエージェントへのアクセスも含まれます。
エージェントのアクティビティをログに記録する: Google Cloud サービス全体のログでエージェントの ID を表示します。ユーザー委任フローの場合、ログにはユーザー ID とエージェント ID の両方が表示されます。
エージェントとエージェント ID を一覧表示する: Agent Runtime でエージェントとその ID のリストを表示します。
コンテキストアウェアアクセスを無効にする（非推奨）: デフォルトのコンテキストアウェアアクセス（CAA）ポリシーを無効にします。

制限事項

エージェント ID には、Cloud Storage バケットに対するレガシーバケットロール（storage.legacyBucketReader、storage.legacyBucketWriter、storage.legacyBucketOwner）を付与できません。

エージェント ID を使用してエージェントを作成する

Agent Runtime インスタンスの作成時に、Agent Runtime にデプロイするエージェントに一意の ID をプロビジョニングできます。この ID は Agent Runtime のエージェントリソース ID に関連付けられており、エージェントの開発に使用したエージェントフレームワークとは独立しています。

エージェント ID を作成するときに、次のオプションを使用できます。

エージェントコードをデプロイせずに Agent Runtime インスタンスを作成する: エージェントをデプロイする前に IAM ポリシーを設定する場合は、エージェントコードをデプロイせずにエージェント ID を作成できます。これを行うには、identity_type フィールドのみを含む Agent Runtime インスタンスを作成します。
```
import agentplatform
from agentplatform import types

client = agentplatform.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.runtimes.create(
  config={
    "display_name": "identity-for-agent",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
  },
)
```
エージェント ID を使用して Agent Runtime インスタンスを作成したら、client.runtimes.update(...) を使用してエージェントコードを追加できます。

エージェントコードのデプロイ中に Agent Runtime インスタンスを作成する: エージェントコードのデプロイ中にエージェント ID をプロビジョニングする場合は、Agent Platform SDK for Python と identity_type=AGENT_IDENTITY フラグを使用します。

任意のフレームワークでエージェントを定義します。

from google.adk.agents import Agent

agent = Agent(
    model="gemini-2.5-flash",
    name="minimal_agent",
    instruction="You are a helpful assistant.",
)

次に、デプロイします。

import agentplatform
from agentplatform import types
from agentplatform.frameworks import AdkApp

# Initialize the Agent Platform client with v1beta1 API for agent identity support
client = agentplatform.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity
remote_app = client.runtimes.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-agentplatform[adk,runtimes]"],
    "staging_bucket": f"gs://"BUCKET_NAME",
  },
)

print(f"Effective Identity: {remote_app.api_resource.spec.effective_identity}")

ここで BUCKET_NAME は Cloud Storage バケット名です。

Agents CLI を使用してエージェントをデプロイする: Agents CLI は、モニタリング用の基盤となるリソースを備えた迅速なデプロイソリューションを提供するため、学習者、プロトタイピング、迅速なテストに最適です。次のコマンドでエージェントをデプロイします。
```
agents-cli deploy --agent-identity
```
ADK deploy を使用して Agent Identity でエージェントをデプロイする: ADK を使用してエージェントを設定する。adk deploy を実行する前に、エージェントのフォルダで次のコマンドを実行して、エージェント ID を含む構成ファイルを追加します。
```
# Create the file
$ touch .agent_engine_config.json

# Update the file to specify that you're using Agent Identity
$ echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json
```

Agent Runtime インスタンスは、読み取り専用のシステム証明済みエージェント ID（プリンシパル ID）を使用して作成されます。

# Agent identity Format
principal://TRUST_DOMAIN/NAMESPACE/AGENT_NAME

# Example agent identity
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID

次の部分は、エージェント ID の一部として自動プロビジョニングされます。

TRUST_DOMAIN: Agent Platform API を有効にすると、信頼ドメインがプロビジョニングされます。
- 組織がある場合、信頼ドメインは組織レベルで agents.global.org-ORGANIZATION_ID.system.id.goog の形式で作成されます。
- プロジェクトに組織がない場合、信頼ドメインはプロジェクトレベルで agents.global.proj-PROJECT_NUMBER.system.id.goog の形式で作成されます。
NAMESPACE: エージェントの不変のリソースパス。
AGENT_NAME: 変更不可の agent-reasoning-engine-id。

エージェント ID は SPIFFE に基づいています。また、安全な認証のために、同じ ID を持つエージェントで x509 証明書を自動プロビジョニングして管理します。デフォルトでは、エージェントは独自のロギング、指標、モデルアクセス、セッション、メモリ、サンドボックス（プレビュー）にアクセスできます。

エージェント ID には、エージェントが基本的な操作権限を持つように、デフォルトの roles/aiplatform.agentContextEditor ロールと roles/aiplatform.agentDefaultAccess ロールが割り当てられます。

ID を表示するには、Agent Runtime の Google Cloud コンソールと API を使用します。

エージェント ID を使用して Google Cloud API とサービスにアクセスする

エージェント ID を持つエージェントを作成したら、次の IAM ポリシーを使用して、エージェントに Google Cloud API とサービスへのアクセスを許可または拒否できます。

許可ポリシー: エージェントに Google Cloud リソースへのアクセス権を付与します。
拒否ポリシー: エージェントによる Google Cloud リソースへのアクセスを拒否します。

エージェントにアクセス権を付与する

エージェント ID に IAM 権限を付与します。

次のロールをおすすめします。

roles/serviceusage.serviceUsageConsumer: プロジェクトの割り当てと Agent Platform SDK を使用する権限をエージェントに付与します。
roles/browser: 基本的な Google Cloud 機能へのアクセス権を付与します。
roles/secretmanager.secretAccessor: エージェントに Secret Manager のシークレットへのアクセス権を付与します。シークレットを環境変数として参照する場合は、デプロイ中にシークレット値を取得できるように、Agent Platform サービスエージェント（service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com）に roles/secretmanager.secretAccessor を付与する必要があります。

ロギング、指標、Cloud API レジストリを使用する場合や、エージェントに公開するその他のリソースを使用する場合は、追加の権限が必要になることがあります。その他の例については、後ほど説明します。

IAM 許可ポリシーを作成して、エージェントに IAM ロールを付与します。

  # Example: Grant the agent access to vision API.
  gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
  --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \
  --role="ROLE_NAME" \

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

RESOURCE_TYPE: リソースのタイプ（projects、organizations など）。
RESOURCE_ID: アクセス権を付与するリソースの ID。
ORGANIZATION_ID: 組織の ID。
PROJECT_NUMBER: プロジェクトの番号。
LOCATION: リージョン。Runtime のサポート対象の地域をご覧ください。
AGENT_ENGINE_ID: Agent Runtime インスタンスのリソース ID。
ROLE_NAME は、付与するロールの名前です。例: roles/vision.user事前定義ロールのリストについては、ロールについてをご覧ください。

IAM が構成されると、Agent Platform SDK のアプリケーションのデフォルト認証情報は、エージェント ID を自動的に使用してGoogle Cloud リソースに対する認証を行います。

Agent-to-Agent（A2A）委任のアクセス権を付与する

親エージェントが Agent Registry に登録されているリモートサブエージェントを呼び出すマルチエージェントシステムを設計する場合、親エージェントの ID には、Agent Registry でサブエージェントを検出し、そのエンドポイントを呼び出す権限が必要です。

親エージェントの ID にリモートサブエージェントを検出して呼び出すために必要な権限があることを確認するには、親エージェントの ID に次の IAM ロールを付与するよう管理者に依頼してください。

親エージェントが実行時にサブエージェントのエンドポイントを検索できるようにする: 親プロジェクトまたはレジストリリソースに対する Agent Registry API 閲覧者（roles/agentregistry.viewer）
親エージェントがサブエージェントにメッセージを送信できるようにします。ターゲットサブエージェントの推論エンジンリソースに対する Agent Platform ユーザー（roles/aiplatform.user）

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

管理者は、カスタムロールや他の事前定義ロールを使用して、親エージェントの ID に必要な権限を付与することもできます。

たとえば、プロジェクトに roles/agentregistry.viewer ロールを付与するには、次の Google Cloud CLI コマンドを使用します。

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/PARENT_AGENT_ENGINE_ID" \
    --role="roles/agentregistry.viewer"

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

ORGANIZATION_ID: 組織の ID。
PROJECT_NUMBER: プロジェクトの番号。
LOCATION: 親エージェントがデプロイされているリージョン。
PARENT_AGENT_ENGINE_ID: 親エージェントの Agent Runtime インスタンスのリソース ID。

複数のエージェントにアクセス権を付与する

IAM ロールは、特定のプロジェクト内のすべての Agent Runtime エージェント、または組織全体に付与できます。

プロジェクト内のすべての Agent Runtime エージェントにロールを付与するには、次のいずれかのコマンドを使用します。

プロジェクトが組織に属している場合:

# Grant all agents in a project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

プロジェクトが組織に属していない場合:

# Grant all agents in an orgless project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.proj-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

割り当て、ロギング、モデルへのアクセスなどの一般的な権限をプロジェクト内のすべてのエージェントに付与すると、デプロイを簡素化できます。次に、データへのアクセスなど、より機密情報に関わる権限については、個々のエージェントに特定の狭い権限を付与します。このような権限は、組織またはプロジェクト内でエージェント ID 機能を初めて使用した後にいつでも付与できるため、エージェントのデプロイ前に付与できます。

たとえば、次のコマンドは、プロジェクト内のすべてのエージェントに基本ロールを付与します。

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/serviceusage.serviceUsageConsumer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/browser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/cloudapiregistry.viewer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/monitoring.metricWriter

組織内のすべての Agent Runtime エージェントにロールを付与するには:

# Grant all agents in an organization the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platform/aiplatform" \
--role="ROLE_NAME"

エージェント間（A2A）通話のアクセス権を付与する

エージェント（エージェント A）が別のエージェント（エージェント B）を呼び出す必要がある場合は、プロジェクト全体の権限を付与しないでください。代わりに、aiplatform.reasoningEngines.query と aiplatform.reasoningEngines.get のみを含むカスタムロールを付与し、エージェント B のリソースパスにバインドします。

必要な権限を持つカスタムロール agentInvoker を作成します。

gcloud iam roles create agentInvoker --project=PROJECT_ID \
  --permissions=aiplatform.reasoningEngines.query,aiplatform.reasoningEngines.get \
  --stage=GA

カスタムロールをエージェント B のリソースにバインドして、エージェント A の ID にアクセス権を付与します。

gcloud beta ai reasoning-engines add-iam-policy-binding AGENT_B_ID \
  --region=LOCATION \
  --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_A_ID" \
  --role="projects/PROJECT_ID/roles/agentInvoker"

エージェント ID が他のエージェントに対して機密性の高い管理オペレーションを実行できないようにするには、reasoningEngines.create、.delete、.update の IAM 拒否ポリシーを作成します。

deniedPrincipals:
  - principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
deniedPermissions:
  - aiplatform.googleapis.com/reasoningEngines.create
  - aiplatform.googleapis.com/reasoningEngines.delete
  - aiplatform.googleapis.com/reasoningEngines.update

エージェントへのアクセスを拒否する

エージェントのリソースへのアクセスを拒否するには、IAM 拒否ポリシーを使用するか、プリンシパルアクセス境界ポリシーを設定します。

IAM 拒否ポリシーを使用して、エージェントが特定のリソースにアクセスできないようにする。

// Deny policy (deny all agents across the org from ability to create or delete buckets)

{
"displayName": "Deny access to bucket for all agent identities in the org",
"rules": [
  {
    "denyRule": {
      "deniedPrincipals": [
        "principalSet://<org.id>.global.agent.id.goog/*"
      ],
      "deniedPermissions": [
        "iam.googleapis.com/roles.create",
        "storage.googleapis.com/buckets.delete"
      ]
    }
  }
]
}

プリンシパルアクセス境界を設定して、エージェントがアクセスできるリソースを制限します。エージェントが持つ他の権限は無視されます。

// PAB Policy (Only allow agents to operate within resource boundary)

{
    "name":"organizations/ORGANIZATION_ID/locations/global/principalAccessBoundaryPolicies/example-policy",
    "details": {
    "rules": [
      {
        "description": "Restrict agent identity inside a folder",
        "resources": [
          "//cloudresourcemanager.googleapis.com/folder/0123456789012"
        ],
        "effect": "ALLOW"
      }
    ],
  }
}

// Bind PAB policy to all identities in the organization (incl agent id)

gcloud iam principal-access-boundary-policies bindings create example-pab-binding \
      --organization=organizations/ORGANIZATION_ID \
      --policy=example-policy \ --target-principal-set=cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID

CI / CD と自動化のガイダンス

エージェントを削除して再作成する自動デプロイパイプライン（Blue/Green デプロイ、一時的なテスト環境、Terraform ワークフローなど）では、ランタイムアクセスがサイレントに失われる可能性があります。再デプロイのたびに一意の ID を持つ新しい reasoningEngines リソースが作成されるため、エージェントは新しいプリンシパル識別子を受け取ります。以前のプリンシパルに付与されていた IAM 権限は、新しいプリンシパルに継承されません。

自動パイプラインで権限を管理するには、次の方法を使用します。

新しいプリンシパル ID を動的に取得する: デプロイレスポンスから spec.effectiveIdentity 値をキャプチャするか、デプロイ後に REST API をクエリしてエージェントのアクティブな ID を取得します。デプロイ後のステップとして、この新しいプリンシパルに必要な IAM バインディングを適用します。

たとえば、次のコマンドを使用して、gcloud でアクティブな ID をクエリできます。

gcloud ai reasoning-engines describe RESOURCE_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --format="value(spec.effectiveIdentity)"

Terraform では、デプロイされた google_vertex_ai_reasoning_engine リソース ID からエージェント ID プリンシパルを動的に作成し、IAM バインディングで参照できます。

resource "google_vertex_ai_reasoning_engine" "reasoning_engine" {
  provider = google-beta

  project      = var.project_id
  region       = var.region
  display_name = var.display_name
  description  = var.agent_description

  spec {
    agent_framework = "google-adk"
    identity_type   = "AGENT_IDENTITY"

    source_code_spec {
      inline_source {
        source_archive = filebase64(data.archive_file.agent_tarball.output_path)
      }

      python_spec {
        entrypoint_module = var.agent_python_spec.entrypoint_module
        entrypoint_object = var.agent_python_spec.entrypoint_object
        requirements_file = var.agent_python_spec.requirements_path
        version           = var.agent_python_spec.version
      }
    }

    deployment_spec {
      env {
        name  = "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY"
        value = "true"
      }

      env {
        name  = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
        value = "true"
      }
    }
  }
}

locals {
  agent_resource_id        = element(split("/", google_vertex_ai_reasoning_engine.reasoning_engine.id), -1)
  agent_identity_principal = "principal://agents.global.org-${data.google_organization.org.org_id}.system.id.goog/resources/aiplatform/projects/${data.google_project.project.number}/locations/${var.region}/reasoningEngines/${local.agent_resource_id}"
}

ベースライン権限にプロジェクトスコープの principalSets を使用する: principalSet バインディングはプロジェクト内のすべてのエージェントを対象とするため、エージェントの削除と再作成後も保持されます。個々のエージェントプリンシパルではなく、プロジェクト全体の principalSet に、一般的な機密性の低いロール（サービスの使用状況、ロギング、一般的なモデル推論など）を付与します。機密性の高いデータソースへの個々の principal:// バインディングを制限します。

エージェントのアクティビティを記録する

Cloud Logging を有効にすると、 Google Cloud リソースにアクセスしたエージェントとユーザーのログを表示できます。

エージェントがユーザーに代わって操作を行うと、ログにはエージェントとユーザーの両方の ID が表示されます。
エージェントが独自の権限で動作している場合、ログにはエージェントの ID のみが表示されます。

エージェントとその ID を一覧表示する

Google Cloud コンソールとコマンドラインを使用して、Agent Runtime のエージェント ID のリストを表示できます。

コンソール

Google Cloud コンソールで、Agent Platform の [デプロイ] ページに移動します。
[デプロイメント] に移動

選択したプロジェクトの一部であるデプロイ済みのエージェントがリストに表示されます。[フィルタ] フィールドを使用して、指定した列でリストをフィルタできます。
エージェントごとに、エージェント ID が [ID] 列に表示されます。

REST API

エージェント ID は、REST API を使用して Agent Runtime インスタンスを取得するときに取得できます。

レスポンスには、次の形式のエージェント ID が含まれます。

{
  ...
  spec: {
    "effectiveIdentity": "agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID"
  }
  ...
}

エージェント ID を使用していない Agent Runtime インスタンスの場合、effectiveIdentity フィールドには、Agent Runtime インスタンスに関連付けられたサービスエージェントまたはサービスアカウントの名前が含まれます。

コンテキストアウェアアクセス（CAA）を無効にする

デフォルトでは、目的の Agent Runtime ランタイムの外部でアクセストークンを使用しようとすると、次のエラーが発生します。

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

エージェント間の特定のトークン共有要件など、特殊なケースでは、デフォルトの CAA ポリシーをオプトアウトできます。この操作は、エージェントが認証情報の窃盗に対して脆弱になるため、強く非推奨とされます。

Agent Runtime インスタンスを作成するときに、次の環境変数を設定して、デフォルトのコンテキストアウェアアクセス（CAA）ポリシーを無効にします。

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

次のステップ

ガイド

デプロイされたエージェントを管理する

Agent Platform マネージドランタイムにデプロイされたエージェントを管理する方法について説明します。

ガイド

エージェントを使用する

Agent Platform Runtime でエージェントを使用します。