Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

デプロイされたエージェントのアクセスを管理する

Gemini Enterprise Agent Platform でデプロイされたエージェントのアクセスを管理するには、外部リソースにアクセスするエージェントと、エージェントにアクセスする外部クライアントの両方に対して認証と認可を構成する必要があります。このドキュメントでは、エージェント ID、サービスアカウント、API キー、OAuth クライアントなどの使用可能な認証方法について説明します。

アクセスモードごとに、さまざまな認証方法を利用できます。

認証方法	ユースケース	この認証方法について
エージェント ID（プレビュー）	エージェント内からデータソースに直接アクセスする。	エージェント ID を使用してデプロイされたエージェントは、エージェントに付与した IAM 権限に従ってリソースにアクセスできます。
サービスアカウント	エージェント内からデータソースに直接アクセスする。	デプロイされたエージェントは、サービスアカウントにアクセス権が付与されているすべてのリソースにアクセスできます。
API キー	エージェント内から API キーを使用してエンドポイントにリクエストを送信します。	この認証方法を使用する前に、使用する API が API キーをサポートしていることを確認してください。
OAuth クライアント ID	エージェントのエンドユーザーのユーザーアカウント、登録、ログイン、認証を処理します。	エージェントがユーザーに同意を求め、同意を得る必要があります。

エージェント ID

エージェント ID を使用してエージェントの ID と権限を設定した場合は、エージェントランタイムでエージェント ID を使用するで、リソースへのアクセス制御を管理する方法について確認してください。

サービスアカウント

サービスアカウントを使用してエージェントの ID と権限を設定した場合、Agent Runtime にデプロイするエージェントは、AI Platform Reasoning Engine サービスエージェントまたはカスタムサービスアカウントを使用して実行されます。

AI Platform Reasoning Engine サービスエージェント

AI Platform Reasoning Engine サービスエージェントのサービスアカウントは、service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com の形式を使用します。

サービスアカウントには、デプロイされたエージェントに必要なデフォルトの権限を付与する Gemini Enterprise Agent Platform Reasoning Engine サービスエージェント ロール（roles/aiplatform.reasoningEngineServiceAgent）があります。デフォルト権限の全一覧は IAM のドキュメントでご確認ください。

デプロイされたエージェントのロールを一覧表示する

コンソール

IAM ページに移動します。

IAM に移動
Google Cloud プロジェクトに対応するプロジェクトを選択します。
エージェント ID として使用されるサービスアカウントと一致するプリンシパルを見つけます。
デプロイされたエージェントのロールは、[ロール] 列で確認できます。

gcloud

まず、gcloud CLI をインストールして初期化します。次のコマンドを実行します。

gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:PRINCIPAL" \
  --format="value(bindings.role)"

ここで

PROJECT_ID_OR_NUMBER はプロジェクトの ID または番号です。
PRINCIPAL は、エージェントが Runtime にデプロイされたときに使用されたサービスアカウントに基づいています。

詳細については、IAM のドキュメントと CLI リファレンスをご覧ください。

Python

まず、次のコマンドを実行してクライアントライブラリをインストールします。

pip install google-api-python-client

次に、認証を行い、次のコマンドを実行して、デプロイされたエージェントのロールを一覧表示します。

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2

project_id = "PROJECT_ID"
principal = "PRINCIPAL"

crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
    resource=f"projects/{project_id}"
))
for binding in policy.bindings:
    for member in binding.members:
        if principal in member:
            print(binding.role)

ここで、PRINCIPAL は、エージェントが Runtime にデプロイされたときに使用されたサービスアカウントに基づいています。

デプロイされたエージェントにロールを付与する

コンソール（推奨）

IAM ページに移動します。

IAM に移動
Google Cloud プロジェクトに対応するプロジェクトを選択します。
エージェント ID として使用されるサービスアカウントと一致するプリンシパルを見つけます。
編集ボタンをクリックして必要なロールを プリンシパルに追加した後、保存ボタンをクリックします。

