Ao implantar um agente no Cloud Run, você pode atribuir a ele uma identidade que permita a autenticação segura ao se comunicar com APIs e outros agentes.
Autenticar em Google Cloud APIs, 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 neste 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 Google Cloud APIs, outros agentes ou ferramentas.
Autenticar em Google Cloud APIs
Os agentes podem usar a identidade atribuída para autenticar em Google Cloud APIs como a Vertex AI, o Cloud Storage e outros Google Cloud produtos usando tokens de acesso buscados no servidor de metadados do Cloud Run.
Conceda o papel do IAM apropriado ao principal do agente, por exemplo:
Conceder 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.objectViewerem um bucket do Cloud Storage. Para mais detalhes, consulte Autenticar com o Application Default Credentials.
Substitua:
PROJECT_ID: o ID do Google Cloud projeto.AGENT_PRINCIPAL: a identidade do 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 o Application Default Credentials (ADC) para buscar tokens de acesso de curta duração no servidor de metadados.
Como alternativa, você pode 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 em outros agentes no Cloud Run
Quando um agente precisa chamar outro agente hospedado no Cloud Run
como agentes A2A, autentique usando um
token de identidade JSON Web Token (JWT) validado pela
verificação roles/run.invoker integrada do IAM do Cloud Run:
Conceda à identidade do agente de chamada o papel
roles/run.invokerno 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=REGIONSubstitua:
TARGET_SERVICE_NAME: o nome do serviço de agente de destino do Cloud Run.CALLER_AGENT_PRINCIPAL: a identidade do agente de 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 ao público-alvo 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: fornece 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 de folha na solicitação.
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")TARGET_SERVICE_URLpelo 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
Authorizationcabeçalho:curl -H "Authorization: Bearer $TOKEN" \
TARGET_SERVICE_URL/endpoint
Buscar um token de ID vinculado (mTLS)
- No contêiner do agente de chamada, leia a cadeia de certificados de 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 de carga de trabalho
durante o handshake 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 vão solicitar automaticamente tokens vinculados por padrão quando os 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 em servidores MCP no Cloud Run
Para se conectar a um servidor ou ferramenta MCP hospedada 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 só for acessado por outros agentes em execução no Cloud Run, use a verificação de invocador do IAM integrada. Permita que seus agentes se comuniquem nativamente usando políticas de invocador de execução padrão:
gcloud run services add-iam-policy-bindingMCP_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..REGION: a Google Cloud região em que o servidor MCP está implantado.
Depois de conceder o papel run.invoker, o agente de chamada poderá buscar um token de identidade
conforme descrito na seção
Opções de validação de token.
Para saber como proteger servidores MCP com o IAP para acesso programático e da CLI do SDK, 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 do agente provisionada para gerenciar a autenticação com servidores MCP e endpoints externos.
Para processar fluxos de trabalho de autorização complexos com segurança, como consentimento OAuth de três partes (3LO), OAuth de duas partes (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 conjuntos de ferramentas, consulte Autenticar em ferramentas e recursos.