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.

You can register endpoints in a supported regional location, a supported
multi-region, or the `global` location. For more information about supported
locations, see [Agent Registry locations](https://docs.cloud.google.com/agent-registry/locations.md.txt).

## Before you begin

1. [Set up Agent Registry](https://docs.cloud.google.com/agent-registry/setup.md.txt).
2. For a single-project setup, get
   [the project ID](https://support.google.com/googleapi/answer/7014113)
   of the [governance project](https://docs.cloud.google.com/agent-registry/overview.md.txt#governance-project)
   where Agent Registry is enabled. If you configured a
   [management boundary](https://docs.cloud.google.com/agent-registry/boundaries-and-topology.md.txt) for multiple
   projects, use the ID of your management project for boundary-wide discovery
   and registration, or specify a member project ID for single-project
   operations.

3. To use the Google Cloud CLI commands in this document,
   [set up your gcloud CLI environment](https://docs.cloud.google.com/agent-registry/setup.md.txt#set-up-cli).

### Required roles

<br />


To get the permissions that
you need to register endpoints in Agent Registry,

ask your administrator to grant you the
[Agent Registry API Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/agentregistry.md.txt#agentregistry.editor) (`roles/agentregistry.editor`) IAM role on the [governance project](https://docs.cloud.google.com/agent-registry/overview.md.txt#governance-project)
where Agent Registry is enabled.


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Register an endpoint

Because endpoints are custom, external destinations, use
[manual registration](https://docs.cloud.google.com/agent-registry/component-lifecycle-and-discovery.md.txt#manual-registration)
to add them to Agent Registry:

### Console

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


   [Go to Agent Registry](https://console.cloud.google.com/agent-platform/agent-registry)

   <br />

2. From the project picker, select the Google Cloud project
   where you [set up Agent Registry](https://docs.cloud.google.com/agent-registry/setup.md.txt).

3. Select the **Endpoints** tab.

4. Click **Add endpoint**.

5. In the **Add Endpoint** panel, locate the **Endpoint details** section
   and select **Custom Endpoint**.

6. Enter a display name and an optional description for the endpoint, and
   then select the location.

7. In the **Destination URL** field, enter the target URL for the endpoint.

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

   > [!NOTE]
   > **Note:** You can register endpoints that use private URLs. However, the connection test only works for public endpoints, checking if the public URL is reachable. The test doesn't support private URLs or endpoints that require sending authenticated data, such as Agent Runtime on Gemini Enterprise Agent Platform endpoints.

8. 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`](https://docs.cloud.google.com/sdk/gcloud/reference/agent-registry/services/create.md.txt)
command and the `--endpoint-spec-type` flag set to `no-spec`:

```bash
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](https://docs.cloud.google.com/agent-registry/manage-endpoints.md.txt).

### 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:

```terraform
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](https://docs.cloud.google.com/agent-registry/overview.md.txt#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](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview.md.txt)
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:

### Console

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


   [Go to Agent Registry](https://console.cloud.google.com/agent-platform/agent-registry)

   <br />

2. From the project picker, select the Google Cloud project where you
   [set up Agent Registry](https://docs.cloud.google.com/agent-registry/setup.md.txt).

3. Select the **Endpoints** tab.

4. Click **Add endpoint**.

5. In the **Add Endpoint** panel, locate the **Endpoint details** section
   and select **GCP Service Endpoint**.

6. From the **GCP Service** menu, select the Google Cloud service that
   you want to register, and then select the location.

7. In the **Automatically generated Endpoint URL variants** table, select
   one or more endpoint URL variants to include in the endpoint, such as the
   base, base mTLS, locational, locational mTLS, and regional endpoint (REP)
   URLs for the service. By default, all generated variants are selected.

8. Click **Save**.

### gcloud

Register the endpoint with multiple interface URLs in the central governance
project by using the
[`gcloud agent-registry services create`](https://docs.cloud.google.com/sdk/gcloud/reference/agent-registry/services/create.md.txt)
command:

```bash
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](https://docs.cloud.google.com/agent-registry/locations.md.txt) 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:

```terraform
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

- Learn how to [manage and discover registered endpoints](https://docs.cloud.google.com/agent-registry/manage-endpoints.md.txt).
- Learn how to [configure Identity and Access Management (IAM) egress policies](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/configure-iam-policies.md.txt#agent-to-endpoint) for registered endpoints.