Migrer vers l'API Agent Identity

Ce document 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 en parallèle pendant la période de migration de la version preview, ce qui vous permet de migrer vos charges de travail sans interrompre les conversations des agents existants.

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 vos 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 des API, vous devez disposer 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 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 consoleCloud de Confiance 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 que vous créez à l'aide de la console Cloud de Confiance , de la gcloud CLI ou de l'API REST apparaît en tant que ressource authProviders/ et n'est pas visible dans l'ancienne API.

  • Les agents actifs utilisant les anciennes chaînes connectors/ continuent 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 de l'API.

Par exemple, si vous avez attribué le rôle Utilisateur de connecteurs (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 localement à l'aide de adk web, accordez roles/agentidentity.user à votre compte utilisateur personnel (user:USER_EMAIL).

Mettre à jour le code de votre 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 de l'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, et remplacez connectors/ par authProviders/ dans le chemin de la requête.

  4. OAuth en trois étapes uniquement : dans votre serveur de validation d'interface (par exemple, main.py), remplacez l'URL du point de terminaison FinalizeCredentials par 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.

Après avoir migré tous les workflows actifs, désactivez l'ancien service dans votre projet :

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

Étapes suivantes