Migrer vers l'API Agent Identity

Ce document explique comment migrer vos agents déployés et vos fournisseurs d'authentification 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 et les SDK de votre agent
  4. Désactiver l'ancienne API

Activer l'API Agent Identity

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

Activer l'API Agent Identity

Rôles requis pour activer les API

Pour activer les API, vous avez besoin de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer l'API

Lorsque vous activez l'API Agent Identity, la page "Agent Registry" (Registre d'agents) de la Google Cloud console passe à 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 Google Cloud console ou de gcloud CLI apparaît comme une ressource authProviders/ et n'est pas visible dans l' ancienne API.

  • Les agents actifs qui utilisent d'anciennes chaînes connectors/ continuent de fonctionner pendant la fenêtre de migration.

Mettre à jour les stratégies d'autorisation IAM

Attribuez les nouveaux rôles IAM aux ressources de fournisseur d'authentification mises en miroir afin que vos agents puissent récupérer les identifiants à partir des nouveaux points de terminaison de l'API.

Par exemple, si vous avez attribué le rôle Utilisateur de connecteur (roles/iamconnectors.user) à l'ID SPIFFE de votre agent sur l'ancienne ressource connectors/AUTH_PROVIDER_NAME, attribuez le rôle Utilisateur d'identité d'agent (roles/agentidentity.user) sur la nouvelle ressource 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"

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

Mettre à jour le code et les SDK de votre agent

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 votre version ADK dans le code de votre agent vers la version 2.3.0 ou 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 iamconnectorcredentials.googleapis.com par agentidentitycredentials.googleapis.com, puis 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), remplacez l'URL du point de terminaison FinalizeCredentials par https://agentidentitycredentials.googleapis.com/v1alpha. Lisez également le auth_provider_name de la requête entrante et définissez-le comme champ auth_provider dans le FinalizeCredentials corps de la requête.

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"

Étape suivante