IAM エージェント ID を使用する

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

概要

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

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

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

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

制限事項

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

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

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

エージェント ID を作成する際には、次のオプションがあります。

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

client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.agent_engines.create(
  config={"identity_type": types.IdentityType.AGENT_IDENTITY}
)
```
エージェント ID を使用して Agent Runtime インスタンスを作成したら、agent_engine.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 vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Agent Platform client with v1beta1 API for agent identity support
client = vertexai.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.agent_engines.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
    "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 を使用してエージェント ID でエージェントをデプロイする: 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
```

エージェントランタイムインスタンスは、読み取り専用のシステム証明済みエージェント 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.project-PROJECT_NUMBER.system.id.goog 形式で作成されます。
NAMESPACE: エージェントの不変リソースパス。
AGENT_NAME: 不変の agent-reasoning-engine-id。

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

エージェント ID にはデフォルトの roles/aiplatform.agentContextEditor ロールと roles/aiplatform.agentDefaultAccess ロールが付属しているため、エージェントには基本的なオペレーション権限が付与されます。

Agent Runtime Google Cloud コンソールと API を使用して、ID を表示できます。

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

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

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

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

エージェント ID に IAM 権限を付与します。次のロールをおすすめします。

roles/aiplatform.expressUser: 推論、セッション、メモリの実行に対するアクセス権を付与します。
roles/serviceusage.serviceUsageConsumer: プロジェクトの割り当てと Agent Platform SDK を使用する権限をエージェントに付与します。
roles/browser: 基本的な Google Cloud 機能へのアクセス権を付与します。

ロギング、指標、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" \

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

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 Runtime エージェントに IAM ロールを付与できます。

プロジェクト内のすべての 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.project-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/aiplatform.expressUser

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"

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

エージェントがリソースにアクセスできないようにするには、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

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

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

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

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

エージェント ID のリストは、 Google Cloud コンソールとコマンドラインを使用して、エージェントランタイムで確認できます。

コンソール

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

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

REST API

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

レスポンスには、次の形式でエージェント 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 でエージェントを使用します。