gcloud

まず、gcloud CLI をインストールして初期化します。次のコマンドを実行します。

gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

ここで

PRINCIPAL は、エージェントが Runtime にデプロイされたときに使用されたサービスアカウントに基づいています。
ROLE_NAME は、付与するロールの名前です。事前定義ロールのリストについては、ロールについてをご覧ください。

詳細については、IAM のドキュメントと CLI リファレンスをご覧ください。

Python

デプロイされたエージェントのロールを付与または取り消すために独自の Python コードを記述することはおすすめしません。代わりに、1 回限りのオペレーションには Google Cloud コンソールまたは gcloud を使用し、IAM アクセス制御をプログラムで管理するには Terraform を使用することをおすすめします。Python でこれを行う必要がある場合は、IAM クライアントライブラリのドキュメントをご覧ください。

デプロイされたエージェントからロールを取り消す

コンソール（推奨）

IAM ページに移動します。

IAM に移動
Google Cloud プロジェクトに対応するプロジェクトを選択します。
エージェント ID として使用されるサービスアカウントと一致するプリンシパルを見つけます。
編集ボタンをクリックして対応するロールを削除し、保存ボタンをクリックして、プリンシパルからロールを取り消します。

gcloud

まず、gcloud CLI をインストールして初期化します。次のコマンドを実行します。

gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

ここで

PRINCIPAL は、エージェントが Runtime にデプロイされたときに使用されたサービスアカウントに基づいています。
ROLE_NAME は、取り消すロールの名前です。事前定義ロールのリストについては、ロールについてをご覧ください。

詳細については、IAM のドキュメントと CLI リファレンスをご覧ください。

Python

API キー

API キーはシークレットを使用します。シークレットには、1 つ以上のシークレットバージョンとともに、ラベルやレプリケーション情報などのメタデータが含まれます。シークレットの実際のペイロードは、シークレットバージョンに保存されます。シークレットはプロジェクトレベルで（Secret Manager を介して）管理され、デプロイされたエージェント間で共有できます。Secret Manager でエージェントに対応するシークレットを一覧表示するには、ラベルを追加してフィルタリングに使用します。

シークレットを作成する

コンソール

[Secret Manager] ページに移動します。

Secret Manager に移動
[シークレットマネージャー] ページで、[シークレットを作成] をクリックします。
[名前] フィールドに、シークレットの名前（例: my-secret）を入力します。
省略可: 最初のシークレットの作成時にシークレットバージョンも追加するには、[シークレットの値] フィールドにシークレットの値を入力します（例: abcd1234）。
[ラベル] に移動して [ラベルを追加] をクリックします。
キーと対応する値を入力してラベルを作成します。
[シークレットの作成] をクリックします。

gcloud

まず、gcloud CLI をインストールして初期化します。次のコマンドを実行します。

gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

ここで

SECRET_ID は、シークレットの ID またはシークレットの完全修飾識別子です。
FILE_PATH は、バージョンの詳細を含むファイルへの完全パス（ファイル名を含む）です。

詳細については、シークレットとシークレットバージョンの作成に関する Secret Manager のドキュメント、またはシークレットとシークレットバージョンの作成に関する CLI リファレンスをご覧ください。

Python

まず、次のコマンドを実行してクライアントライブラリをインストールします。

pip install google-cloud-secret-manager

次に、認証を行い、次のコマンドを実行します。

from google.cloud import secretmanager
import google_crc32c

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "SECRET_ID",
    "secret": {  # google.cloud.secretmanager_v1.types.Secret
        # Required. The replication policy cannot be changed after the Secret has been created.
        "replication": {"automatic": {}},
        # Optional. Labels to associate with the secret.
        "labels": {"type": "api_key", "provider": "anthropic"},
        # Optional. The secret's time-to-live in seconds with format (e.g.,
        # "900s" for 15 minutes). If specified, the secret versions will be
        # automatically deleted upon reaching the end of the TTL period.
        "ttl": "TTL",
    },
})

