Migra a la API de Agent Identity

En este documento, se muestra cómo migrar los agentes y proveedores de autenticación implementados desde la API heredada de IAM Connectors (iamconnectors.googleapis.com) a la nueva API de Agent Identity (agentidentity.googleapis.com).

Ambas APIs operan en paralelo durante el período de migración de la versión preliminar, lo que te permite migrar tus cargas de trabajo sin interrumpir las conversaciones existentes con el agente.

El flujo de trabajo de migración incluye las siguientes tareas:

  1. Habilita la API de Agent Identity
  2. Actualiza las políticas de permisos de IAM
  3. Actualiza el código y los SDKs de tu agente
  4. Inhabilita la API heredada

Habilita la API de Agent Identity

Para iniciar la migración, habilita la nueva API de Agent Identity en tu proyecto.

Habilita la API de Agent Identity.

Roles necesarios para habilitar las APIs

Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar la API

Cuando habilitas la API de Agent Identity, la página de Agent Registry en la consola deGoogle Cloud cambia a la nueva API para leer y escribir recursos:

  • No es necesario que vuelvas a crear tus proveedores de autenticación. La nueva API refleja cada proveedor de autenticación heredado (por ejemplo, projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME) como un recurso authProviders (projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME).

  • Un proveedor de autenticación recién creado con la consola de Google Cloud o la gcloud CLI aparece como un recurso deauthProviders/y no se ve en la API heredada.

  • Los agentes activos que usan cadenas connectors/ heredadas seguirán funcionando durante el período de migración.

Actualiza las políticas de permisos de IAM

Otorga los nuevos roles de IAM en los recursos del proveedor de autenticación duplicados para que tus agentes puedan recuperar credenciales de los nuevos extremos de API.

Por ejemplo, si otorgaste el rol de Usuario del conector (roles/iamconnectors.user) al ID de SPIFFE de tu agente en el recurso heredado connectors/AUTH_PROVIDER_NAME, otorga el rol de Usuario de identidad del agente (roles/agentidentity.user) en el nuevo recurso 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 pruebas tu agente de forma local con adk web, otorga roles/agentidentity.user a tu cuenta de usuario personal (user:USER_EMAIL).

Actualiza el código y los SDKs de tu agente

Actualiza el código de tu agente para que haga referencia a la nueva jerarquía de recursos y los nuevos extremos de authProviders/:

  1. Actualiza la versión del ADK en el código del agente a 2.3.0 o una versión posterior.

  2. En el código del agente (por ejemplo, agent.py), reemplaza connectors/ por authProviders/ en la cadena de recursos GcpAuthProviderScheme.

    Configuración heredada: 

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

    Nueva configuración: 

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

  3. Solo para OAuth de 3 segmentos: Si tu agente llama directamente a la API de REST, actualiza el nombre de host del extremo de iamconnectorcredentials.googleapis.com a agentidentitycredentials.googleapis.com y reemplaza connectors/ por authProviders/ en la ruta de acceso de la solicitud.

  4. Solo para OAuth de 3 segmentos: En tu servidor de validación de frontend (por ejemplo, main.py), actualiza la URL del extremo FinalizeCredentials a https://agentidentitycredentials.googleapis.com/v1alpha. Además, lee el auth_provider_name de la solicitud entrante y configúralo como el campo auth_provider en el cuerpo de la solicitud FinalizeCredentials.

Inhabilita la API heredada

Después de actualizar tus políticas de IAM de permisos y de implementar el código del agente, verifica que el agente se autentique y recupere las credenciales con la nueva API.

Después de migrar todos los flujos de trabajo activos, inhabilita el servicio heredado en tu proyecto:

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

¿Qué sigue?