Register endpoints

Agent Registry lets you manually register target URLs, such as external REST APIs, as managed endpoints so that you can centrally govern which destinations your fleet of agents can connect to.

Endpoint registration 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

  1. Set up Agent Registry.

  2. Get the project ID for the governance project where Agent Registry is enabled.

  3. To use the Google Cloud CLI commands in this document, set up your gcloud CLI environment.

Required roles

To get the permissions that you need to register endpoints in Agent Registry, ask your administrator to grant you the Agent Registry API Editor (roles/agentregistry.editor) IAM role on the governance project where Agent Registry is enabled. 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 endpoint

Because endpoints are custom, external destinations, use manual registration to add them to Agent Registry:

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

  4. Click Add endpoint.

  5. In the Endpoint details panel, enter the display name, a description, the geographic region, and the destination URL.

    Optionally, click Test connection in this panel to test your connection to the destination URL.

  6. Click Save.

gcloud

The specification flags you use determine which resource collection your component belongs to. For a complete mapping of flags to resource collections, see [Service resources and discovery resources](/agent-registry/data-model#service-resources).

To add your endpoint to Agent Registry, create a Service resource with the gcloud agent-registry services create command and the --endpoint-spec-type flag set to no-spec:

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

Replace the following:

  • ENDPOINT_NAME: the name you want to give to your endpoint, for example, my-external-api. The name must be 4 to 63 characters and can contain only lowercase letters, numbers, and hyphens.
  • PROJECT_ID: the project ID.
  • REGION: the registry region.
  • DISPLAY_NAME: the human-readable name of the endpoint, for example, My External API.
  • ENDPOINT_URL: the target URL, for example, https://api.example.com/v1/data.
  • PROTOCOL: the protocol binding for the interface. Valid values are http-json, grpc, or jsonrpc.

After the Service resource is created, Agent Registry automatically generates a read-only Endpoint resource that agents and orchestrators can discover and use.

Terraform

The specification block you configure determines which resource collection your component belongs to. For a complete mapping of specifications to resource collections, see [Service resources and discovery resources](/agent-registry/data-model#service-resources).

To register an external endpoint, configure the google_agent_registry_service resource with the endpoint_spec block:

resource "google_agent_registry_service" "endpoint" {
  location     = "REGION"
  service_id   = "ENDPOINT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "An external REST API registered using Terraform."

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

  endpoint_spec {
    type = "NO_SPEC"
  }
}

output "endpoint_resource_name" {
  description = "The generated read-only Endpoint resource name."
  value       = google_agent_registry_service.endpoint.registry_resource
}

Replace the following:

  • REGION: the registry region.
  • ENDPOINT_NAME: the unique name you want to give to your endpoint, for example, my-external-api. The name must be 4 to 63 characters and can contain only lowercase letters, numbers, and hyphens.
  • DISPLAY_NAME: the human-readable name of the endpoint, for example, My External API.
  • ENDPOINT_URL: the target URL, for example, https://api.example.com/v1/data.
  • PROTOCOL: the protocol binding for the interface. Valid values are HTTP_JSON, GRPC, or JSONRPC.

Register a composite Google APIs endpoint

In a cross-project architecture, a central governance project hosts shared infrastructure such as Agent Registry and Agent Gateway, and separate Google Cloud projects host agent compute instances.

When you route agent traffic through Agent Gateway in egress mode, outbound network traffic is blocked by default. To let agents in separate Google Cloud projects communicate with essential Google Cloud APIs, you can group multiple API interfaces into a single composite Service resource in the central governance project.

Grouping interfaces into a single endpoint simplifies policy administration by letting you manage a single Identity-Aware Proxy (IAP) policy binding for the entire suite of core Google APIs.

Follow these steps to register a composite Google APIs endpoint:

gcloud

Register the endpoint with multiple interface URLs in the central governance project by using the gcloud agent-registry services create command:

gcloud agent-registry services create SERVICE_NAME \
    --project=CENTRAL_PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --endpoint-spec-type=no-spec \
    --interfaces=protocolBinding=jsonrpc,url=API_URL \
    --interfaces=protocolBinding=jsonrpc,url=ADDITIONAL_API_URL

Replace the following:

  • SERVICE_NAME: the identifier for the service, for example, core-gapi-services. The name must be 4 to 63 characters and can contain only lowercase letters, numbers, and hyphens.
  • CENTRAL_PROJECT_ID: the project ID of the central governance project hosting Agent Registry and Agent Gateway.
  • REGION: the region where your gateway and registry reside.
  • DISPLAY_NAME: the human-readable name, for example, Core Google APIs.
  • DESCRIPTION: a brief description, for example, Essential Google APIs for agent operations.
  • API_URL: the URL of the primary Google API, such as https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: repeat the --interfaces flag for each additional Google API URL or variant required by your agents, such as https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com, or regional and mTLS variants such as https://telemetry.mtls.googleapis.com.

Terraform

To register the composite Google APIs endpoint using Terraform, define the google_agent_registry_service resource with multiple interfaces blocks:

resource "google_agent_registry_service" "core_gapi_services" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "SERVICE_NAME"
  display_name = "DISPLAY_NAME"
  description  = "DESCRIPTION"

  endpoint_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "API_URL"
    protocol_binding = "JSONRPC"
  }

  # Add an interfaces block for each additional Google API URL
  interfaces {
    url              = "ADDITIONAL_API_URL"
    protocol_binding = "JSONRPC"
  }
}

Replace the following:

  • CENTRAL_PROJECT_ID: the project ID of the central governance project.
  • REGION: the registry region.
  • SERVICE_NAME: the service ID, for example, core-gapi-services. The name must be 4 to 63 characters and can contain only lowercase letters, numbers, and hyphens.
  • DISPLAY_NAME: the human-readable name, for example, Core Google APIs.
  • DESCRIPTION: the endpoint description.
  • API_URL: the URL of the primary Google API, such as https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: repeat the interfaces block for each additional Google API URL or variant required by your agents, such as https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com, or regional and mTLS variants such as https://telemetry.mtls.googleapis.com.

What's next