Autenticar usando a própria autoridade de um agente

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

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

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 aos 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 do agente 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 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.

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 organização Google Cloud .
  • 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 agente único.
  • ENGINE_ID: o ID do 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 Agent Gateway, a política aplica a demonstração de prova de posse (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 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, na sigla em inglês).

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 do Acesso consciente do 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. Portanto, não é recomendável desativar essa opção.

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 Agent Runtime, 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