Migrar para a API Agent Identity

Neste documento, mostramos como migrar seus agentes e provedores de autenticação implantados 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 da prévia, permitindo que você migre suas cargas de trabalho sem interromper as conversas atuais do agente.

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

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

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

Ative a API Agent Identity, se 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 pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

Quando você ativa a API Agent Identity, 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 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 criado usando o console do Google Cloud , a CLI gcloud ou a API REST 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 os novos papéis do IAM em recursos de 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 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 e os SDKs do agente

Atualize o código do agente para referenciar a nova hierarquia de recursos e os endpoints de 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/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 projeto:

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

A seguir