Use manual registration

You require manual registration in Agent Registry for agents hosted outside Google Cloud, running on unsupported runtimes, or deployed across different Google Cloud projects. This document shows you how to manually register agents in Agent Registry.

Warning: This feature isn't supported in the us and eu multi-region locations. You must use a supported region or the global location. For more information, see Agent Registry locations.

Before you begin

Before you start, set up Agent Registry. You need the project ID to perform these tasks.

To use the Google Cloud CLI commands in this document, make sure you have set up your gcloud CLI environment.

Required roles

To get the permissions that you need to manually register agents in Agent Registry, ask your administrator to grant you the following IAM roles on the project:

To register agents in Agent Registry: Agent Registry API Editor (roles/agentregistry.editor)
For cross-project registration, to access agent metadata in a remote project: Agent Registry API Viewer (roles/agentregistry.viewer)

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.

You don't require any additional permissions if the agent's endpoint or Agent Card is accessible using standard public URLs or authenticated through pre-configured credentials.

Register an A2A-compliant agent

If your remote agent implements the Agent2Agent (A2A) specification, direct Agent Registry to the agent's agent-card.json payload. The registry automatically synchronizes the Agent Card and indexes the agent's available A2A skills for discovery.

Follow these steps to register the agent:

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.
Click Add agent.
In the Agent details panel, enter the following details:
- Type: Select A2A.
- Region: Select the geographic location where you want to register the agent.
Choose one of the following options:
- To register the agent using its resource URI, select the From URI tab and enter a valid URL in the URI field. Then, click Import to get the Agent Card from the URL.
- To copy and paste the Agent Card content, select the Paste JSON tab and paste the full contents of your agent-card.json file.
Click Save.

gcloud

To register an A2A agent, save the agent's Agent Card as a local JSON file, for example, agent-card.json, and do the following:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json

The maximum file size for the specification file is 10 KB.

Replace the following:

AGENT_NAME: The name you want to give to your agent, for example, my-support-agent.
PROJECT_ID: The project ID.
REGION: The region where you want to register the agent. If you don't want to use a specific region, use the value global.
DISPLAY_NAME: The human-readable name that you want to give to your agent, for example, Support Agent.

Terraform

To register an A2A-compliant agent, configure the google_agent_registry_service resource. Specify the agent_spec block with the A2A_AGENT_CARD type and the content representing your Agent Card JSON payload:

resource "google_agent_registry_service" "a2a_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"

  agent_spec {
    type    = "A2A_AGENT_CARD"
    content = jsonencode({
      schemaVersion = "v1"
      displayName   = "DISPLAY_NAME"
      description   = "A custom support agent registered using Terraform."
      skills = [
        {
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
        }
      ]
    })
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.a2a_agent.registry_resource
}

Replace the following:

REGION: The region where you register the agent.
AGENT_NAME: The unique name you want to give to your agent, for example, my-support-agent.
DISPLAY_NAME: The human-readable name that you want to give to your agent, for example, Support Agent.

Register a standard REST agent

Standard REST agents are discoverable by name and description, but don't have searchable A2A skills unless they adopt the A2A protocol.

If you want to register a remote agent that doesn't implement the A2A specification, such as a standard REST or SaaS API endpoint, the Agent Registry API creates a Service resource with no agent protocol specification.

Follow these steps to register the agent:

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.
Click Add agent.
In the Agent details panel, enter the following details:
- Type: Select Non-A2A.
- Name: Enter a human-readable display name for your agent, such as Travel Agent.
- Description: Enter a description of the agent's capabilities, such as A test agent that plans travel itineraries.
- Region: Select the geographic location where you want to register the agent.
- Endpoint: Enter the endpoint where the agent is hosted.
Click Save.

gcloud

You can optionally provide the defined HTTP/JSON endpoint interface with the --interfaces flag so that the registry establishes a connection with the agent.

To register a standard REST agent, do the following:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

Replace the following:

AGENT_NAME: The name you want to give to your agent, for example, my-remote-rest-agent.
PROJECT_ID: The project ID.
REGION: The registry region.
DISPLAY_NAME: The human-readable name that you want to give to your agent, for example, Remote REST Agent.
ENDPOINT_URL: The agent's API endpoint URL, for example, https://api.remote-service.com/v1/agents/1234.
PROTOCOL: The protocol binding for the endpoint. Valid values are http-json, grpc, or jsonrpc.

Terraform

To register a standard REST agent, configure the google_agent_registry_service resource with agent_spec set to NO_SPEC type, and define the endpoint interface connections:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "A standard REST agent registered using Terraform."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.rest_agent.registry_resource
}

Replace the following:

REGION: The region where you register the agent.
AGENT_NAME: The unique name you want to give to your agent, for example, my-remote-rest-agent.
DISPLAY_NAME: The human-readable name that you want to give to your agent, for example, Remote REST Agent.
ENDPOINT_URL: The agent's API endpoint URL, for example, https://api.remote-service.com/v1/agents/1234.
PROTOCOL: The protocol binding for the endpoint. Valid values are HTTP_JSON, GRPC, or JSONRPC.

Register an agent from another project

If your organization deploys agents across multiple Google Cloud projects and uses a central Agent Gateway to govern egress traffic, you can register agents from spoke or workload projects into the central Agent Registry catalog.

Because automatic registration only discovers resources created in the same project, you must manually register each remote agent into the central governance project's registry.

Considerations for cross-project registration

Before you register agents across projects, review the following:

Compatible locations: The Agent Registry instance, the Agent Gateway, and the agent endpoints must reside in the same geographic region or the global location.
Automatic discovery limitation: Automatic cross-project discovery is not supported. You must manually register each remote agent.
Lifecycle management: Manual entries in Agent Registry are not automatically updated or deleted when changes occur in the remote project. You must manage the lifecycle of these entries in the central registry when remote agents are modified or removed.
Egress mode only: Cross-project governance with Agent Gateway is supported only for Agent-to-Anywhere (egress) gateways. Client-to-Agent ingress gateways require the agent and gateway to be in the same project.

Register the remote agent

To manually register an agent from another project, follow these steps:

Console

In the Google Cloud console, go to Agent Registry:

Go to Agent Registry
From the project picker, select the central governance Google Cloud project where you want to register the agent.
Select the Agents tab.
Click Add agent.
In the Agent details panel, enter the following details:
- Type: Select A2A if the remote agent implements the A2A protocol, or Non-A2A for a standard REST endpoint.
- Region: Select the region matching your central gateway and remote agent deployment.
Provide the agent endpoint:
- For A2A agents, select From URI and enter the remote agent's Agent Card URL, or select Paste JSON and paste the agent-card.json content.
- For non-A2A agents, enter the Endpoint URL of the remote agent.
Click Save.

gcloud

A2A agent: To register an A2A agent from another project using the gcloud CLI, run the following command in the central governance project:

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json

REST agent: To register a standard REST agent from another project, run the following command in the central governance project:

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=REMOTE_ENDPOINT_URL,protocolBinding=PROTOCOL

Replace the following:

AGENT_NAME: The name for your agent in the central registry, for example, remote-support-agent.
CENTRAL_PROJECT_ID: The project ID of the central governance project.
REGION: The region where you register the agent.
DISPLAY_NAME: The human-readable name for the agent, for example, Remote Support Agent.
REMOTE_ENDPOINT_URL: The endpoint URL of the agent running in the remote project, for example, https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app.
PROTOCOL: The protocol binding for the endpoint. Valid values are http-json, grpc, or jsonrpc.

Terraform

To register a remote agent in a central governance project using Terraform, configure the google_agent_registry_service resource and specify the central project:

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project REMOTE_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "REMOTE_ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.remote_agent.registry_resource
}

Replace the following:

CENTRAL_PROJECT_ID: The project ID of the central governance project.
REGION: The region where you register the agent.
AGENT_NAME: The unique name for your agent in the registry, for example, remote-support-agent.
DISPLAY_NAME: The human-readable name for the agent, for example, Remote Support Agent.
REMOTE_PROJECT_ID: The project ID where the agent is hosted.
REMOTE_ENDPOINT_URL: The endpoint URL of the agent running in the remote project.
PROTOCOL: The protocol binding for the endpoint. Valid values are HTTP_JSON, GRPC, or JSONRPC.

Verify registration

After registering your agent, verify that Agent Registry successfully processed the Service and created the corresponding Agent resource:

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.

gcloud

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

If you have multiple agents, or if you want to confirm the registration of a single agent, you can filter the list by the agent's metadata:

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

Replace the following:

PROJECT_ID: The project ID.
REGION: The region where you want to register the agent. If you don't want to use a specific region, use the value global.
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 identifier (URN), you can use agentId='urn:agent:AGENT_URN'.

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
}

Replace the following:

REGION: The registry region.
DISPLAY_NAME: The human-readable display name of the agent.

What's next

Learn how to manage registered agents.
Learn about automatic registration, the recommended method to register agents deployed to managed runtimes.

Use manual registration Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required roles

Register an A2A-compliant agent

Console

gcloud

Terraform

Register a standard REST agent

Console

gcloud

Terraform

Register an agent from another project

Considerations for cross-project registration

Register the remote agent

Console

gcloud

Terraform

Verify registration

Console

gcloud

Terraform

What's next

Use manual registration