Agent Identity API に移行する

このドキュメントでは、デプロイされたエージェントと認証プロバイダを以前の IAM Connectors API（iamconnectors.googleapis.com）から新しい Agent Identity API（agentidentity.googleapis.com）に移行する方法について説明します。

プレビューの移行期間中は、両方の API が並行して動作するため、既存のエージェントの会話を中断することなくワークロードを移行できます。

移行ワークフローには次のタスクが含まれます。

  1. Agent Identity API を有効にする
  2. IAM 許可ポリシーを更新する
  3. エージェント コードと SDK を更新する
  4. 以前の API を無効にする

Agent Identity API を有効にする

移行を開始するには、プロジェクトで新しいエージェント ID API を有効にします。

Agent Identity API を有効にします。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法をご覧ください。

API の有効化

Agent Identity API を有効にすると、Google Cloud コンソールの Agent Registry ページが新しい API に切り替わり、リソースの読み取りと書き込みが行われます。

  • 認証プロバイダを再作成する必要はありません。新しい API は、各レガシー認証プロバイダ（projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME など）を authProviders リソース（projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME）としてミラーリングします。

  • Google Cloud コンソールまたは gcloud CLI を使用して新しく作成された認証プロバイダは、authProviders/ リソースとして表示され、以前の API には表示されません。

  • 移行期間中も、以前の connectors/ 文字列を使用しているアクティブなエージェントは引き続き動作します。

IAM 許可ポリシーを更新する

エージェントが新しい API エンドポイントから認証情報を取得できるように、ミラーリングされた認証プロバイダ リソースに新しい IAM ロールを付与します。

たとえば、以前の connectors/AUTH_PROVIDER_NAME リソースでエージェントの SPIFFE ID に Connector ユーザー（roles/iamconnectors.user）ロールを付与した場合は、新しい authProviders/AUTH_PROVIDER_NAME リソースで Agent Identity ユーザー（roles/agentidentity.user）ロールを付与します。

gcloud alpha agent-identity authProviders add-iam-policy-binding \
    AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

adk web を使用してエージェントをローカルでテストする場合は、個人用ユーザー アカウント（user:USER_EMAIL）に roles/agentidentity.user を付与します。

エージェント コードと SDK を更新する

新しい authProviders/ リソース階層とエンドポイントを参照するようにエージェント コードを更新します。

  1. エージェント コードの ADK バージョンを 2.3.0 以降に更新します。

  2. エージェント コード（agent.py など）で、GcpAuthProviderScheme リソース文字列の connectors/ を authProviders/ に置き換えます。

    以前の構成: 

    auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME"
)

    新しい構成:

    auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME"
)

  3. 3-legged OAuth のみ: エージェントが REST API を直接呼び出す場合は、エンドポイントのホスト名を iamconnectorcredentials.googleapis.com から agentidentitycredentials.googleapis.com に更新し、リクエスト パスで connectors/ を authProviders/ に置き換えます。

  4. 3-legged OAuth のみ: フロントエンド検証サーバー（main.py など）で、FinalizeCredentials エンドポイント URL を https://agentidentitycredentials.googleapis.com/v1alpha に更新します。また、受信リクエストから auth_provider_name を読み取り、FinalizeCredentials リクエスト本文の auth_provider フィールドとして設定します。

以前の API を無効にする

IAM 許可ポリシーを更新してエージェント コードをデプロイしたら、エージェントが新しい API を使用して認証を行い、認証情報を取得することを確認します。

すべてのアクティブなワークフローを移行したら、プロジェクトで以前のサービスを無効にします。

gcloud services disable iamconnectors.googleapis.com \
    --project="PROJECT_ID"

次のステップ