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

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

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

始める前に

必要なロール

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

エージェントにアクセス権を付与するには:
- プロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）
- セキュリティ管理者（roles/iam.securityAdmin）
エージェント ID に推奨されるロール:
- エージェントコンテキスト編集者（roles/aiplatform.agentContextEditor）
- エージェントのデフォルトアクセス（roles/aiplatform.agentDefaultAccess）
- Vertex AI ユーザー（roles/aiplatform.user）
- Service Usage ユーザー（roles/serviceusage.serviceUsageConsumer）
- ブラウザ（roles/browser）
- ストレージオブジェクト閲覧者（roles/storage.objectViewer）

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

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

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

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

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

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

コンソール

コンソールで、アクセス権を付与するリソースの [IAM] ページに移動します。 Google Cloud
- プロジェクトの場合は、[IAM] ページに移動します。
  [IAM] ページに移動
- 他のリソースの場合は、そのリソースのページに移動して、 [権限] タブまたは [IAM] タブをクリックします。
[**アクセス権を付与**] をクリックします。
[**新しいプリンシパル**] フィールドに、付与するアクセスレベルに一致するプリンシパル 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/*
In the [**Select a role**] field, search for and select the role that you want to grant.
[保存] をクリックします。

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: 組織 ID。 Google Cloud
PROJECT_NUMBER: あなたの Google Cloud プロジェクトの番号。
LOCATION: エージェントのロケーション（ us-central1 など）。（単一エージェントアクセスの場合にのみ必須）
ENGINE_ID: Reasoning Engine の ID。（単一エージェントアクセスの場合にのみ必須）
ROLE: 付与する IAM ロール。

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

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

次の 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）を適用します。また、このポリシーでは、mTLS を使用してエージェントゲートウェイにアクセスすることも強制されます。これにより、証明書バインドトークンは、意図した信頼できるランタイム環境（Cloud Run コンテナなど）でのみ使用できます。このセキュリティベースラインにより、盗まれた認証情報を再利用できなくなり、認証情報の盗難やアカウントの乗っ取り（ATO）を防ぐことができます。

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

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

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

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

にエージェントをデプロイするときは、エージェント ID が有効になっていることを確認してください。 Google CloudAgent 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]"],
    },
)