Esegui la migrazione all'API Agent Identity

Questo documento mostra come eseguire la migrazione degli agenti e dei provider di autenticazione di cui è stato eseguito il deployment dall'API IAM Connectors precedente (iamconnectors.googleapis.com) alla nuova API Agent Identity (agentidentity.googleapis.com).

Entrambe le API operano in parallelo durante il periodo di migrazione dell'anteprima, consentendoti di eseguire la migrazione dei workload senza interrompere le conversazioni degli agenti esistenti.

Il flusso di lavoro di migrazione include le seguenti attività:

  1. Abilita l'API Agent Identity
  2. Aggiorna le policy di autorizzazione IAM
  3. Aggiorna il codice dell'agente e gli SDK
  4. Disattiva l'API legacy

Abilita l'API Agent Identity

Per avviare la migrazione, abilita la nuova API Agent Identity nel tuo progetto.

Abilita l'API Agent Identity, se non è già abilitata.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

Quando abiliti l'API Agent Identity, la pagina Agent Registry nella consoleCloud de Confiance passa alla nuova API per leggere e scrivere risorse:

  • Non è necessario ricreare i provider di autenticazione. La nuova API rispecchia ogni provider di autenticazione legacy (ad esempio projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME) come risorsa authProviders (projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME).

  • Un provider di autenticazione creato utilizzando la console Cloud de Confiance , gcloud CLI o l'API REST viene visualizzato come risorsa authProviders/ e non è visibile nell'API legacy.

  • Gli agenti attivi che utilizzano stringhe connectors/ legacy continuano a funzionare durante la finestra di migrazione.

Aggiorna le policy di autorizzazione IAM

Concedi i nuovi ruoli IAM sulle risorse del provider di autenticazione sottoposte a mirroring in modo che i tuoi agenti possano recuperare le credenziali dai nuovi endpoint API.

Ad esempio, se hai concesso il ruolo Connector User (roles/iamconnectors.user) all'ID SPIFFE dell'agente sulla risorsa connectors/AUTH_PROVIDER_NAME legacy, concedi il ruolo Agent Identity User (roles/agentidentity.user) sulla nuova risorsa 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"

Se testi l'agente localmente utilizzando adk web, concedi roles/agentidentity.user al tuo account utente personale (user:USER_EMAIL).

Aggiorna il codice dell'agente e gli SDK

Aggiorna il codice dell'agente per fare riferimento alla nuova gerarchia delle risorse e ai nuovi endpoint di authProviders/:

  1. Aggiorna la versione di ADK nel codice dell'agente alla versione 2.3.0 o successiva.

  2. Nel codice dell'agente (ad esempio agent.py), sostituisci connectors/ con authProviders/ nella stringa della risorsa GcpAuthProviderScheme.

    Configurazione legacy: 

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

    Nuova configurazione: 

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

  3. Solo OAuth a tre vie: se l'agente chiama direttamente l'API REST, aggiorna il nome host dell'endpoint da iamconnectorcredentials.googleapis.com a agentidentitycredentials.googleapis.com e sostituisci connectors/ con authProviders/ nel percorso della richiesta.

  4. Solo OAuth a tre vie: nel server di convalida frontend (ad esempio main.py), aggiorna l'URL dell'endpoint FinalizeCredentials in https://agentidentitycredentials.googleapis.com/v1. Inoltre, leggi il auth_provider_name dalla richiesta in entrata e impostalo come campo auth_provider nel corpo della richiesta FinalizeCredentials.

Disabilita l'API legacy

Dopo aver aggiornato le policy di autorizzazione IAM e aver eseguito il deployment del codice dell'agente, verifica che l'agente si autentichi e recuperi le credenziali utilizzando la nuova API.

Dopo aver eseguito la migrazione di tutti i workflow attivi, disattiva il servizio legacy nel progetto:

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

Passaggi successivi