Bermigrasi ke Agent Identity API

Dokumen ini menunjukkan cara memigrasikan agen dan penyedia autentikasi yang di-deploy dari IAM Connectors API lama (iamconnectors.googleapis.com) ke Agent Identity API baru (agentidentity.googleapis.com).

Kedua API beroperasi secara berdampingan selama periode migrasi pratinjau, sehingga Anda dapat memigrasikan workload tanpa mengganggu percakapan agen yang ada.

Alur kerja migrasi mencakup tugas-tugas berikut:

  1. Mengaktifkan Agent Identity API
  2. Memperbarui kebijakan izin IAM
  3. Memperbarui kode agen dan SDK
  4. Menonaktifkan API lama

Mengaktifkan Agent Identity API

Untuk memulai migrasi, aktifkan Agent Identity API baru di project Anda.

Aktifkan Agent Identity API.

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

Mengaktifkan API

Saat Anda mengaktifkan Agent Identity API, halaman Registri Agen di Google Cloud konsol akan beralih ke API baru untuk membaca dan menulis resource:

  • Anda tidak perlu membuat ulang penyedia autentikasi. API baru mencerminkan setiap penyedia autentikasi lama (misalnya, projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME) sebagai resource authProviders (projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME).

  • Penyedia autentikasi yang baru dibuat menggunakan Google Cloud konsol atau gcloud CLI akan muncul sebagai authProviders/ resource dan tidak terlihat di API lama.

  • Agen aktif yang menggunakan string connectors/ lama akan terus berfungsi selama periode migrasi.

Memperbarui kebijakan izin IAM

Berikan peran IAM baru pada resource penyedia autentikasi yang dicerminkan agar agen Anda dapat mengambil kredensial dari endpoint API baru.

Misalnya, jika Anda memberikan peran Pengguna Konektor (roles/iamconnectors.user) ke ID SPIFFE agen Anda di resource lama connectors/AUTH_PROVIDER_NAME, berikan peran Pengguna Identitas Agen (roles/agentidentity.user) di resource baru authProviders/AUTH_PROVIDER_NAME:

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"

Jika Anda menguji agen secara lokal menggunakan adk web, berikan roles/agentidentity.user ke akun pengguna pribadi Anda (user:USER_EMAIL).

Memperbarui kode agen dan SDK

Perbarui kode agen Anda untuk mereferensikan hierarki dan endpoint resource authProviders/ baru:

  1. Perbarui versi ADK di kode agen Anda ke 2.3.0 atau yang lebih tinggi.

  2. Dalam kode agen Anda (misalnya, agent.py), ganti connectors/ dengan authProviders/ dalam string resource GcpAuthProviderScheme.

    Konfigurasi lama: 

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

    Konfigurasi baru: 

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

  3. Hanya 3-legged OAuth: Jika agen Anda memanggil REST API secara langsung, perbarui nama host endpoint dari iamconnectorcredentials.googleapis.com ke agentidentitycredentials.googleapis.com, dan ganti connectors/ dengan authProviders/ di jalur permintaan.

  4. Hanya 3-legged OAuth: Di server validasi frontend Anda (misalnya, main.py), perbarui URL endpoint FinalizeCredentials ke https://agentidentitycredentials.googleapis.com/v1alpha. Selain itu, baca auth_provider_name dari permintaan masuk dan tetapkan sebagai kolom auth_provider di isi permintaan FinalizeCredentials.

Menonaktifkan API lama

Setelah memperbarui kebijakan izin IAM dan men-deploy kode agen, pastikan agen Anda mengautentikasi dan mengambil kredensial menggunakan API baru.

Setelah memigrasikan semua alur kerja aktif, nonaktifkan layanan lama di project Anda:

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

Langkah berikutnya