Fazer a autenticação no Google Cloud usando a própria identidade de um agente

Os agentes podem acessar APIs Google Cloud e outros recursos usando a própria identidade. O Google recomenda esse método para agentes hospedados em Google Cloud interagirem com outros serviços Google Cloud .

Quando um agente age por conta própria, ele usa a identidade SPIFFE principal para solicitar Google Cloud tokens de acesso.

Antes de começar

  1. Verifique se você escolheu o método de autenticação correto.
  2. Crie e implante um agente com a Identidade do Agente ativada.
  3. Verifique se você tem os papéis necessários para concluir esta tarefa.

Funções exigidas

Para receber as permissões necessárias para conceder a um agente acesso aos serviços do Google Cloud , peça ao administrador para conceder a você os seguintes papéis do IAM no recurso de destino:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Conceder acesso a agentes

Para permitir que seu agente acesse um serviço Google Cloud , conceda à identidade do agente os papéis necessários no recurso de destino.

Nas políticas de permissão do IAM, as identidades dos agentes usam identificadores principais.

Para conceder acesso de um agente a um recurso, use o console do Google Cloud ou a CLI gcloud.

Console

  1. No console Google Cloud , acesse a página IAM do recurso a que você quer conceder acesso.
    • Para um projeto, acesse a página IAM:

      Acessar a página do IAM

    • Para outros recursos, acesse a página correspondente e clique na guia Permissões ou IAM.
  2. Clique em Conceder acesso.
  3. No campo Novos participantes, insira o identificador principal que corresponde ao nível de acesso que você quer conceder:
    • Um único agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Todos os agentes em um projeto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Todos os agentes em uma organização: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  4. No campo Selecionar um papel, pesquise e selecione o papel que você quer conceder.
  5. Clique em Salvar.

CLI do Google Cloud

Para conceder acesso de um agente a um recurso, execute o seguinte comando: 
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Substitua:

  • SERVICE: o serviço Google Cloud (por exemplo, storage ou bigquery).
  • RESOURCE_NAME: o nome do recurso (por exemplo, o nome do bucket ou o ID do conjunto de dados).
  • PRINCIPAL_IDENTIFIER: o identificador principal que corresponde ao nível de acesso que você quer conceder:
    • Um único agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Todos os agentes em um projeto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Todos os agentes em uma organização: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  • ORGANIZATION_ID: o ID da sua Google Cloud organização.
  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • LOCATION: o local do seu agente (por exemplo, us-central1). Obrigatório apenas para acesso de um único agente.
  • ENGINE_ID: o ID do seu mecanismo de raciocínio. (Obrigatório apenas para acesso de um único agente.)
  • ROLE: o papel do IAM que você quer conceder.

Referenciar a identidade do agente no código

As bibliotecas de cliente Google Cloud usam automaticamente a identidade do agente quando ele é implantado em um ambiente Google Cloud compatível.

O snippet de Python a seguir mostra como usar manualmente as credenciais de identidade do agente para chamar a API Cloud Vision usando o Kit de Desenvolvimento de Agente (ADK).

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

Opcional: desativar o Acesso baseado no contexto

Uma política padrão de Acesso Baseado no Contexto gerenciada pelo Google ajuda a proteger as credenciais de identidade do agente. Além do Gateway de Agente, a política aplica a Demonstração de prova de posse (DPoP) autenticando o token de acesso do agente. A política também exige TLS mútuo (mTLS) para acessar o Gateway de Agente. Esse requisito garante que os tokens vinculados a certificados só possam ser usados no ambiente de execução confiável e pretendido (por exemplo, um contêiner do Cloud Run). Essa base de segurança torna as credenciais roubadas impossíveis de serem reproduzidas, ajudando a proteger contra roubo de credenciais e invasão de conta (ATO).

Em casos raros, como requisitos específicos de compartilhamento de tokens entre agentes, se você precisar injetar o token diretamente no cabeçalho ou se o agente não puder fazer a autenticação com um erro 401 UNAUTHENTICATED, você poderá desativar a política padrão de Acesso baseado no contexto. A desativação remove a proteção da vinculação de token, tornando esses tokens de acesso de curta duração vulneráveis a roubo ou ataques de repetição. Por isso, não recomendamos a desativação.

Para desativar, defina a seguinte variável de ambiente ao implantar o agente:

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

Implantar o agente

Ao implantar o agente no Google Cloud, verifique se a Identidade do agente está ativada. Se você estiver implantando no Agent Runtime na Gemini Enterprise Agent Platform , use a flag identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

A seguir