Configura las funciones de Agent Platform para Cloud Run

Las funciones de Gemini Enterprise Agent Platform, como Agent Identity y Agent Registry, proporcionan capacidades integradas para compilar, implementar y administrar agentes de IA, servidores del Protocolo de contexto del modelo (MCP) y herramientas. Si habilitas estas funciones para tus recursos de Cloud Run, puedes aprovechar las identidades administradas por el sistema y el registro automático para simplificar el descubrimiento y la seguridad de tus cargas de trabajo de agentes.

En esta guía, se explica lo siguiente:

Cloud Run admite las siguientes funciones de Agent Platform:

  • Agent Identity: Asigna una identidad única y criptográficamente verificable a tu carga de trabajo, lo que permite conexiones seguras a otros agentes, herramientas y APIs de Google Cloud.
  • Agent Registry: registra automáticamente tus agentes y herramientas para que puedan ser descubiertos por otros desarrolladores y agentes de tu organización.

Antes de comenzar

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Instala Google Cloud CLI.

  4. Configura gcloud CLI para usar tu identidad federada.

    Para obtener más información, consulta Accede a la gcloud CLI con tu identidad federada.

  5. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

  6. Habilita las APIs de Cloud Run Admin, Identity and Access Management, Agent Registry y App Hub.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol Propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol Administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

    Habilitar las API

  7. Asegúrate de haber configurado Agent Registry en tu proyecto u organización.
  8. Instala e inicializa gcloud CLI.
  9. Actualiza los componentes, como se indica a continuación: 
    gcloud components update
  10. Revisa la página de precios de Cloud Run para obtener información sobre la CPU, la memoria y la salida de red. El tamaño total del disco aprovisionado y la vida útil de la instancia que lo usa contribuyen a tu costo.

Roles obligatorios

Para obtener los permisos que necesitas para configurar las funciones de Agent Platform, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Casos de uso

Usa las funciones de Agent Platform con Cloud Run en las siguientes situaciones:

  • Autentica tu agente en otros agentes, herramientas y Google Cloud APIs con una identidad única administrada por el sistema vinculada a su ciclo de vida.
  • Habilita el descubrimiento automático de agentes y servidores de MCP en el Agent Registry de tu organización.
  • Usa Identity-Aware Proxy como una política de autenticación para proteger los servidores de MCP.

Comprende los tipos funcionales y de identidad

Para configurar las funciones de Agent Platform, debes establecer propiedades funcionales y de identidad en tus recursos de Cloud Run.

Estas dos propiedades controlan cómo registrar e identificar una carga de trabajo:

  • Tipo funcional: Declara el propósito principal de la carga de trabajo. Una vez establecida, esta propiedad no se puede cambiar ni anular. Asigna a tu carga de trabajo uno de los siguientes tipos funcionales:
    • agent: Designa la carga de trabajo como un agente de IA. Las cargas de trabajo de este tipo deben usar el tipo agent-identity.
    • mcp-server: Designa la carga de trabajo como un servidor de MCP administrado por el usuario. Este tipo puede usar cualquier tipo de identidad compatible.
  • Tipo de identidad: Especifica el tipo de identidad asignado a la carga de trabajo. Una vez establecida, esta propiedad no se puede cambiar ni anular. Asigna a tu carga de trabajo uno de los siguientes tipos de identidad:
    • agent-identity: Asigna una identidad de agente administrada por el sistema diseñada para agentes. Cuando implementas con agent-identity, Agent Platform habilita los certificados de identidad de forma predeterminada. Para inhabilitar esta opción, actualiza tu servicio con la --no-identity-certificate marca o establece la run.googleapis.com/identity-certificate-enabled: "false" anotación. Sigue la guía para autenticar herramientas y recursos para agentes que actúan por su propia autoridad o en nombre de los usuarios finales. Para comprender los conceptos básicos y los beneficios de seguridad de las identidades de agentes administradas por el sistema, obtén más información sobre Agent Identity.
    • service-account: Usa una cuenta de servicio estándar de Google Cloud.

Comportamiento de la configuración

El comportamiento de las propiedades funcionales y de identidad depende de la combinación que elijas:

Tipo funcional Tipo de identidad Comportamiento resultante
agent agent-identity La carga de trabajo se registra como un agente en Agent Registry y se le asigna una identidad de agente administrada por el sistema.
agent Otro o sin especificar Error. Las cargas de trabajo con functional-type=agent deben usar identity-type=agent-identity.
mcp-server agent-identity, service-account o sin especificar La carga de trabajo se registra como un servidor de MCP (/mcpServers) en Agent Registry. Si no se especifica, la configuración predeterminada es una identidad de cuenta de servicio.
Sin especificar service-account La carga de trabajo se ejecuta como un servicio o trabajo estándar de Cloud Run.

