Esegui la migrazione all'API Agent Identity

Questo documento mostra come eseguire la migrazione degli agenti e dei fornitori 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 funzionano in parallelo durante il periodo di migrazione dell'anteprima, consentendoti di eseguire la migrazione dei tuoi workload senza interrompere le conversazioni esistenti con gli agenti.

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

  1. Abilita l'API Agent Identity
  2. Aggiornare le policy di autorizzazione IAM
  3. Aggiornare il codice dell'agente e gli SDK
  4. Disabilita 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.

Ruoli richiesti per abilitare le API

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

Abilitare l'API

Quando abiliti l'API Agent Identity, la pagina Agent Registry nella consoleGoogle Cloud 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 appena creato utilizzando la console Google Cloud o gcloud CLI 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 gli agenti possano recuperare le credenziali dai nuovi endpoint API.

Ad esempio, se hai concesso il ruolo Utente connettore (roles/iamconnectors.user) all'ID SPIFFE dell'agente nella risorsa connectors/AUTH_PROVIDER_NAME precedente, concedi il ruolo Utente identità agente (roles/agentidentity.user) nella nuova risorsa 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"

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 in modo che faccia riferimento alla nuova gerarchia e ai nuovi endpoint della risorsa authProviders/:

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

  2. Nel codice dell'agente (ad esempio agent.py), sostituisci connectors/ con authProviders/ nella stringa di risorse 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 a https://agentidentitycredentials.googleapis.com/v1alpha. Inoltre, leggi il auth_provider_name dalla richiesta in arrivo 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 esegua l'autenticazione e recuperi le credenziali utilizzando la nuova API.

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

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

Passaggi successivi