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 migrare i 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. Aggiorna 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, 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 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 i tuoi agenti possano recuperare le credenziali dai nuovi endpoint API.

Ad esempio, se hai concesso il ruolo Utente connettore (roles/iamconnectors.user) all'ID SPIFFE del tuo 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 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).

Aggiornare il codice dell'agente e gli SDK

Aggiorna il codice dell'agente in modo che faccia riferimento alla nuova gerarchia e agli endpoint delle risorse authProviders/:

  1. Aggiorna la versione di 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/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 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 tuo progetto:

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

Passaggi successivi