anthropic_api_key = "API_KEY"  # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

version = client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),  # Optional.
    },
})
print(f"Added secret version: {version.name}")

シークレットを取得する

コンソール

[Secret Manager] ページに移動します。

Secret Manager に移動
[Secret Manager] ページで、記述するシークレットの名前をクリックします。
[シークレットの詳細] ページにシークレットに関する情報が一覧表示されます。

gcloud

まず、gcloud CLI をインストールして初期化します。次のコマンドを実行します。

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

ここで

VERSION_ID はシークレットバージョンの ID です。
SECRET_ID は、シークレットの ID またはシークレットの完全修飾された識別子です。

詳細については、Secret Manager のドキュメントまたは CLI リファレンスをご覧ください。

Python

まず、次のコマンドを実行してクライアントライブラリをインストールします。

pip install google-cloud-secret-manager

次に、認証を行い、次のコマンドを実行します。

from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})

シークレットの一覧表示

コンソール

[Secret Manager] ページに移動します。

Secret Manager に移動
[シークレット] テーブルで、[フィルタ] フィールドをクリックします。
フィルタプロパティとその対応する値（Location:asia-east1 など）を選択します。
入力された値に基づいて、テーブルが自動的にフィルタされます。
（省略可）シークレットバージョンをフィルタするには、シークレットを選択してそのバージョンにアクセスし、[バージョン] テーブルの [フィルタ] オプションを使用します。

gcloud

まず、gcloud CLI をインストールして初期化します。

プロジェクトのすべてのシークレットを一覧表示するには、次のコマンドを実行します。

gcloud secrets list --filter="FILTER"

ここで、FILTER は文字列（name:asecret OR name:bsecret など）または正規表現（name ~ "secret_ab.*" など）です。

シークレットのすべてのバージョンを一覧表示するには、次のコマンドを実行します。

gcloud secrets versions list SECRET_ID

ここで、SECRET_ID はシークレットの ID またはシークレットの完全修飾識別子です。

詳細については、シークレットのフィルタリングとシークレットバージョンのリスト表示に関する Secret Manager のドキュメント、またはシークレットとシークレットバージョンのリスト表示に関する CLI リファレンスをご覧ください。

Python

まず、次のコマンドを実行してクライアントライブラリをインストールします。

pip install google-cloud-secret-manager

次に、認証を行い、次のコマンドを実行します。

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
    "parent": "projects/PROJECT_ID",
    "filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
    print(f"Found secret: {secret.name}")

シークレットを更新する

コンソール

[Secret Manager] ページに移動します。

Secret Manager に移動
[Secret Manager] ページで、シークレットの名前の横にあるチェックボックスをオンにします。
[情報パネル] が閉じている場合は、[情報パネルを表示] をクリックして表示します。
情報パネルで、[ラベル] タブを選択します。
[ラベルを追加] をクリックし、ラベルのキーと値を入力します。
[保存] をクリックします。

gcloud

まず、gcloud CLI をインストールして初期化します。次のコマンドを実行します。

gcloud secrets update SECRET_ID --update-labels=KEY=VALUE

ここで

SECRET_ID は、シークレットの ID またはシークレットの完全修飾識別子です。
KEY はラベルキーです。
VALUE は、ラベルの対応する値です。

詳細については、Secret Manager のドキュメントまたは CLI リファレンスをご覧ください。

Python

まず、次のコマンドを実行してクライアントライブラリをインストールします。

pip install google-cloud-secret-manager

次に、認証を行い、次のコマンドを実行します。

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
    "secret": {
        "name": name,
        "labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
    },
    "update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")

シークレットを削除する

コンソール

[Secret Manager] ページに移動します。

Secret Manager に移動
[Secret Manager] ページのシークレットの [アクション] 列で、[もっと見る] をクリックします。
表示されるメニューで [削除] をクリックします。
[シークレットの削除] ダイアログで、シークレットの名前を入力します。
[シークレットを削除] ボタンをクリックします。

gcloud

