Migra a la API de Agent Identity

En este documento, se muestra cómo migrar tus agentes y proveedores de autenticación implementados 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 de los agentes.

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 si aún no está habilitada.

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 obtenerlo 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 consola deCloud de Confiance 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 que creas con la consola de Cloud de Confiance , la gcloud CLI o la API de REST 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 duplicados del proveedor de autenticación para que tus agentes puedan recuperar credenciales de los nuevos endpoints de API.

Por ejemplo, si otorgaste el rol de usuario de conector (roles/iamconnectors.user) al ID de SPIFFE de tu agente en el recurso connectors/AUTH_PROVIDER_NAME heredado, otorga el rol de usuario de identidad del agente (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 de tu agente

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

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

  2. En el código de tu 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 niveles: 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 niveles: 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 establécelo como el campo auth_provider en el cuerpo de la solicitud FinalizeCredentials.

Inhabilita la API heredada

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

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?