Use automatic registration for agents

Agent Registry lets you configure automatic registration for agents on supported Google Cloud runtimes so that developers and orchestrator agents can discover them without manually creating registry resources. Depending on the runtime, registration happens by default or through an opt-in deployment step, and the indexed metadata depends on the implementation protocol.

Automatic registration only discovers supported resources deployed within the governance project where Agent Registry is enabled. To register remote agents deployed in other Google Cloud projects, see Register an agent from another project. For remote agents hosted externally or on unsupported runtimes, see Use manual registration for agents.

Automatically indexed metadata

The metadata and capabilities indexed for an agent during automatic registration depend on whether the agent implements the Agent2Agent (A2A) protocol:

Agents implementing the A2A protocol: Agent Registry queries the agent's /.well-known/agent-card.json Agent Card to automatically extract its advertised A2A skills and capabilities in Agent Registry.
Agents not implementing the A2A protocol: Agent Registry registers the agent, but can't automatically capture metadata such as the endpoint URL where the agent is hosted, the agent identity, and A2A skills. These are agents that expose, for example, standard REST or gRPC endpoints. To associate capabilities with non-A2A agents, use manual registration or register skills.

Before you begin

Set up Agent Registry.
Get the project ID for the governance project where Agent Registry is enabled.
To use the Google Cloud CLI commands in this document, set up your gcloud CLI environment.

Register agents from Agent Runtime

If you develop and deploy agents with Agent Runtime on Gemini Enterprise Agent Platform, registration in Agent Registry is automatic.

The following example shows how to deploy an agent implementing the A2A protocol to Agent Runtime. For more information, see Deploy an agent.

# Create and deploy the agent
# This action automatically registers the agent in Agent Registry
remote_agent = client.agent_engines.create(
    agent=my_a2a_agent, # Your defined A2A object
    config={
        "display_name": "my-support-agent",
        "description": "An agent that handles support tickets.",
        "requirements": ["google-cloud-aiplatform[agent_engines,langchain]"],
    },
)

As you update or delete your agent in Agent Runtime, Agent Registry automatically synchronizes those changes.

Register built-in Google agents

Built-in Google agents, such as Google Workspace and Gemini Enterprise agents, are automatically registered in Agent Registry. You don't need to perform any configuration or deployment steps. These agents are ingested and available for discovery within your registry.

Register agents from GKE

To register agents deployed on Google Kubernetes Engine (GKE), add the required Kubernetes labels and annotations to your deployment manifest. The following example shows a GKE manifest that defines a Kubernetes Deployment and a Kubernetes Service configured for automatic registration:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
  labels:
    # GKE takes this label and registers the agent to Agent Registry
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  selector:
    matchLabels:
      app: my-agent
  template:
    metadata:
      labels:
        app: my-agent
      annotations:
        # Agent Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
    spec:
      containers:
      - name: server
        image: gcr.io/PROJECT_ID/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
# Kubernetes Service for in-cluster network routing to the agent pod
apiVersion: v1
kind: Service
metadata:
  name: my-agent-service
  labels:
    app: my-agent
spec:
  type: ClusterIP
  ports:
  - port: 8080
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: my-agent

Replace PROJECT_ID with your Google Cloud project ID.

To configure and apply the deployment manifest, do the following:

In metadata.labels of your Deployment manifest, add the registry.gke.io/functional-type: "AGENT" label. This label identifies the deployment as an AI agent workload, which instructs the GKE cluster runtime controller to inspect the workload and register the agent with Agent Registry.

Note: GKE also supports the apphub.cloud.google.com/functional-type: "AGENT" annotation for backward compatibility. However, use the registry.gke.io/functional-type: "AGENT" label for your GKE deployments.
In metadata.annotations of your Deployment manifest, enable automated discovery of the agent's A2A skills by providing the a2a-protocol.org/agent-card annotation. The GKE ingestion controller uses this annotation to query the A2A Agent Card.
In spec.template.metadata.annotations of the Pod template, enable authenticated communication by configuring Agent Identity with the iam.gke.io/spiffe-identity-type: agent-identity annotation.
Apply the deployment manifest to your cluster. For more information, see Deploy and orchestrate AI agents.

When you apply the deployment, the GKE cluster runtime controller automatically inspects the workload container and queries the Agent Card endpoint declared in the annotation. It then syncs the agent's metadata and A2A skills directly into a read-only Agent discovery resource in Agent Registry.

Register agents from Cloud Run

You can automatically register agents when you deploy them as Cloud Run services or jobs by specifying the --functional-type=agent and --identity-type=agent-identity flags. The --functional-type=agent flag identifies the Cloud Run service or job as an AI agent rather than a standard containerized workload, instructing Cloud Run to register the agent with Agent Registry. During registration, Cloud Run automatically adds the agent's name and the AGENT type to the registry.

Workloads configured with --functional-type=agent must specify the --identity-type=agent-identity flag. Deploying with any other identity type results in an error.

To configure automatic registration on a new or existing Cloud Run service or job, see Configure Gemini Enterprise Agent Platform features for Cloud Run. To prepare, containerize, and deploy an A2A-compliant agent on Cloud Run, see Deploy A2A agents to Cloud Run.

Verify registration

You can verify that Agent Registry successfully registered your agents by listing them:

Console

In the Google Cloud console, go to Agent Registry:

Go to Agent Registry
From the project picker, select the Google Cloud project where you set up Agent Registry.
Select the Agents tab.

The page displays a list of all registered agents and their details, such as name, identifier, description, runtime, and location.
Filter the list by the agent's location or its runtime resource:
- To filter by location, click the Location menu, select the locations you want to filter, and click Apply.
- To filter by runtime, click the Runtime menu, select the runtimes you want to filter, and click Apply.
The page displays a filtered list of the registered agents for your selected conditions.

gcloud

You can filter the list by the agent's metadata. Make sure you have set up your gcloud CLI environment for Agent Registry, and then run the gcloud agent-registry agents list command:

gcloud agent-registry agents list \
    --project=PROJECT_ID \
    --location=REGION \
    --filter="FILTER_EXPRESSION"

Replace the following:

PROJECT_ID: the project ID.
REGION: the registry region.
FILTER_EXPRESSION: the filter expression for the agents that you want to filter. For example, to filter by display name, you can use displayName='DISPLAY_NAME'. To filter by the globally unique agent identifier (URN), you can use agentId='urn:agent:AGENT_URN'.

Built-in Google agents use an agent identifier (URN) format that depends on where the agent is deployed. For example, you can discover built-in Google Workspace agents by filtering your list for the googleapis.com publisher using --filter="agentId:'urn:agent:googleapis.com:*'".

Terraform

Reference your registered agent in other Terraform configurations by using the google_agent_registry_agent data source:

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  filter = "displayName=\"DISPLAY_NAME\""
}

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}