O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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

Os agentes podem acessar Google Cloud APIs e outros recursos usando a própria identidade. O Google recomenda esse método para agentes hospedados na Vertex AI 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

Verifique se você escolheu o método de autenticação correto.
Crie e implante um agente com a Identidade do Agente ativada.
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 a um agente acesso a Google Cloud serviços, peça ao administrador para conceder a você os seguintes papéis do IAM no recurso de destino:

Para conceder acesso a um agente:
- Administrador de IAM do projeto (roles/resourcemanager.projectIamAdmin)
- Administrador de segurança (roles/iam.securityAdmin)
Papéis recomendados para a identidade do agente:
- Editor de contexto do agente (roles/aiplatform.agentContextEditor)
- Acesso padrão do agente (roles/aiplatform.agentDefaultAccess)
- Usuário da Vertex AI (roles/aiplatform.user)
- Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)
- Navegador (roles/browser)
- Leitor de objetos do Storage (roles/storage.objectViewer)

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 com papéis personalizados ou outros papéis predefinidos.

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 a um agente a um recurso, use o Google Cloud console ou a CLI gcloud.

Console

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.
Clique em Conceder acesso.
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/*
No campo Selecionar um papel, pesquise e selecione o papel que você quer conceder.
Clique em Salvar.

Google Cloud CLI

Para conceder acesso a 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: o ID da sua Google Cloud organização.
PROJECT_NUMBER: o número do seu Google Cloud 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 o agente é implantado em um ambiente compatível Google Cloud .

O snippet de Python a seguir mostra como usar manualmente as credenciais da 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 tokens vinculados a certificados

Uma política de acesso baseado no contexto gerenciada pelo Google ajuda a proteger as credenciais da Identidade do Agente. Além do Gateway de Agente, 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 TLS mútuo (mTLS) para acessar o Gateway de Agente. Esse requisito ajuda a garantir que apenas o ambiente de execução confiável pretendido, como um contêiner do Cloud Run ou um pod do Google Kubernetes Engine (GKE), possa usar os tokens vinculados ao certificado. 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).

A vinculação de certificados ajuda a proteger dois tipos de credenciais de agente:

Google Cloud Tokens de acesso: tokens de acesso do OAuth 2.0 de curta duração que autenticam solicitações para Google Cloud APIs e outros recursos (*.googleapis.com).
Tokens de ID do OpenID Connect (OIDC): JSON Web Tokens (JWTs) que autenticam solicitações para serviços externos e para ferramentas e serviços hospedados em Google Cloud tempos de execução, como o Cloud Run (*.mtls.run.app) ou o GKE.

Desativar a vinculação para todos os tokens de acesso e de ID

Não é recomendável desativar a política de acesso baseado no contexto padrão e os tokens vinculados a certificados no ambiente de execução. A configuração GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false remove a proteção de vinculação de tokens para Google Cloud tokens de acesso e tokens de ID do OIDC, tornando esses tokens de curta duração vulneráveis a roubo ou ataques de repetição.

No entanto, é possível desativar no ambiente de execução nos seguintes casos raros:

Você tem requisitos específicos de compartilhamento de tokens entre agentes.
Você precisa injetar o token diretamente no cabeçalho da solicitação.
O agente não pode autenticar e retorna um 401 UNAUTHENTICATED erro.

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

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

Desativar para solicitações de token de ID individuais

Por padrão, as bibliotecas de cliente do Google Auth compatíveis vinculam criptograficamente os tokens de ID do OIDC ao certificado X.509 exclusivo do agente, incluindo a impressão digital do certificado na declaração cnf (x5t#S256) do token.

Alguns serviços, como o Cloud Run, aplicam a vinculação de certificados quando a declaração cnf está presente. Se o agente chamar esses serviços em um endpoint não mTLS, como um URL *.run.app padrão, ou se um endpoint de destino não exigir vinculação de certificado, você poderá desativar para solicitações de token de ID individuais. Essa configuração afeta apenas essa solicitação e não desativa a vinculação de certificados para Google Cloud tokens de acesso.

Python

Na biblioteca google-auth do Python (2.61.0 ou mais recente no GKE e 2.62.0 ou mais recente no Cloud Run), defina bind_id_token=False:

from google.auth.transport.requests import AuthorizedSession
from google.auth.transport.requests import Request
from google.oauth2 import id_token

target_audience = "https://TARGET_SERVICE_URL"

# Option 1: Use AuthorizedSession with IDTokenCredentials
credentials = id_token.fetch_id_token_credentials(
    audience=target_audience,
    bind_id_token=False,
)
authed_session = AuthorizedSession(credentials)
response = authed_session.get(target_audience)

# Option 2: Fetch a raw ID token directly
token = id_token.fetch_id_token(
    Request(),
    audience=target_audience,
    bind_id_token=False,
)

Substitua TARGET_SERVICE_URL pelo URI ou URL do serviço de recebimento que o agente chama.

Implantar o agente

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

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]"],
    },
)