Autentica tus agentes de IA

Vista previa — Configura funciones de Agent Platform para Cloud Run

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Cuando implementas un agente en Cloud Run, puedes asignarle una identidad que le permita autenticarse de forma segura cuando se comunica con APIs y otros agentes.

Autenticación en Google Cloud APIs, otros agentes y herramientas

Cuando tu carga de trabajo de Cloud Run se configura con el tipo de identidad agent-identity, recibe una identidad administrada por el sistema con el siguiente formato:

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

En el caso de los proyectos sin organización, el formato usa el número de proyecto:

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

Puedes usar esta identidad para autenticar de forma segura a tu agente cuando se comunica con las APIs, otros agentes o herramientas de Google Cloud .

Autenticación en las Google Cloud APIs

Los agentes pueden usar su identidad de agente asignada para autenticarse en las APIs deGoogle Cloud como Vertex AI, Cloud Storage y otrosGoogle Cloud productos con tokens de acceso recuperados del servidor de metadatos de Cloud Run.

1. Otorga el rol de IAM adecuado a la principal de tu agente, por ejemplo:

   • Otorga acceso a Vertex AI:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member="AGENT_PRINCIPAL" \
         --role="roles/aiplatform.user"

   • Otorga acceso a otras APIs de Google Cloud :

     Otorga el rol requerido en tu recurso de destino a AGENT_PRINCIPAL, por ejemplo, roles/storage.objectViewer en un bucket de Cloud Storage. Para obtener más detalles, consulta Autenticación con credenciales predeterminadas de la aplicación.

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID del proyecto de Google Cloud .
   • AGENT_PRINCIPAL: Es la identidad de tu agente, por ejemplo, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME.

2. En el código de la aplicación de tu agente, usa las bibliotecas cliente estándar de Google Cloud. Las bibliotecas cliente usan automáticamente las credenciales predeterminadas de la aplicación (ADC) para recuperar tokens de acceso de corta duración del servidor de metadatos.

   Como alternativa, puedes recuperar manualmente un token de acceso del servidor de metadatos dentro de tu contenedor:

   curl -s -H "Metadata-Flavor: Google" \
   "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"

Autentica otros agentes en Cloud Run

Cuando un agente necesita llamar a otro agente alojado en Cloud Run, como los agentes de A2A, se autentica con un token de identidad de token web JSON (JWT) validado por la verificación de IAM integrada de roles/run.invoker de Cloud Run:

1. Otorga a la identidad del agente de llamada el rol roles/run.invoker en el servicio de Cloud Run de destino:

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

   Reemplaza lo siguiente:

   • TARGET_SERVICE_NAME: Es el nombre del servicio del agente de Cloud Run de destino.
   • CALLER_AGENT_PRINCIPAL: Es la identidad del agente que realiza la llamada.
   • REGION: Es la Google Cloud región del servicio de destino.

Opciones de validación de tokens

Cloud Run admite dos métodos de validación de tokens de identidad:

• Tokens no vinculados: Son tokens de identidad estándar vinculados al público que genera el servidor de metadatos. Este es el mecanismo predeterminado para la autenticación de servicio a servicio y de agente a agente.

• Tokens vinculados: Proporcionan vinculación criptográfica entre el token y el certificado de la carga de trabajo a través de mTLS. Para usar tokens vinculados, el cliente que realiza la llamada proporciona su cadena de certificados de hoja en la solicitud.

  Puedes usar tokens vinculados a mTLS para invocar recursos de Cloud Run configurados con ingress=internal. Esto te permite restringir el acceso público a Internet a tus agentes o servidores de MCP sin necesidad de una red de VPC.

Recupera un token de ID no vinculado

1. Desde el contenedor del agente de llamada, recupera un token de identidad con la URL del servicio de destino como público:

   TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
     "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")

   Reemplaza TARGET_SERVICE_URL por la URL del servicio de Cloud Run de destino, por ejemplo, https://target-agent-1234567890.us-central1.run.app.
2. Envía solicitudes al servicio de destino con el token en el encabezado Authorization:

   curl -H "Authorization: Bearer $TOKEN" \
     TARGET_SERVICE_URL/endpoint

Recupera un token de ID vinculado (mTLS)

1. Desde el contenedor del agente de llamada, lee tu cadena de certificados de hoja y solicita un token vinculado al servidor de metadatos con una solicitud 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")

2. Llama al extremo mTLS del servicio de destino y presenta los certificados de carga de trabajo durante el protocolo de enlace 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

Ejemplo de Python

Si escribes código de agente basado en Python, las bibliotecas cliente estándar de Google Cloud solicitan automáticamente tokens vinculados de forma predeterminada cuando hay certificados presentes. Si necesitas realizar solicitudes HTTP manuales, haz lo siguiente:

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)

Reemplaza TARGET_SERVICE_MTLS_URL por la URL de mTLS del servicio de Cloud Run de destino, por ejemplo, https://target-agent-12345.us-central1.mtls.run.app.

Autentica en servidores de MCP en Cloud Run

Para conectarte a un servidor o una herramienta de MCP alojados en Cloud Run, usa el identificador --functional-type=mcp-server para habilitar el registro automático del servidor de MCP en Agent Registry.

Si solo otros agentes que se ejecutan en Cloud Run acceden a tu servidor de MCP, usa la verificación integrada del invocador de IAM. Permite que tus agentes se comuniquen de forma nativa con políticas estándar de invocador de ejecución:

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

Reemplaza lo siguiente:

• MCP_SERVICE_NAME: Es el nombre del servicio de Cloud Run de destino que aloja el servidor de MCP.
• CALLING_AGENT_PRINCIPAL: Es la identidad principal del agente que invoca el servidor de MCP. Por ejemplo, serviceAccount:[e-mail].
• REGION: Es la región Google Cloud en la que se implementa el servidor de MCP.

Después de otorgar el rol run.invoker, el agente que llama puede recuperar un token de identidad como se describe en la sección Opciones de validación de tokens.

Para obtener información sobre cómo proteger los servidores de MCP con IAP para la CLI y el acceso al SDK programático, consulta Cómo autenticar servidores de MCP.

Autenticación en nombre de los usuarios

Cuando tu agente accede a herramientas y servicios externos en nombre de un usuario, puede usar su identidad de agente aprovisionada para administrar la autenticación con servidores de MCP y extremos externos.

Para controlar de forma segura flujos de trabajo de autorización complejos, como el consentimiento de OAuth de 3 segmentos (3LO), OAuth de 2 segmentos (2LO) y claves de API, configura el Administrador de autenticación de identidad del agente.

Para obtener instrucciones sobre cómo vincular estos administradores de autenticación a tus conjuntos de herramientas, consulta Cómo autenticarse en herramientas y recursos.