Configura las funciones de Agent Platform para Cloud Run

Vista previa : Configura las funciones de la plataforma de agentes 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.

Gemini Enterprise Agent Platform proporciona capacidades integradas para crear, implementar y administrar agentes de IA, servidores del Protocolo de contexto del modelo (MCP) y herramientas. Esto te permite 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.

• Agent Identity asigna una identidad criptográfica única a tu carga de trabajo de Cloud Run para que pueda conectarse a otros agentes, herramientas y APIs de Google Cloud .
• Agent Registry registra tus agentes y herramientas para que los desarrolladores y agentes de tu organización puedan descubrirlos.

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

• Establece los roles de IAM necesarios
• Información sobre los tipos funcionales y de identidad
• Configura funciones para servicios y trabajos
• Cómo ver las identidades asignadas
• Consulta los agentes y las herramientas registrados en Agent Registry

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.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

3. Install the Google Cloud CLI.

4. Configure the gcloud CLI to use your federated identity.

   For more information, see Sign in to the gcloud CLI with your federated identity.

5. To initialize the gcloud CLI, run the following command:

   gcloud init

6. Habilita la API de Cloud Run Admin, la API de Identity and Access Management, la API de Agent Registry y las APIs de App Hub, si aún no están habilitadas.

   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 de propietario (roles/owner). De lo contrario, puedes obtenerlo 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

7. Asegúrate de haber configurado el Registro de agentes 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 conocer los costos de CPU, memoria y salida de red. El tamaño total del disco aprovisionado y el ciclo de vida 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 implementar y administrar recursos de Cloud Run: Administrador de Cloud Run (roles/run.admin)
• Para administrar los recursos de App Hub, uno de los siguientes roles:
  • Administrador de App Hub (roles/apphub.admin)
  • Administrador de la API de Agent Registry (roles/apiregistry.admin)
• Para implementar con una identidad específica, una de las siguientes opciones:
  • Usuario de la cuenta de servicio de IAM (roles/iam.serviceAccountUser)
  • Administrador de cuentas de servicio de IAM (roles/iam.serviceAccountAdmin)

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 las siguientes situaciones:

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

Comprender los tipos funcionales y de identidad

Para configurar las funciones de Agent Platform, establece 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 asignada 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 inhabilitarla, actualiza tu servicio con la marca --no-identity-certificate o establece 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 bajo 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 se registra como un servidor de MCP (/mcpServers) en Agent Registry. Si no se especifica, se establece de forma predeterminada en 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

Configura 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: una referencia a la imagen de 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 y usar la identidad del agente, sigue estos pasos:

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

  Importante: Cuando actualizas un servicio existente de una cuenta de servicio a agent-identity, Cloud Run asigna una principal nueva que no hereda los permisos de tu cuenta de servicio anterior. Para evitar interrupciones de la conexión, usa el Analizador de políticas para identificar los roles necesarios y asignarlos previamente a la principal de principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME antes de actualizar, o actualiza el servicio con --no-traffic para asignar permisos antes de migrar el tráfico.

  Reemplaza lo siguiente:

  • SERVICE_NAME: El nombre de tu servicio de Cloud Run.
  • ORGANIZATION_ID: Es el ID de organización de Google Cloud.
  • PROJECT_NUMBER: Es el número del 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. 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 de 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 asignado a la carga de trabajo. Especifica agent-identity o service-account. La configuración predeterminada es service-account.

Trabajos

Nota: Solo los servicios de Cloud Run se pueden exponer como servidores de MCP. Los trabajos de Cloud Run no se pueden exponer como servidores de MCP y solo admiten el tipo funcional agent.

• 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: Es el nombre de tu trabajo de Cloud Run.
  • IMAGE_URL: Es una referencia a la imagen de contenedor.

Ver 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 de tu trabajo.

La identidad del agente asignado se muestra en el resultado.

Visualiza 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 registro de agentes 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 aprender a almacenarlos y descubrirlos de forma segura, explora Agent Registry.

¿Qué sigue?

• Obtén información para autenticar tus agentes en las APIs y las herramientas.
• Obtén información para autenticar servidores de MCP y establecer conexiones seguras.
• Obtén información para alojar servidores de MCP en Cloud Run.
• Usa el Kit de desarrollo de agentes para crear y registrar agentes personalizados en el registro.
• Para compilar e implementar agentes que cumplan con la especificación de A2A, consulta Implementa agentes de A2A en Cloud Run.
• Consulta la guía de solución de problemas si tienes problemas con el registro del agente o la asignación de identidad.