Vertex AI Agent Engine でエージェント ID を使用する

このページでは、Vertex AI Agent Engine Runtime でエージェントを使用する際に、Identity Access Management（IAM）エージェント ID を使用してセキュリティ機能とアクセス管理機能を提供する方法について説明します。

概要

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

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

制限事項

プロジェクトを計画する際は、次の制限事項を考慮してください。

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

  • エージェント ID はテスト環境でのみ使用することをおすすめします。

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

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

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

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

    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 Engine インスタンスを作成したら、agent_engine.update(...) を使用してエージェント コードを追加できます。

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

    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(
      agent=app,
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
          "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
          "staging_bucket": f"gs://"BUCKET _NAME",
      },
)

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

Agent Engine インスタンスは、読み取り専用のシステム証明エージェント 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: Vertex AI 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 証明書を自動的にプロビジョニングして管理します。

Vertex AI Agent Engine の 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: プロジェクトの割り当てと Vertex AI SDK を使用する権限をエージェントに付与します。

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: リージョン。Vertex AI Agent Engine のサポートされているリージョンをご覧ください。

  • AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。

  • ROLE_NAME は、付与するロールの名前です。例: roles/vision.user事前定義ロールのリストについては、ロールについてをご覧ください。

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

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

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

OAuth を使用して委任された権限でサードパーティ サービスにアクセスする

エージェント ID を使用すると、Secret Manager との統合により、エージェントがユーザーに代わってサードパーティ サービスにアクセスできるようになります。

Secret Manager との統合を設定するには、まず次の手順で、サードパーティ サービスにアクセスするための補助認証情報（クライアント ID またはクライアント シークレット）を Secret Manager（エージェントのライフサイクルが管理されているコンシューマー プロジェクト内）に保存する必要があります。

  1. Secret Manager で新しいコンテナを作成します。

  2. サードパーティ製アプリのプロバイダからクライアント ID またはクライアント シークレットを取得します。

  3. クライアント ID またはクライアント シークレットを Secret Manager に追加します。

  4. エージェント ID（プリンシパル ID）に基づいて、これらの認証情報へのアクセスを制限します。

    # Create the secret container
gcloud secrets create my-app-oauth-secret

# Add the actual client secret to Secret Manager
gcloud secrets versions add my-app-oauth-secret "gcp-client-secret-1a2b3c4d"

# Grant agent identity access to the secret
gcloud secrets add-iam-policy-binding my-app-oauth-secret \
--role='roles/secretmanager.secretAccessor' \
--member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \

シークレットが保存されると、エージェントは、プリンシパル ID と標準のGoogle Cloud 認証ライブラリをアプリケーションのデフォルト認証情報の一部として使用して、実行時にこれらの認証情報に自動的にアクセスできます。

# Example: Use agent identity to retrieve third party credentials from Secret Manager
# Use case: Using an agent, the user is trying to post a message on Slack,
# The developer first retrieves secret from Secret Manager using agent identity,
# and then uses it to login to Slack and post a message.

from google.cloud import secretmanager

def access_secret(project_id: str, secret_id: str, version_id: str = "latest") -> str:

      # Application default credential automatically gets token from MDS using agent identity
      agent_identity_credentials = default()

       # Create the Secret Manager client.
       client = secretmanager.SecretManagerServiceClient(credentials=agent_identity_credentials)

       # Build the resource name of the secret version.
       name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

       # Access the secret version.
       response = client.access_secret_version(request={"name": name})

       # Decode the payload to get the secret string.
       secret_value = response.payload.data.decode("UTF-8")
       return secret_value

クライアント ID とクライアント シークレットを使用して、ツールを構築し、OAuth ベースの認証を構成できるようになりました。

次の例では、Agent Development Kit（ADK）で開発されたエージェントを使用しています。OAuth ベースの認証は、ツール構築の一部として authenticationScheme メソッドと authCredential メソッドにラップされます。

import os

from google.adk.auth.auth_schemes import OpenIdConnectWithConfig
from google.adk.auth.auth_credential import AuthCredential, AuthCredentialTypes, OAuth2Auth
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
from google.adk.agents.llm_agent import LlmAgent

