このページは Cloud Translation API によって翻訳されました。

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

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

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

ロール

Vertex AI Agent Engine にデプロイするエージェントは、AI Platform Reasoning Engine サービスエージェントまたはカスタムサービスアカウントを使用して実行されます。詳細については、エージェントの ID と権限を設定するをご覧ください。

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

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

サービスアカウントには、デプロイされたエージェントに必要なデフォルトの権限を付与する Vertex AI 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 は、エージェントが Vertex AI Agent Engine にデプロイされたときに使用されたサービスアカウントに基づいています。

詳細については、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 は、エージェントが Vertex AI Agent Engine にデプロイされたときに使用されたサービスアカウントに基づいています。

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

コンソール（推奨）

IAM ページに移動します。

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

gcloud

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

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

ここで

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

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

Python

Secret

シークレットには 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 > Clients] ページに移動します。

[Google Auth Platform] > [クライアント] に移動します。
（必要な場合）画面に「Google Auth Platform not configured yet」と表示されたら、[Get Started] をクリックして、[Project Configurations] に入力します。（これらは後で更新できます）。本番環境の準備の詳細については、OAuth 2.0 ポリシーの遵守をご覧ください。
[Create Client] をクリックします。
[アプリケーションの種類] を 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 > Clients] ページに移動します。

[Google Auth Platform] > [クライアント] に移動します。
所有している OAuth クライアント認証情報が一覧表示されます。

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

Google Cloud コンソールで、[Google Auth Platform > Clients] ページに移動します。

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

顧客管理の暗号鍵（CMEK）

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

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

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

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

制限事項

Vertex AI Agent Engine で CMEK を使用する場合、次の制限が適用されます。

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

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

ロール

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

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

コンソール

gcloud

Python

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

コンソール（推奨）

gcloud

Python

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

コンソール（推奨）

gcloud

Python

Secret

シークレットを作成する

コンソール

gcloud

Python

シークレットを取得する

コンソール

gcloud

Python

シークレットの一覧表示

コンソール

gcloud

Python

シークレットを更新する

コンソール

gcloud

Python

シークレットを削除する

コンソール

gcloud

Python

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

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

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

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

顧客管理の暗号鍵（CMEK）

制限事項

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

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