Migrer vers l'API Agent Identity

Ce document vous explique comment migrer vos agents et fournisseurs d'authentification déployés de l'ancienne API IAM Connectors (iamconnectors.googleapis.com) vers la nouvelle API Agent Identity (agentidentity.googleapis.com).

Les deux API fonctionnent côte à côte pendant la période de migration de l'aperçu, ce qui vous permet de migrer vos charges de travail sans interrompre les conversations d'agent existantes.

Le workflow de migration comprend les tâches suivantes :

  1. Activer l'API Agent Identity
  2. Mettre à jour les stratégies d'autorisation IAM
  3. Mettre à jour le code de votre agent et les SDK
  4. Désactiver l'ancienne API

Activer l'API Agent Identity

Pour lancer la migration, activez la nouvelle API Agent Identity dans votre projet.

Activez l'API Agent Identity si ce n'est pas déjà fait.

Rôles requis pour activer les API

Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer l'API

Lorsque vous activez l'API Agent Identity, la page "Agent Registry" de la consoleGoogle Cloud bascule vers la nouvelle API pour lire et écrire des ressources :

  • Vous n'avez pas besoin de recréer vos fournisseurs d'authentification. La nouvelle API reflète chaque ancien fournisseur d'authentification (par exemple, projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME) en tant que ressource authProviders (projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME).

  • Un fournisseur d'authentification nouvellement créé à l'aide de la console Google Cloud ou de gcloud CLI apparaît en tant que ressource authProviders/ et n'est pas visible dans l'ancienne API.

  • Les agents actifs utilisant d'anciennes chaînes connectors/ continueront de fonctionner pendant la période de migration.

Mettre à jour les stratégies d'autorisation IAM

Accordez les nouveaux rôles IAM sur les ressources du fournisseur d'authentification dupliquées afin que vos agents puissent récupérer les identifiants à partir des nouveaux points de terminaison d'API.

Par exemple, si vous avez attribué le rôle Utilisateur du connecteur (roles/iamconnectors.user) à l'ID SPIFFE de votre agent sur l'ancienne ressource connectors/AUTH_PROVIDER_NAME, attribuez le rôle Utilisateur de l'identité de l'agent (roles/agentidentity.user) sur la nouvelle ressource authProviders/AUTH_PROVIDER_NAME :

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"

Si vous testez votre agent en local à l'aide de adk web, accordez roles/agentidentity.user à votre compte utilisateur personnel (user:USER_EMAIL).

Mettre à jour votre code d'agent et vos SDK

Mettez à jour le code de votre agent pour référencer la nouvelle hiérarchie de ressources et les nouveaux points de terminaison authProviders/ :

  1. Mettez à jour la version ADK dans le code de votre agent vers 2.3.0 ou une version ultérieure.

  2. Dans le code de votre agent (par exemple, agent.py), remplacez connectors/ par authProviders/ dans la chaîne de ressources GcpAuthProviderScheme.

    Ancienne configuration : 

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

    Nouvelle configuration : 

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

  3. OAuth en trois étapes uniquement : si votre agent appelle directement l'API REST, remplacez le nom d'hôte du point de terminaison de iamconnectorcredentials.googleapis.com par agentidentitycredentials.googleapis.com, et remplacez connectors/ par authProviders/ dans le chemin d'accès de la requête.

  4. OAuth en trois étapes uniquement : dans votre serveur de validation frontend (par exemple, main.py), mettez à jour l'URL du point de terminaison FinalizeCredentials sur https://agentidentitycredentials.googleapis.com/v1. Lisez également le auth_provider_name de la requête entrante et définissez-le comme champ auth_provider dans le corps de la requête FinalizeCredentials.

Désactiver l'ancienne API

Après avoir mis à jour vos stratégies d'autorisation IAM et déployé le code de votre agent, vérifiez que votre agent s'authentifie et récupère les identifiants à l'aide de la nouvelle API.

Une fois que vous avez migré tous les workflows actifs, désactivez l'ancien service dans votre projet :

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

Étapes suivantes