まず、gcloud CLI をインストールして初期化します。

シークレットバージョンを削除するには、次のコマンドを実行します。

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

ここで

VERSION_ID はシークレットバージョンのリソース名です。
SECRET_ID は、シークレットの ID またはシークレットの完全修飾された識別子です。

シークレットとそのすべてのバージョンを削除するには、次のコマンドを実行します。

gcloud secrets delete SECRET_ID

ここで、SECRET_ID はシークレットの ID またはシークレットの完全修飾識別子です。

詳細については、Secret Manager のドキュメントのシークレットの削除とシークレットバージョンの破棄、または CLI リファレンスのシークレットの削除とシークレットバージョンの破棄をご覧ください。

Python

まず、次のコマンドを実行してクライアントライブラリをインストールします。

pip install google-cloud-secret-manager

次に、認証を行い、次のコマンドを実行します。

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})

OAuth クライアントと認証情報

クライアント ID は、Google の OAuth サーバーで個々のエージェントを識別するために使用します。エージェントが複数のプラットフォームで実行される場合、各プラットフォームに独自のクライアント ID が必要です。OAuth ベースのエージェントを統合するには、次の操作を行います。

OAuth クライアントと認証情報を作成します。
クライアント ID とシークレットを Secret Manager に保存します（シークレットを作成するをご覧ください）。
開発中にエージェントのシークレットにアクセスします。

OAuth クライアント認証情報を作成する

Google Cloud コンソールで、[Google Auth Platform] > [クライアント] ページに移動します。

[Google Auth Platform] > [クライアント] に移動します。
（必要に応じて）画面に「Google Auth Platform not configured yet」と表示された場合は、[Get Started] をクリックして [Project Configurations] に入力します（後で更新できます）。本番環境の準備について詳しくは、OAuth 2.0 ポリシーの遵守をご覧ください。
[クライアントを作成] をクリックします。
[アプリケーションの種類] を Web application に設定します。
OAuth クライアントの名前を OAUTH_CLIENT_DISPLAY_NAME に設定します。
[承認済みのリダイレクト URI] に、REDIRECT_URI の URI を追加します。
[クライアントシークレット] で、[JSON をダウンロード] ボタンをクリックします。次の内容を含む client_secret.json ファイルがダウンロードされます。

{'web': {
    'client_id': "CLIENT_ID",
    'client_secret': "CLIENT_SECRET",
    'project_id': "PROJECT_ID",
    'redirect_uris': [REDIRECT_URIs],
    'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
    'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
    'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
    'javascript_origins': "JAVASCRIPT_ORIGINS",  # Optional.
}}

クライアント ID とシークレットを Secret Manager に保存します。

from google.cloud import secretmanager
import google_crc32c
import json

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
    "secret": {
        "labels": {"type": "oauth_client"},
        "replication": {"automatic": {}},
    },
})

payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),
    },
})

OAuth クライアントのリストを取得する

Google Cloud コンソールで、[Google Auth Platform > クライアント] ページに移動します。このページには、OAuth クライアント認証情報が一覧表示されます。

[Google Auth Platform] > [クライアント] に移動します。

OAuth クライアントを削除する

Google Cloud コンソールで、[Google Auth Platform] > [クライアント] ページに移動します。

[Google Auth Platform] > [クライアント] に移動します。
削除する OAuth クライアント認証情報を選択し、[削除] をクリックします。

顧客管理の暗号鍵（CMEK）

デフォルトでは、 Google Cloud は、Google が管理する暗号鍵を使用して、保存されているデータを自動的に暗号化します。データを保護する鍵について特定のコンプライアンス要件や規制要件がある場合は、デプロイされたエージェントに顧客管理の暗号鍵（CMEK）を使用できます。

Gemini Enterprise Agent Platform で CMEK を使用するための一般的な要件とガイダンスについては、Gemini Enterprise Agent Platform 用の CMEK のドキュメントをご覧ください。

プロジェクトの設定（課金と有効な API）
キーリングと鍵の作成
必要な権限付与

