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.

Autenticar seus agentes de IA

Ao implantar um agente no Cloud Run, é possível atribuir a ele uma identidade que permite a autenticação segura ao se comunicar com APIs e outros agentes.

Autenticar em APIs Google Cloud , outros agentes e ferramentas

Quando a carga de trabalho do Cloud Run é configurada com o tipo de identidade agent-identity, ela recebe uma identidade gerenciada pelo sistema no seguinte formato:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

Para projetos sem uma organização, o formato usa o número do projeto:

principal://agents.global.project-PROJECT_NUMBER.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

Você pode usar essa identidade para autenticar seu agente com segurança ao se comunicar com APIs do Google Cloud , outros agentes ou ferramentas.

Autenticar em APIs do Google Cloud

Os agentes podem usar a identidade atribuída para se autenticar nas APIs doGoogle Cloud , como Vertex AI, Cloud Storage e outros produtos doGoogle Cloud , usando tokens de acesso buscados no servidor de metadados do Cloud Run.

Conceda o papel apropriado do IAM ao principal do seu agente, por exemplo:
- Conceda acesso à Vertex AI:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="AGENT_PRINCIPAL" \
    --role="roles/aiplatform.user"
```
- Conceder acesso a outras Google Cloud APIs:
  
  Conceda o papel necessário no recurso de destino a AGENT_PRINCIPAL, por exemplo, roles/storage.objectViewer em um bucket do Cloud Storage. Para mais detalhes, consulte Autenticar com o Application Default Credentials.
Substitua:
- PROJECT_ID: o ID do projeto Google Cloud .
- AGENT_PRINCIPAL: a identidade do seu agente, por exemplo, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME.
No código do aplicativo do agente, use as bibliotecas de cliente padrão do Google Cloud. As bibliotecas de cliente usam automaticamente as Application Default Credentials (ADC) para buscar tokens de acesso de curta duração do servidor de metadados.

Como alternativa, é possível buscar manualmente um token de acesso no servidor de metadados dentro do contêiner:
```
curl -s -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"
```

Autenticar outros agentes no Cloud Run

Quando um agente precisa chamar outro agente hospedado no Cloud Run, como agentes A2A, faça a autenticação usando um token de identidade JSON Web Token (JWT) validado pela verificação roles/run.invoker do IAM integrada do Cloud Run:

Conceda à identidade do agente de chamada o papel roles/run.invoker no serviço de destino do Cloud Run:
```
gcloud run services add-iam-policy-binding TARGET_SERVICE_NAME \
    --member="CALLER_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION
