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 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, jika belum diaktifkan.

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 Agent Registry di konsolGoogle Cloud 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 konsol Google Cloud atau gcloud CLI akan muncul sebagai resource authProviders/ 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 Connector User (roles/iamconnectors.user) ke ID SPIFFE agen Anda di resource connectors/AUTH_PROVIDER_NAME lama, berikan peran Agent Identity User (roles/agentidentity.user) di resource authProviders/AUTH_PROVIDER_NAME baru:

gcloud agent-identity auth-providers 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/ yang baru:

  1. Update 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. Khusus OAuth 3-legged: Jika agen Anda memanggil REST API secara langsung, perbarui nama host endpoint dari iamconnectorcredentials.googleapis.com menjadi agentidentitycredentials.googleapis.com, dan ganti connectors/ dengan authProviders/ di jalur permintaan.

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

Menonaktifkan API lama

Setelah memperbarui kebijakan izin IAM dan men-deploy kode agen, verifikasi bahwa agen Anda melakukan autentikasi dan mengambil kredensial menggunakan API baru.

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

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

Langkah berikutnya