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 crear, 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 basadas en agentes.

En esta guía, se explica cómo hacer lo siguiente:

Cloud Run admite las siguientes funciones de la plataforma de agentes:

  • 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 otros desarrolladores y agentes de tu organización puedan descubrirlos.

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud . Si es la primera vez que usas Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  2. 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

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

  4. Instala Google Cloud CLI.

  5. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

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

    gcloud init

  7. 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

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

  9. Instala Google Cloud CLI.

  10. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

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

    gcloud init

  12. Habilita la API de Cloud Run Admin, Identity and Access Management, Agent Registry y App Hub si alguna de ellas aún no está habilitada.

    Roles necesarios para habilitar las APIs

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

    Habilitar las API

  13. Asegúrate de configurar Agent Registry en tu proyecto o organización.
  14. Instala e inicializa la CLI de gcloud
  15. Actualiza los componentes, como se indica a continuación: 
    gcloud components update
  16. Revisa la página de precios de Cloud Run para conocer los precios de 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 a través de roles personalizados o cualquier otro rol predefinido.

Casos de uso

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

  • Autentica tu agente en otros agentes, herramientas y Google Cloud APIs con una identidad única administrada por el sistema y 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.
  • Usar Identity-Aware Proxy como política de autenticación para proteger los servidores de MCP

Comprende los tipos de identidad y funcionales

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 establecido, este parámetro 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 asignada a la carga de trabajo. Una vez establecido, este parámetro 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 y diseñada para agentes. Cuando implementas con agent-identity, Agent Platform habilita los certificados de identidad de forma predeterminada. Para inhabilitar la opción, actualiza tu servicio con la marca --no-identity-certificate o configura la anotación run.googleapis.com/identity-certificate-enabled: "false". Sigue la guía para autenticarte en 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 la identidad de agentes.
    • 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 está registrada como un servidor de MCP (/mcpServers) en Agent Registry. Si no se especifica, el valor predeterminado 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

Configuras las funciones de Agent Platform en tus servicios y trabajos de Cloud Run con 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: Es 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 que use la identidad del agente, 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 ID de organización Google Cloud.
    • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
    • REGION: Es 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. Opcionalmente, 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: Es 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 Es el tipo de identidad asignada 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: Es una referencia a la imagen del contenedor.

Cómo ver las identidades asignadas

Puedes ver la identidad del agente asignado desde la consola de Google Cloud o 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 asignado.

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 del servicio.

La identidad del agente asignado 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 asignado.

gcloud

Para ver la identidad del agente de 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 del trabajo.

La identidad del agente asignado se muestra en el resultado.

Cómo ver un agente o un 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.

  • Los agentes se registran en el catálogo de agentes (/agents).
  • Los servidores de MCP se registran en el catálogo de servidores de MCP (/mcpServers).

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

¿Qué sigue?