エージェントで CMEK を有効にするには、Agent Platform インスタンスの作成時に Cloud KMS 鍵を使用して encryption_spec を指定する必要があります。コードサンプルについては、顧客管理の暗号鍵を構成するをご覧ください。

制限事項

Agent Runtime で CMEK を使用する場合は、次の制限事項が適用されます。

マルチリージョン鍵は使用できません: シングルリージョン鍵のみがサポートされています。キーリングと鍵のリージョンは、Agent Platform インスタンスと同じである必要があります。
CMEK インスタンスの暗号鍵を更新できない: CMEK 鍵を使用してエージェントをデプロイすると、そのデプロイの暗号鍵を変更することはできません。新しい鍵を使用するには、新しい Agent Platform インスタンスをデプロイする必要があります。
鍵で暗号化されない特定のメタデータと運用データ: CMEK は、エージェントのコアデータを保存時に暗号化します。ただし、特定のメタデータとランタイム運用データは、ユーザーの鍵で暗号化されません。代わりに、Google のデフォルトの暗号化を使用して暗号化されます。以下が該当します。
- エージェントのメタデータ:
  - 表示名
  - 説明
- ランタイムオペレーションデータ:
  - サービスアカウントのメールアドレス
  - エージェントオブジェクトクラスメソッド名
  - 環境変数

VPC Service Controls（VPC-SC）

Agent Runtime は、データセキュリティを強化し、データの引き出しのリスクを軽減するために、VPC Service Controls をサポートしています。

VPC Service Controls が構成されている場合、デプロイされたエージェントは、BigQuery API、Cloud SQL Admin API、Agent Platform API などの Google API とサービスへの安全なアクセスを維持し、定義された境界内でのシームレスなオペレーションを確認します。VPC Service Controls は、すべての公共のインターネットアクセスを効果的にブロックし、データ移動を承認済みネットワーク境界内に制限することで、企業のセキュリティポスチャーを大幅に強化します。

使用可能なデプロイオプションについては、エージェントをデプロイするをご覧ください。デプロイオプションに応じて、次の上り（内向き）ルールを構成する必要があります。

pickle ベースのデプロイの場合、storage.googleapis.com サービスと artifactregistry.googleapis.com サービスへの上り（内向き）が必要です。
ソースベースのデプロイ、git ベースのデプロイ、独自の Dockerfile（BYOD）デプロイでは、artifactregistry.googleapis.com サービスへの上り（内向き）が必要です。
独自のコンテナ（BYOC）デプロイの場合、追加の上り（内向き）ルールは必要ありません。

制限事項

Agent Gateway では VPC Service Controls はサポートされていません。

ただし、カスタム組織ポリシーの制約を使用して、エージェントに関連付けることができるゲートウェイを制限できます。詳細については、エージェントゲートウェイを介してトラフィックを転送するをご覧ください。

デプロイされたエージェントのアクセスを管理する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

エージェント ID

サービス アカウント

AI Platform Reasoning Engine サービス エージェント

デプロイされたエージェントのロールを一覧表示する

コンソール

gcloud

Python

デプロイされたエージェントにロールを付与する

コンソール（推奨）

gcloud

Python

デプロイされたエージェントからロールを取り消す

コンソール（推奨）

gcloud

Python

API キー

シークレットを作成する

コンソール

gcloud

Python

シークレットを取得する

コンソール

gcloud

Python

シークレットの一覧表示

コンソール

gcloud

Python

シークレットを更新する

コンソール

gcloud

Python

シークレットを削除する

コンソール

gcloud

Python

OAuth クライアントと認証情報

OAuth クライアント認証情報を作成する

OAuth クライアントのリストを取得する

OAuth クライアントを削除する

顧客管理の暗号鍵（CMEK）

制限事項

VPC Service Controls（VPC-SC）

制限事項

デプロイされたエージェントのアクセスを管理する

サービスアカウント

AI Platform Reasoning Engine サービスエージェント