Autentica tus agentes de IA

Versión preliminar : Configura las 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 "tal como están" 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 las APIs y otros agentes.

Autentícate en las 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

Para los proyectos sin una 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 tu agente cuando se comunica con las Google Cloud APIs, otros agentes o herramientas.

Autentícate en las Google Cloud APIs

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

1. Otorga el rol de IAM adecuado al 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 Google Cloud APIs:

     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 Autentícate con credenciales predeterminadas de la aplicación.

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID del Google Cloud proyecto de.
   • 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 del 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 de forma manual 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"

Autentícate en otros agentes en Cloud Run

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

1. Otorga a la identidad del agente llamador 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 de agente de Cloud Run de destino.
   • CALLER_AGENT_PRINCIPAL: Es la identidad del agente llamador.
   • REGION: laregión del Google Cloud 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: Proporciona vinculación criptográfica entre el token y el certificado de la carga de trabajo mediante mTLS. Para usar tokens vinculados, el cliente llamador proporciona su cadena de certificados hoja en la solicitud.

Recupera un token de ID no vinculado

1. Desde el contenedor del agente llamador, 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 Authorization encabezado:

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

Recupera un token de ID vinculado (mTLS)

1. Desde el contenedor del agente llamador, lee tu cadena de certificados hoja y solicita un token vinculado del 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.

Autentícate en los servidores de MCP en Cloud Run

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

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

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 Google Cloud región en la que se implementa el servidor de MCP.

Después de otorgar el rol run.invoker, el agente llamador 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 el acceso a la CLI y al SDK programático, consulta Autentica servidores de MCP.

Autentícate 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 los flujos de trabajo de autorización complejos, como el consentimiento de OAuth de 3 segmentos (3LO), OAuth de 2 segmentos (2LO) y las claves de API, configura el administrador de autenticación de identidad de agente.

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