Migra a la API de Agent Identity

En este documento, se muestra cómo migrar los agentes implementados y los proveedores de autenticación de la API de IAM Connectors heredada (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 del 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 del 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 las 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 información para otorgar roles.

Habilitar la API

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

  • No es necesario volver a crear los 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 Google Cloud consola o gcloud CLI aparece como un recurso authProviders/ y no es visible en la API heredada.

  • Los agentes activos que usan cadenas connectors/ heredadas siguen 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 reflejados del proveedor de autenticación para que tus agentes puedan recuperar credenciales de los nuevos extremos de la API.

Por ejemplo, si otorgaste el rol de usuario de 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 Agent Identity (roles/agentidentity.user) en el nuevo recurso 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 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 del agente

Actualiza el código del agente para hacer referencia a la nueva jerarquía de recursos y extremos 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 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 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/v1. Además, lee el auth_provider_name de la solicitud entrante y configúralo como el auth_provider campo en el FinalizeCredentials cuerpo de la solicitud.

Inhabilita la API heredada

Después de actualizar las políticas de permisos de IAM y de implementar el código del agente, verifica que el agente se autentique y recupere 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?