Configure Agent Platform features for Cloud Run

Gemini Enterprise Agent Platform features like Agent Identity and Agent Registry provide built-in capabilities for building, deploying, and managing AI agents, Model Context Protocol (MCP) servers, and tools. By enabling these features for your Cloud Run resources, you can take advantage of system-managed identities and automatic registration to simplify discovery and security for your agentic workloads.

This guide covers how to:

Cloud Run supports the following Agent Platform features:

  • Agent Identity: assigns a unique, cryptographically verifiable identity to your workload, enabling secure connections to other agents, tools, and Google Cloud APIs.
  • Agent Registry: automatically registers your agents and tools to make them discoverable by other developers and agents in your organization.

Before you begin

  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. 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. Enable the Cloud Run Admin API, Identity and Access Management API, Agent Registry API, and App Hub API APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  7. Ensure that you have set up Agent Registry in your project or organization.
  8. Install and initialize the gcloud CLI.
  9. Update components: 
    gcloud components update
  10. Review the Cloud Run pricing page for CPU, memory, and network egress. The entire size of the provisioned disk and the lifetime of the instance that is using it contribute to your cost.

Required roles

To get the permissions that you need to configure Agent Platform features, ask your administrator to grant you the following IAM roles on your project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Use cases

Use Agent Platform features with Cloud Run in the following scenarios:

  • Authenticate your agent to other agents, tools, and Google Cloud APIs using a unique, system-managed identity tied to its lifecycle.
  • Enable automatic discovery of agents and MCP servers within your organization's Agent Registry.
  • Use Identity-Aware Proxy as an authentication policy to secure MCP servers.

Understand functional and identity types

You configure Agent Platform features by setting functional and identity properties on your Cloud Run resources.

These two properties control how to register and identify a workload:

  • Functional type: declares the primary purpose of the workload. Once set, this property cannot be changed or unset. You assign your workload one of the following functional types:
    • agent: designates the workload as an AI agent. Workloads of this type must use the agent-identity type.
    • mcp-server: designates the workload as a user-managed MCP server. This type can use any supported identity type.
  • Identity type: specifies the kind of identity assigned to the workload. Once set, this property cannot be changed or unset. You assign your workload one of the following identity types:
    • agent-identity: assigns a system-managed agent identity designed for agents. When you deploy with agent-identity, Agent Platform enables identity certificates by default. To opt out, update your service with the --no-identity-certificate flag or set the run.googleapis.com/identity-certificate-enabled: "false" annotation. Follow the guide to authenticate to tools and resources for agents acting on their own authority or on behalf of end users. To understand the core concepts and security benefits of system-managed agent identities, learn more about Agent Identity.
    • service-account: uses a standard Google Cloud service account.

Configuration behavior

The behavior of functional and identity properties depends on the combination you choose:

Functional type Identity type Resulting behavior
agent agent-identity Workload is registered as an agent in the Agent Registry and assigned a system-managed agent identity.
agent Other or unspecified Error. Workloads with functional-type=agent must use identity-type=agent-identity.
mcp-server agent-identity, service-account, or unspecified Workload is registered as an MCP server (/mcpServers) in the Agent Registry. If unspecified, defaults to a service account identity.
Unspecified service-account Workload runs as a standard Cloud Run service or job.

Configure features on services and jobs

You configure Agent Platform features on your Cloud Run services and jobs using the Google Cloud CLI.

Services

  • To deploy an agent, specify --functional-type=agent and --identity-type=agent-identity:

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

    Replace the following:

    • SERVICE_NAME: the name of your Cloud Run service.
    • IMAGE_URL: a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

  • To update an existing service to use Agent Identity:

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

    Replace the following:

    • SERVICE_NAME: the name of your Cloud Run service.
    • ORGANIZATION_ID: your Google Cloud organization ID.
    • PROJECT_NUMBER: your Google Cloud project number.
    • REGION: the region where your service is deployed.

  • To deploy a user-managed MCP server, specify --functional-type=mcp-server. You can optionally specify an identity type using --identity-type:

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

    Replace the following:

    • SERVICE_NAME: the name of your Cloud Run service.
    • IMAGE_URL: a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • IDENTITY_TYPE: Optional. The type of identity assigned to the workload. Specify agent-identity or service-account. Defaults to service-account.

Jobs

  • To create an agent job, specify --functional-type=agent and --identity-type=agent-identity:

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

    Replace the following:

    • JOB_NAME: the name of your Cloud Run job.
    • IMAGE_URL: a reference to the container image.

View assigned identities

You can view the assigned agent identity from the Google Cloud console or gcloud CLI.

Services

Console

  1. In the Google Cloud console, go to Cloud Run:

    Go to Cloud Run

  2. Select Services from the Cloud Run navigation menu, and click your service.

  3. Click the Revisions tab and select a revision.

  4. Click the Security tab.

The Identity field displays the assigned agent identity.

gcloud

To view the agent identity, describe the revision of your service:

gcloud beta run revisions describe REVISION_NAME

Replace REVISION_NAME with the name of your service revision.

The assigned agent identity is displayed in the output.

Jobs

Console

  1. In the Google Cloud console, go to Cloud Run:

    Go to Cloud Run

  2. Select Jobs from the Cloud Run navigation menu, and click your job.

  3. Click the Executions tab and select an execution.

  4. View the execution details.

The Identity field displays the assigned agent identity.

gcloud

To view the agent identity for a job execution, describe the execution:

gcloud beta run jobs executions describe EXECUTION_NAME

Replace EXECUTION_NAME with the name of your job execution.

The assigned agent identity is displayed in the output.

View an agent or MCP in Agent Registry

When you deploy a Cloud Run resource with --functional-type=agent or --functional-type=mcp-server, it's automatically registered in your organization's Agent Registry.

  • Agents are registered under the agent catalog (/agents).
  • MCP servers are registered under the MCP server catalog (/mcpServers).

To view your registered agents and tools in the registry, and to learn how to securely store and discover your agents and tools, explore Agent Registry.

What's next