Autenticar usando a própria autoridade de um agente

Os agentes podem acessar Google Cloud APIs e outros recursos usando a própria autoridade. Recomendamos esse método para agentes hospedados no Google Cloud para interagir com outros Google Cloud serviços.

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 essa tarefa.

Funções exigidas

Para receber as permissões necessárias para conceder acesso de um agente a Google Cloud serviços, 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 personalizados papéis ou outros predefinidos papéis.

Conceder acesso a agentes

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

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

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

Console

  1. No Google Cloud console, 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 desse recurso e clique na guia Permissões ou IAM.
  2. Clique em Conceder acesso.
  3. No campo Novos principais, 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.

Google Cloud CLI

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 Google Cloud serviço (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: seu Google Cloud ID da organização.
  • PROJECT_NUMBER: Seu Google Cloud número do projeto.
  • LOCATION: o local do agente (por exemplo, us-central1). (Necessário apenas para acesso de agente único.)
  • ENGINE_ID: o ID do seu mecanismo de raciocínio. (Necessário apenas para acesso de agente único.)
  • ROLE: o papel do IAM que você quer conceder.

Referenciar a identidade do agente no código

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

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 agentes (ADK, na sigla em inglês).

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 de acesso baseado no contexto gerenciada pelo Google ajuda a proteger as credenciais de identidade do agente. Além do gateway do agente, a política aplica a prova de posse demonstrável (DPoP, na sigla em inglês) autenticando o token de acesso do agente. A política também exige que o mTLS seja usado para acessar o gateway do agente. Isso garante que os tokens vinculados a certificados só possam ser usados no ambiente de execução confiável pretendido (por exemplo, um contêiner do Cloud Run). Essa linha de base de segurança torna as credenciais roubadas não reproduzíveis, ajudando a proteger contra roubo de credenciais e sequestro 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 ser autenticado com um erro 401 UNAUTHENTICATED, você pode desativar a política de acesso baseado no contexto padrão. A desativação remove a proteção da vinculação de tokens, tornando esses tokens de acesso de curta duração vulneráveis a roubo ou ataques de reprodução. Portanto, a desativação não é recomendada.

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

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

Implantar o agente

Ao implantar o agente no Google Cloud, verifique se a identidade do agente está ativada. Se você estiver implantando no ambiente de execução do agente, 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