Migrar para a API Agent Identity

Este documento mostra como migrar seus agentes implantados e provedores de autenticação da API IAM Connectors legada (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 de visualização, permitindo que você migre suas cargas de trabalho sem interromper as conversas de agentes atuais.

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

  1. Ativar a API Agent Identity
  2. Atualizar as 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 Agent Identity

Para iniciar a migração, ative a nova API Agent Identity no seu projeto.

Ativar a API Agent Identity.

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pela função de proprietário (roles/owner). Caso contrário, você pode receber essa permissão pela função Administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder funções.

Ativar a API

Quando você ativa a API Agent Identity, a página do registro de agentes no Google Cloud console 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 legado (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 Google Cloud console 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 a janela de migração.

Atualizar as políticas de permissão do IAM

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

Por exemplo, se você concedeu a função Usuário do conector (roles/iamconnectors.user) ao ID SPIFFE do seu agente no recurso legado connectors/AUTH_PROVIDER_NAME, conceda a função Usuário de identidade do agente (roles/agentidentity.user) no novo recurso 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 você testar seu 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 referenciar a 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 etapas: 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/v1alpha. Além disso, leia o auth_provider_name da solicitação recebida e defina-o como o auth_provider campo no FinalizeCredentials corpo da solicitação.

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 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