Migrar para a API Agent Identity

Este documento mostra como migrar seus agentes implantados e provedores de autenticação da API legada do IAM Connectors (iamconnectors.googleapis.com) para a nova API Agent Identity (agentidentity.googleapis.com).

As duas APIs operam lado a lado durante o período de migração da prévia, permitindo que você migre suas cargas de trabalho sem interromper as conversas atuais com o agente.

O fluxo de trabalho de migração inclui as seguintes tarefas:

  1. Ativar a API Identidade do Agente
  2. Atualizar políticas de permissão do IAM
  3. Atualizar o código do agente e os SDKs
  4. Desativar a API legada

Ativar a API Identidade do Agente

Para iniciar a migração, ative a nova API Identidade do Agente no seu projeto.

Ative a API Identidade do Agente, se ela ainda não estiver ativada.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

Quando você ativa a API Identidade do Agente, a página do Agent Registry no console doGoogle Cloud muda para a nova API para ler e gravar recursos:

  • Não é necessário recriar os provedores de autenticação. A nova API espelha cada provedor de autenticação legada (por exemplo, projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME) como um recurso authProviders (projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME).

  • Um provedor de autenticação recém-criado usando o console Google Cloud ou a CLI gcloud aparece como um recurso authProviders/ e não fica visível na API legada.

  • Os agentes ativos que usam strings connectors/ legadas continuam funcionando durante o período de migração.

Atualizar políticas de permissão do IAM

Conceda as novas funções do IAM nos recursos do provedor de autenticação espelhados para que seus agentes possam recuperar credenciais dos novos endpoints de API.

Por exemplo, se você concedeu o papel de Usuário do conector (roles/iamconnectors.user) ao ID SPIFFE do seu agente no recurso legado connectors/AUTH_PROVIDER_NAME, conceda o papel de Usuário da identidade do agente (roles/agentidentity.user) no novo 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"

Se você testar o agente localmente usando adk web, conceda roles/agentidentity.user à sua conta de usuário pessoal (user:USER_EMAIL).

Atualizar o código do agente e os SDKs

Atualize o código do agente para fazer referência à nova hierarquia de recursos e endpoints authProviders/:

  1. Atualize a versão do ADK no código do agente para 2.3.0 ou mais recente.

  2. No código do agente (por exemplo, agent.py), substitua connectors/ por authProviders/ na string de recurso GcpAuthProviderScheme.

    Configuração legada: 

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

    Nova configuração: 

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

  3. Somente OAuth de três vias: se o agente chamar a API REST diretamente, atualize o nome do host do endpoint de iamconnectorcredentials.googleapis.com para agentidentitycredentials.googleapis.com e substitua connectors/ por authProviders/ no caminho da solicitação.

  4. Somente OAuth de três etapas: no servidor de validação de front-end (por exemplo, main.py), atualize o URL do endpoint FinalizeCredentials para https://agentidentitycredentials.googleapis.com/v1. Além disso, leia o auth_provider_name da solicitação recebida e defina-o como o campo auth_provider no corpo da solicitação FinalizeCredentials.

Desativar a API legada

Depois de atualizar as políticas de permissão do IAM e implantar o código do agente, verifique se o agente autentica e recupera as credenciais usando a nova API.

Depois de migrar todos os fluxos de trabalho ativos, desative o serviço legado no seu projeto:

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

A seguir