Esegui la migrazione all'API Agent Identity

Questo documento mostra come eseguire la migrazione degli agenti e dei provider di autenticazione di cui hai eseguito il deployment dall'API IAM Connectors legacy (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 carichi di lavoro 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 i criteri di autorizzazione di IAM
  3. Aggiorna il codice e gli SDK dell'agente
  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 hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore di Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita l'API

Quando abiliti l'API Agent Identity, la pagina Agent Registry nella Google Cloud console passa alla nuova API per leggere e scrivere le risorse:

  • Non devi 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 Google Cloud console o gcloud CLI viene visualizzato come risorsa authProviders/ e non è visibile nell' API legacy.

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

Aggiorna i criteri di autorizzazione di 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 del connettore (roles/iamconnectors.user) all'ID SPIFFE dell'agente sulla risorsa legacy connectors/AUTH_PROVIDER_NAME, concedi il ruolo Utente di Agent Identity (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 e gli SDK dell'agente

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

  1. Aggiorna la versione di ADK nel codice dell'agente a 2.3.0 o versioni 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 del 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 i criteri di autorizzazione di 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, disabilita il servizio legacy nel tuo progetto:

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

Passaggi successivi