Manage and discover endpoints

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.

Effective management of your fleet of agents requires keeping your network of endpoints accurate. This document details how to discover available endpoints, update their connection details, or remove them when they are no longer in use.

Before you begin

Before you can manage endpoints, register endpoints in Agent Registry. You also need your 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 manage endpoints in Agent Registry, ask your administrator to grant you the following IAM roles on the project:

• Discover endpoints: Agent Registry API Viewer (roles/agentregistry.viewer)
• Update and delete endpoints: Agent Registry API Editor (roles/agentregistry.editor)

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.

Discover endpoints

To browse the target URLs and REST APIs registered in your environment, list the available endpoint resources.

List all endpoints

List all registered endpoints in your environment:

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.

   The page displays a list of all registered endpoints and their details, such as name, description, and location.

4. To view the full connection details of an endpoint, click the endpoint's name.

gcloud

To list all endpoints in a specific location, use the endpoints list command:

gcloud alpha agent-registry endpoints list \
  --project=PROJECT_ID \
  --location=REGION

Replace the following:

• PROJECT_ID: The project ID.
• REGION: The registry region.

Filter registered endpoints

If you have multiple endpoints, you can filter the list by the endpoint's metadata:

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.

   The page displays a list of all registered endpoints and their details, such as name, description, and location.

4. To filter by location, click the Location menu, select the locations you want to filter, and click Apply.

   The page displays a filtered list of the registered endpoints for your selected conditions.

gcloud

Filter your list to only return resources matching specific metadata, using the --filter flag:

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

Replace FILTER_EXPRESSION with the filter expression for the endpoints that you want to filter. For example, to filter by display name, use displayName='DISPLAY_NAME'.

View details from an endpoint

View details from a specific endpoint, including its connection details and protocol bindings:

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.

   The page displays a list of all registered endpoints and their details, such as name, description, and location.

4. Click the name of the endpoint that you want to view.

   The Overview page displays the name, description, location, and connection details of the endpoint, including the destination URL and the protocol bindings.

gcloud

Retrieve detailed metadata about a specific endpoint, including its full interface URL and protocol binding:

gcloud alpha agent-registry endpoints describe ENDPOINT_NAME \
  --project=PROJECT_ID \
  --location=REGION

Replace the following:

• PROJECT_ID: The project ID.
• REGION: The registry region.
• ENDPOINT_NAME: The name of your endpoint, for example, my-external-api.

Update an endpoint

If the underlying URL of an external service changes, you can update the endpoint interface details.

Follow these steps to update an endpoint:

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.

   The page displays a list of all registered endpoints and their details, such as name, description, and location.

4. Click the name of the endpoint that you want to update.

   The Overview page displays the name, description, location, and connection details of the endpoint, including the destination URL and the protocol bindings.

5. Click Edit.

6. In the Edit service panel, enter the updated information for the endpoint, such as the display name, description, and destination URL. You can test the connection to the endpoint from this panel.

7. Click Save.

gcloud

For the Agent Registry API, Endpoint resources are used for discovery. Therefore, you must update the registered Service resource directly.

Use the --interfaces flag to specify the new target URL:

gcloud alpha agent-registry services update SERVICE_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

Replace the following:

• SERVICE_NAME: The name of your resource, for example, my-external-api.
• PROJECT_ID: The project ID.
• REGION: The registry region.
• ENDPOINT_URL: The new target URL, for example, https://new-api.example.com/v1/data.
• PROTOCOL: The protocol binding for the interface. Valid values are HTTP_JSON, GRPC, or JSONRPC.

Remove an endpoint

To remove an endpoint from the registry, you must delete its underlying Service resource. This action immediately removes the endpoint from discovery search results.

Follow these steps to remove an endpoint from your 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.

   The page displays a list of all registered endpoints and their details, such as name, description, and location.

4. Click the name of the endpoint that you want to remove.

   The Overview page displays the name, description, location, and connection details of the endpoint, including the destination URL and the protocol bindings.

5. Click Delete.

6. In the Delete endpoint window, enter DELETE to confirm the action.

7. Click Delete.

gcloud

gcloud alpha agent-registry services delete SERVICE_NAME \
  --project=PROJECT_ID \
  --location=REGION