auth_scheme = OpenIdConnectWithConfig(
   authorization_endpoint="https://your-endpoint.slack.com/oauth2/v1/authorize",
   token_endpoint="https://your-token-endpoint.slack.com/oauth2/v1/token",
   scopes=['openid', 'profile', "email"]
)

auth_credential = AuthCredential(
 auth_type=AuthCredentialTypes.OPEN_ID_CONNECT,
 oauth2=OAuth2Auth(
   client_id=access_secret(project_id: 'foo', secret_id: 'slack_oauth_client_id'),
   client_secret=access_secret(project_id: 'foo', secret_id: 'slack_oauth_client_secret'),
 )
)

# --- Slack Toolset Configuration Based On OpenAPI Specification ---

with open(os.path.join(os.path.dirname(__file__), 'spec.yaml'), 'r') as f:
   spec_content = f.read()

slack_toolset = OpenAPIToolset(
  spec_str=spec_content,
  spec_str_type='yaml',

  # ** Crucially, associate the authentication scheme and credentials with these tools. **
  # This tells the ADK that the tools require the defined OIDC/OAuth2 flow.
  auth_scheme=auth_scheme,
  auth_credential=auth_credential,
)

# Configure and create the main LLM Agent.

root_agent = LlmAgent(
   model='gemini-2.0-flash',
   name='enterprise_assistant',
   instruction='Help user integrate with Slack and post messages to Slack.',
   tools=userinfo_toolset.get_tools(),
)

実行時に次の処理が行われます（ADK ウェブ経由でローカルで ADK を使用する場合、手順は ADK ウェブと ADK バックエンド内で自動化されます）。

  1. エージェントにアクセスすると、エージェントはツール（Slack など）を呼び出す必要があると判断します。

  2. ADK 内でプログラミングされたツール（auth_scheme と auth_credential を使用）は、フロントエンドに authConfig オブジェクト（リダイレクト URI とクライアント ID を含む）を返します。

  3. フロントエンドが authConfig オブジェクトを解析し、サードパーティの認証ページにリダイレクトされます。ログインすると、エージェントのフロントエンドにリダイレクトされ、認証コードが ADK バックエンドに送信されます。

  4. バックエンドは、認証コードを使用してサードパーティ サービスのアクセス トークンを取得し、ツールの実行を続行します。

ADK エージェントを Vertex AI Agent Engine Runtime にデプロイする場合は、カスタム フロントエンドを構築し、ADK-web 認証またはリダイレクト コードをフロントエンドに移行して、同じ OAuth 統合を行う必要があります。

API キーを使用してサードパーティ サービスにアクセスする

エージェント ID を使用すると、エージェントはサードパーティ サービスにアクセスし、API キーを使用してユーザーに代わって操作できます。まず、サードパーティ サービスにアクセスするための API キーを Secret Manager に保存し、Secret Manager からこれらの認証情報を取得する必要があります。

from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset

WEATHER_DOT_COM_API_KEY = access_secret(project_id: 'foo', secret_id: 'weather_dot_com_api_key')

auth_scheme, auth_credential = token_to_scheme_credential(
   "apikey", "query", "apikey", WEATHER_DOT_COM_API_KEY
)

sample_api_toolset = OpenAPIToolset(
   spec_str="...",
   spec_str_type="yaml",
   auth_scheme=auth_scheme,
   auth_credential=auth_credential,
)

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

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

  • エージェントがユーザーに代わって操作を行うと、ログにはエージェントとユーザーの両方の ID が表示されます。

  • エージェントが独自の権限で動作している場合、ログにはエージェントの ID のみが表示されます。

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

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

コンソール

  1. Google Cloud コンソールで、[Vertex AI Agent Engine] ページに移動します。

    Agent Engine に移動

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

  2. 各エージェントについて、エージェント ID は [ID] 列に表示されます。

REST API

REST API を使用して Agent Engine インスタンスを取得するときに、エージェント 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 Engine インスタンスの場合、effectiveIdentity フィールドには、Agent Engine インスタンスに関連付けられたサービス エージェントまたはサービス アカウントの名前が含まれます。

次のステップ