```
Substitua:
- TARGET_SERVICE_NAME: o nome do serviço de destino do agente do Cloud Run.
- CALLER_AGENT_PRINCIPAL: a identidade do agente autor da chamada.
- REGION: a Google Cloud região do serviço de destino.

Opções de validação de token

O Cloud Run oferece suporte a dois métodos de validação de token de identidade:

Tokens não vinculados: tokens de identidade padrão vinculados à audiência gerados pelo servidor de metadados. Esse é o mecanismo padrão para autenticação de serviço para serviço e de agente para agente.
Tokens vinculados: fornecem vinculação criptográfica entre o token e o certificado da carga de trabalho usando mTLS. Para usar tokens vinculados, o cliente de chamada fornece a cadeia de certificados folha na solicitação.

É possível usar tokens vinculados ao mTLS para invocar recursos do Cloud Run configurados com ingress=internal. Isso permite restringir o acesso público à Internet aos seus agentes ou servidores MCP sem exigir uma rede VPC.

Buscar um token de ID não vinculado

No contêiner do agente de chamada, busque um token de identidade com o URL do serviço de destino como público-alvo:
```
TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")
```
Substitua TARGET_SERVICE_URL pelo URL do serviço de destino do Cloud Run, por exemplo, https://target-agent-1234567890.us-central1.run.app.
Envie solicitações ao serviço de destino com o token no cabeçalho Authorization:
```
curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint
```

Buscar um token de ID vinculado (mTLS)

No contêiner do agente de chamada, leia sua cadeia de certificados folha e solicite um token vinculado do servidor de metadados usando uma solicitação POST:

CERT_PATH="/var/run/secrets/workload-spiffe-credentials/certificates.pem"
JSON_PAYLOAD=$(jq -n --arg certs "$(cat $CERT_PATH)" '{"certificate_chain": $certs}')

TOKEN=$(curl -s -X POST \
    -H "Metadata-Flavor: Google" \
    -H "Content-Type: application/json" \
    -d "$JSON_PAYLOAD" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_MTLS_URL")

Chame o endpoint mTLS do serviço de destino, apresentando os certificados da carga de trabalho durante o handshake de TLS:

KEY_PATH="/var/run/secrets/workload-spiffe-credentials/private_key.pem"

curl --cert $CERT_PATH \
    --key $KEY_PATH \
    -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_MTLS_URL/endpoint

Exemplo do Python

Se você escrever um código de agente baseado em Python, as bibliotecas de cliente padrão do Google Cloud solicitarão automaticamente tokens vinculados por padrão quando certificados estiverem presentes. Se você precisar fazer solicitações HTTP manuais:

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

# Target agent's mTLS URL
target_mtls_url = "TARGET_SERVICE_MTLS_URL"

# 1. Fetch the ID token.
# google-auth automatically requests a bound ID token via POST because
# the platform configures the workload certificate environment variables.
auth_req = Request()
token = id_token.fetch_id_token(auth_req, target_mtls_url)

# 2. Make the HTTP call over mTLS, presenting the workload certificates.
cert_path = "/var/run/secrets/workload-spiffe-credentials/certificates.pem"
key_path = "/var/run/secrets/workload-spiffe-credentials/private_key.pem"

response = requests.get(
    target_mtls_url,
    headers={"Authorization": f"Bearer {token}"},
    cert=(cert_path, key_path)
)
print(response.text)

Substitua TARGET_SERVICE_MTLS_URL pelo URL mTLS do serviço de destino do Cloud Run, por exemplo, https://target-agent-12345.us-central1.mtls.run.app.

Autenticar-se em servidores MCP no Cloud Run

Para se conectar a um servidor MCP ou ferramenta hospedado no Cloud Run, use o identificador --functional-type=mcp-server para ativar o registro automático do servidor MCP no Agent Registry.

Se o servidor MCP for acessado apenas por outros agentes em execução no Cloud Run, use a verificação de invocador do IAM integrada. Permita que seus agentes se comuniquem de forma nativa usando políticas padrão de invocador de execução:

gcloud run services add-iam-policy-binding MCP_SERVICE_NAME \
    --member="CALLING_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

Substitua:

MCP_SERVICE_NAME: o nome do serviço de destino do Cloud Run que hospeda o servidor MCP.
CALLING_AGENT_PRINCIPAL: a identidade principal do agente que invoca o servidor MCP. Por exemplo, serviceAccount:my-agent@my-project.iam.iam.gserviceaccount.com.
REGION: a região Google Cloud em que o servidor MCP está implantado.

Depois de conceder a função run.invoker, o agente de chamada pode buscar um token de identidade conforme descrito na seção Opções de validação de token.

Para saber como proteger servidores MCP com a IAP para acesso programático ao SDK e à CLI, consulte Autenticar servidores MCP.

Autenticar em nome dos usuários

Quando o agente acessa ferramentas e serviços externos em nome de um usuário, ele pode usar a identidade provisionada para gerenciar a autenticação com servidores MCP e endpoints externos.

Para processar com segurança fluxos de trabalho de autorização complexos, como consentimento do OAuth de três etapas (3LO), OAuth de duas etapas (2LO) e chaves de API, configure o Gerenciador de autenticação de identidade do agente.

Para instruções sobre como vincular esses gerenciadores de autenticação aos seus conjuntos de ferramentas, consulte Autenticar ferramentas e recursos.