Configura funciones en servicios y trabajos

Para configurar las funciones de Agent Platform en tus servicios y trabajos de Cloud Run, usa Google Cloud CLI.

Servicios

  • Para implementar un agente, especifica --functional-type=agent y --identity-type=agent-identity:

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=agent \
    --identity-type=agent-identity

    Reemplaza lo siguiente:

    • SERVICE_NAME: El nombre de tu servicio de Cloud Run.
    • IMAGE_URL: Una referencia a la imagen del contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME debe estar creado. La URL sigue el formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

  • Para actualizar un servicio existente para usar Agent Identity, haz lo siguiente:

    gcloud beta run services update SERVICE_NAME \
    --functional-type=agent \
    --identity-type=agent-identity \
    --no-traffic

    Reemplaza lo siguiente:

    • SERVICE_NAME: El nombre de tu servicio de Cloud Run.
    • ORGANIZATION_ID: Tu Google Cloud ID de organización.
    • PROJECT_NUMBER: Tu Google Cloud número de proyecto.
    • REGION: La región en la que se implementa tu servicio.

  • Para implementar un servidor de MCP administrado por el usuario, especifica --functional-type=mcp-server. De manera opcional, puedes especificar un tipo de identidad con --identity-type:

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=mcp-server \
    --identity-type=IDENTITY_TYPE

    Reemplaza lo siguiente:

    • SERVICE_NAME: El nombre de tu servicio de Cloud Run.
    • IMAGE_URL: Una referencia a la imagen del contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/hello:latest. Si usas Artifact Registry, el repositorio REPO_NAME debe estar creado. La URL sigue el formato de LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • IDENTITY_TYPE: Opcional. El tipo de identidad asignado a la carga de trabajo. Especifica agent-identity o service-account. La configuración predeterminada es service-account.

Trabajos

  • Para crear un trabajo de agente, especifica --functional-type=agent y --identity-type=agent-identity:

    gcloud beta run jobs create JOB_NAME \
  --image=IMAGE_URL \
  --functional-type=agent \
  --identity-type=agent-identity

    Reemplaza lo siguiente:

    • JOB_NAME: El nombre de tu trabajo de Cloud Run.
    • IMAGE_URL: Una referencia a la imagen del contenedor.

Ver las identidades asignadas

Puedes ver la identidad del agente asignada desde la Google Cloud consola o la gcloud CLI.

Servicios

Console

  1. En la consola Google Cloud , ve a Cloud Run:

    Ir a Cloud Run

  2. Selecciona Servicios en el menú de navegación de Cloud Run y haz clic en tu servicio.

  3. Haz clic en la pestaña Revisiones y selecciona una revisión.

  4. Haz clic en la pestaña Seguridad.

En el campo Identidad , se muestra la identidad del agente asignada.

gcloud

Para ver la identidad del agente, describe la revisión de tu servicio:

gcloud beta run revisions describe REVISION_NAME

Reemplaza REVISION_NAME por el nombre de la revisión de tu servicio.

La identidad del agente asignada se muestra en el resultado.

Trabajos

Console

  1. En la consola Google Cloud , ve a Cloud Run:

    Ir a Cloud Run

  2. Selecciona Trabajos en el menú de navegación de Cloud Run y haz clic en tu trabajo.

  3. Haz clic en la pestaña Ejecuciones y selecciona una ejecución.

  4. Consulta los detalles de la ejecución.

En el campo Identidad , se muestra la identidad del agente asignada.

gcloud

Para ver la identidad del agente para una ejecución de trabajo, describe la ejecución:

gcloud beta run jobs executions describe EXECUTION_NAME

Reemplaza EXECUTION_NAME por el nombre de la ejecución de tu trabajo.

La identidad del agente asignada se muestra en el resultado.

Cómo ver un agente o MCP en Agent Registry

Cuando implementas un recurso de Cloud Run con --functional-type=agent o --functional-type=mcp-server, se registra automáticamente en el Agent Registry de tu organización.

Para ver tus agentes y herramientas registrados en el registro, y obtener información para almacenar y descubrir de forma segura tus agentes y herramientas, explora Agent Registry.

¿Qué sigue?