Use manual registration

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

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 Agent Registry API Editor (roles/agentregistry.editor) IAM role on the 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.

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

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

Verify registration

Console

gcloud

Terraform

What's next

Use manual registration