エージェント自身の権限を使用して認証する

エージェントは、独自の権限を使用して Google Cloud API やその他のリソースにアクセスできます。この方法は、 Google Cloudでホストされているエージェントが他の Google Cloud サービスとやり取りする場合におすすめします。

エージェントが独自の権限で動作する場合、プライマリ SPIFFE ID を使用して Google Cloud アクセストークンをリクエストします。

始める前に

  1. 正しい認証方法を選択していることを確認します。
  2. エージェント ID を有効にしてエージェントを作成してデプロイします。
  3. このタスクの完了に必要なロールが付与されていることを確認します。

必要なロール

エージェントに Google Cloud サービスへのアクセス権を付与するために必要な権限を取得するには、ターゲット リソースに対する次の IAM ロールを付与するよう管理者に依頼します。

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

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

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

エージェントが Google Cloud サービスにアクセスできるようにするには、ターゲット リソースに必要なロールをエージェントの ID に付与する必要があります。

IAM 許可ポリシーでは、エージェント ID はプリンシパル IDを使用します。

エージェントにリソースへのアクセス権を付与するには、 Google Cloud コンソールまたは gcloud CLI を使用します。

コンソール

  1. Google Cloud コンソールで、アクセス権を付与するリソースの [IAM] ページに移動します。
    • プロジェクトの場合は、[IAM] ページに移動します。

      [IAM] ページに移動

    • 他のリソースの場合は、そのリソースのページに移動して、[権限] タブまたは [IAM] タブをクリックします。
  2. [アクセス権を付与] をクリックします。
  3. [新しいプリンシパル] フィールドに、付与するアクセスレベルに対応するプリンシパル ID を入力します。
    • 単一のエージェント: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • プロジェクト内のすべてのエージェント: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • 組織内のすべてのエージェント: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  4. [ロールを選択] フィールドで、付与するロールを検索して選択します。
  5. [保存] をクリックします。

Google Cloud CLI

エージェントにリソースへのアクセス権を付与するには、次のコマンドを実行します。
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

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

  • SERVICE: Google Cloud サービス（storage、bigquery など）。
  • RESOURCE_NAME: リソースの名前（バケット名やデータセット ID など）。
  • PRINCIPAL_IDENTIFIER: 付与するアクセスレベルに一致するプリンシパル ID。
    • 単一のエージェント: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • プロジェクト内のすべてのエージェント: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • 組織内のすべてのエージェント: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  • ORGANIZATION_ID: Google Cloud 組織 ID。
  • PROJECT_NUMBER: Google Cloud プロジェクトの番号。
  • LOCATION: エージェントのロケーション（例: us-central1）。（単一エージェント アクセスの場合のみ必須）。
  • ENGINE_ID: 推論エンジンの ID。（単一エージェント アクセスの場合のみ必須）。
  • ROLE: 付与する IAM ロール。

コードでエージェント ID を参照する

Google Cloud クライアント ライブラリは、エージェントがサポートされている Google Cloud 環境にデプロイされると、エージェント ID を自動的に使用します。

次の Python スニペットは、Agent Development Kit（ADK）を使用してエージェント ID 認証情報を手動で使用して Cloud Vision API を呼び出す方法を示しています。

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

省略可: コンテキストアウェア アクセスを無効にする

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

エージェント間で特定のトークン共有要件があるなど、まれに、ヘッダーにトークンを直接挿入する必要がある場合や、エージェントが 401 UNAUTHENTICATED エラーで認証できない場合は、デフォルトのコンテキストアウェア アクセス ポリシーをオプトアウトできます。オプトアウトすると、トークン バインディングの保護が解除され、これらの有効期間の短いアクセス トークンが盗難やリプレイ攻撃に対して脆弱になります。そのため、オプトアウトはおすすめしません。

オプトアウトするには、エージェントのデプロイ時に次の環境変数を設定します。

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

エージェントをデプロイする

エージェントを Google Cloudにデプロイするときは、エージェント ID が有効になっていることを確認してください。Agent Runtime にデプロイする場合は、identity_type=AGENT_IDENTITY フラグを使用します。

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI 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 (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

次のステップ