Use manual registration

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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

Note: Manual registration isn't supported in the us and eu multi-region locations. You must register resources in 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 gcloud CLI commands in this document, make sure you have set up your Google Cloud 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

1. In the Google Cloud console, go to Agent Registry:

   Go to Agent Registry

2. From the project picker, select the Google Cloud project where you set up Agent Registry.

3. Select the Agents tab.

4. Click Add agent.

5. In the Agent details panel, enter a display name, a description, and select the geographic region.

6. For the agent type, select A2A.

7. In the agent specification section, select the Paste JSON tab and paste the full contents of your agent-card.json file.

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

Note: The agent specification file you upload must not exceed 10 KB in size.

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 registry region.
• 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

1. In the Google Cloud console, go to Agent Registry:

   Go to Agent Registry

2. From the project picker, select the Google Cloud project where you set up Agent Registry.

3. Select the Agents tab.

4. Click Add agent.

5. In the Agent details panel, enter a display name, a description, and select the geographic region.

6. For the agent type, select the option indicating no specification, such as Non-A2A.

7. Enter the endpoint where the agent is hosted and select the protocol binding if required, such as HTTP_JSON.

8. 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 alpha 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 service 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

1. In the Google Cloud console, go to Agent Registry:

   Go to Agent Registry

2. From the project picker, select the Google Cloud project where you set up Agent Registry.

3. Select the Agents tab.

   The page must displays a list of all registered agents and their details.

gcloud

gcloud alpha 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 alpha 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 identifier (URN), you can use agentId='urn:agent:AGENT_URN'.