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

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

アクセスモードに応じて、さまざまな認証方法を使用できます。

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

ロール

Agent Engine にデプロイするエージェントは、service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com に一致する AI Platform Reasoning Engine サービスエージェントのサービスアカウントを使用して実行されます。

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

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

コンソール

[IAM] ページに移動し、[Google 提供のロール付与を含める] チェックボックスをオンにします。

IAM に移動
Google Cloud プロジェクトに対応するプロジェクトを選択します。
service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com に一致するプリンシパルを見つけます。
デプロイされたエージェントのロールは、[ロール] 列に表示されます。

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

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

コンソール（推奨）

[IAM] ページに移動し、[Google 提供のロール付与を含める] チェックボックスをオンにします。

IAM に移動
Google Cloud プロジェクトに対応するプロジェクトを選択します。
service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com に一致するプリンシパルを見つけます。
編集ボタンをクリックして必要なロールを [プリンシパル] に追加し、保存ボタンをクリックします。

gcloud

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

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

ここで

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

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

Python

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

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

コンソール（推奨）

[IAM] ページに移動し、[Google 提供のロール付与を含める] チェックボックスをオンにします。

IAM に移動
Google Cloud プロジェクトに対応するプロジェクトを選択します。
service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com に一致するプリンシパルを見つけます。
編集ボタンをクリックして、対応するロールを削除してから、保存ボタンをクリックして、プリンシパルからロールを取り消します。

gcloud

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

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

ここで

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

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

Python

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

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 をインストールして初期化します。

Secret のバージョンを削除するには、次のコマンドを実行します。

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] > [Clients] に移動
（必要に応じて）画面に「Google Auth Platform はまだ構成されていません」と表示されている場合は、[使ってみる] をクリックして [プロジェクトの設定] に入力します。（これらは後で更新できます）。本番環境への準備の詳細については、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] > [クライアント] ページに移動します。

[Google Auth Platform] > [Clients] に移動
使用可能な OAuth クライアント認証情報が一覧表示されます。

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

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

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