Registra extremos

En Agent Registry, un extremo representa una URL de destino, por lo general, una API de REST, a la que acceden tus agentes. Si registras estos destinos como componentes de agentes administrados en Agent Registry, puedes controlar de forma centralizada a qué extremos externos puede conectarse tu flota de agentes.

En este documento, se explica cómo registrar explícitamente extremos externos en el registro.

Antes de comenzar

Antes de comenzar, configura Agent Registry. Necesitas el ID de tu proyecto para realizar estas tareas.

Para usar los comandos de Google Cloud CLI en este documento, asegúrate de haber configurado tu entorno de gcloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para registrar extremos en Agent Registry, pídele a tu administrador que te otorgue el rol de IAM Editor de la API de Agent Registry (roles/agentregistry.editor) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Registra un extremo

Dado que los extremos son destinos externos personalizados, usa el registro manual para agregarlos a Agent Registry:

Console

  1. En la Google Cloud consola, ve a Agent Registry:

    Ir a Agent Registry

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.

  3. Selecciona la pestaña Endpoints.

  4. Haz clic en Add endpoint.

  5. En el panel Endpoint details , ingresa el nombre visible, una descripción, la región geográfica y la URL de destino.

    De manera opcional, haz clic en Test connection en este panel para probar tu conexión a la URL de destino.

  6. Haz clic en Guardar.

gcloud

Crea un recurso Service con un endpoint-spec-type de no-spec.

Registra el extremo y define los detalles de conexión de su interfaz:

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

Reemplaza lo siguiente:

  • ENDPOINT_NAME: El nombre que deseas asignarle a tu extremo, por ejemplo, my-external-api.
  • PROJECT_ID: El ID del proyecto
  • REGION: La región del registro.
  • DISPLAY_NAME: El nombre legible del extremo.
  • ENDPOINT_URL: La URL de destino, por ejemplo, https://api.example.com/v1/data.
  • PROTOCOL: La vinculación de protocolo para la interfaz. Los valores válidos son http-json, grpc o jsonrpc.

Después de crear el recurso Service, Agent Registry genera automáticamente un recurso Endpoint de solo lectura en el lado del consumidor que los agentes y los orquestadores pueden descubrir y usar.

Terraform

Para registrar un extremo externo, configura el recurso google_agent_registry_service con el bloque endpoint_spec:

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
}

Reemplaza lo siguiente:

  • REGION: La región del registro.
  • ENDPOINT_NAME: El nombre único que deseas asignarle a tu extremo, por ejemplo, my-external-api.
  • DISPLAY_NAME: El nombre legible del extremo.
  • ENDPOINT_URL: La URL de destino, por ejemplo, https://api.example.com/v1/data.
  • PROTOCOL: La vinculación de protocolo para la interfaz. Los valores válidos son HTTP_JSON, GRPC o JSONRPC.

Registra un extremo compuesto de las APIs de Google

En una arquitectura entre proyectos, un proyecto de administración central aloja la infraestructura compartida, como Agent Registry y Agent Gateway, y los proyectos de carga de trabajo individuales alojan instancias de procesamiento de agentes.

Cuando enrutas el tráfico de agentes a través de Agent Gateway en modo de salida, el tráfico de red saliente se bloquea de forma predeterminada. Para permitir que los agentes de los proyectos de carga de trabajo se comuniquen con las APIs esenciales Google Cloud , puedes agrupar varias interfaces de API en un solo extremo compuesto Service en el proyecto de administración central.

Agrupar interfaces en un solo extremo simplifica la administración de políticas, ya que te permite administrar una sola vinculación de políticas de IAP para todo el conjunto de APIs principales de Google.

Sigue estos pasos para registrar un extremo compuesto de las APIs de Google:

gcloud

Registra el extremo con varias URLs de interfaz en el proyecto de administración central:

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

Reemplaza lo siguiente:

  • SERVICE_NAME: El identificador del servicio, por ejemplo, core-gapi-services.
  • CENTRAL_PROJECT_ID: El ID del proyecto de administración central que aloja Agent Registry y Agent Gateway.
  • REGION: La región en la que residen tu puerta de enlace y tu registro.
  • DISPLAY_NAME: El nombre legible, por ejemplo, Core Google APIs.
  • DESCRIPTION: Una breve descripción, por ejemplo, Essential Google APIs for agent operations.
  • API_URL: La URL de la API principal de Google, como https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: Repite la marca --interfaces para cada URL o variante adicional de la API de Google que requieran tus agentes, como https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com o variantes regionales y de mTLS como https://telemetry.mtls.googleapis.com.

Terraform

Para registrar el extremo compuesto de las APIs de Google con Terraform, define el recurso google_agent_registry_service con varios bloques interfaces:

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"
  }
}

Reemplaza lo siguiente:

  • CENTRAL_PROJECT_ID: El ID del proyecto de administración central.
  • REGION: La región del registro.
  • SERVICE_NAME: El ID del servicio.
  • DISPLAY_NAME: El nombre legible.
  • DESCRIPTION: La descripción del servicio.
  • API_URL: La URL de la API principal de Google, como https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: Repite el bloque interfaces para cada URL o variante adicional de la API de Google que requieran tus agentes, como https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com o variantes regionales y de mTLS como https://telemetry.mtls.googleapis.com.

¿Qué sigue?