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

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

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

概要

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

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

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

エージェント ID を使用してエージェントを作成する: エージェントを Agent Runtime にデプロイすると、エージェントが自動的に一意の ID を受け取るようにエージェントを作成します。
エージェント ID を使用して Google Cloud API へのアクセスを承認する: プロビジョニングされたエージェント ID を使用して、エージェントによる Google Cloud's のファーストパーティツール、API、リソースへのアクセスを許可または拒否します。これには、Agent Runtime でホストされている他のエージェントへのアクセスも含まれます。Agent2Agent（A2A）プロトコルを使用します。
エージェントアクティビティをログに記録する: サービス全体のログでエージェント ID を確認します。 Google Cloud ユーザー委任フローの場合、ログにはユーザー 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 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={
    "display_name": "identity-for-agent",
    "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
```

Agent Runtime インスタンスは、読み取り専用のシステム証明エージェント 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 ロールが付属しているため、エージェントは基本的なオペレーション権限を持ちます。

ID は、Agent Runtime Google Cloud コンソールと API で確認できます。

エージェント 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: リージョン。ランタイムでサポートされているリージョンをご覧ください。
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 のリストは、 Agent Runtime で Google Cloud コンソールとコマンドラインを使用して確認できます。

コンソール

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

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