Enregistrer des points de terminaison

Le registre d'agents vous permet d'enregistrer manuellement des URL cibles, telles que des API REST externes, en tant que points de terminaison gérés. Vous pouvez ainsi gérer de manière centralisée les destinations auxquelles votre parc d'agents peut se connecter.

L'enregistrement des points de terminaison n'est pas disponible dans les emplacements multirégionaux us et eu. Vous devez utiliser une région prise en charge ou l'emplacement global. Pour en savoir plus, consultez Emplacements du registre d'agents.

Avant de commencer

  1. Configurer le registre d'agents.

  2. Obtenez l'ID du projet pour le projet de gouvernance dans lequel Agent Registry est activé.

  3. Pour utiliser les commandes de la Google Cloud CLI dans ce document, configurez votre environnement gcloud CLI.

Rôles requis

Pour obtenir les autorisations nécessaires pour enregistrer des points de terminaison dans le registre d'agents, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de l'API Agent Registry (roles/agentregistry.editor) sur le projet de gouvernance où le registre d'agents est activé. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Enregistrer un point de terminaison

Étant donné que les points de terminaison sont des destinations externes personnalisées, utilisez l'enregistrement manuel pour les ajouter à Agent Registry :

Console

  1. Dans la console Google Cloud , accédez à Agent Registry :

    Accéder au registre d'agents

  2. Dans le sélecteur de projets, sélectionnez le projet Google Cloud dans lequel vous avez configuré Agent Registry.

  3. Sélectionnez l'onglet Points de terminaison.

  4. Cliquez sur Ajouter un point de terminaison.

  5. Dans le panneau Détails du point de terminaison, saisissez le nom à afficher, une description, la région géographique et l'URL de destination.

    Vous pouvez également cliquer sur Tester la connexion dans ce panneau pour tester votre connexion à l'URL de destination.

  6. Cliquez sur Enregistrer.

gcloud

Les options de spécification que vous utilisez déterminent la collection de ressources à laquelle appartient votre composant. Pour obtenir un mappage complet des options vers les collections de ressources, consultez [Ressources de service et ressources de découverte](/agent-registry/data-model#service-resources).

Pour ajouter votre point de terminaison à Agent Registry, créez une ressource Service à l'aide de la commande gcloud agent-registry services create et de l'option --endpoint-spec-type définie sur 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

Remplacez les éléments suivants :

  • ENDPOINT_NAME : nom que vous souhaitez attribuer à votre point de terminaison, par exemple my-external-api. Le nom doit comporter entre 4 et 63 caractères, et ne peut contenir que des lettres minuscules, des chiffres et des traits d'union.
  • PROJECT_ID : ID du projet.
  • REGION : région du registre.
  • DISPLAY_NAME : nom lisible par l'humain du point de terminaison, par exemple My External API.
  • ENDPOINT_URL : URL cible, par exemple https://api.example.com/v1/data.
  • PROTOCOL : liaison de protocole pour l'interface. Les valeurs valides sont http-json, grpc ou jsonrpc.

Une fois la ressource Service créée, Agent Registry génère automatiquement une ressource Endpoint en lecture seule que les agents et les orchestrateurs peuvent découvrir et utiliser.

Terraform

Le bloc de spécification que vous configurez détermine la collection de ressources à laquelle appartient votre composant. Pour obtenir un mappage complet des spécifications aux collections de ressources, consultez [Ressources de service et ressources de découverte](/agent-registry/data-model#service-resources).

Pour enregistrer un point de terminaison externe, configurez la ressource google_agent_registry_service avec le bloc 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
}

Remplacez les éléments suivants :

  • REGION : région du registre.
  • ENDPOINT_NAME : nom unique que vous souhaitez attribuer à votre point de terminaison, par exemple my-external-api. Le nom doit comporter entre 4 et 63 caractères, et ne peut contenir que des lettres minuscules, des chiffres et des traits d'union.
  • DISPLAY_NAME : nom lisible par l'humain du point de terminaison, par exemple My External API.
  • ENDPOINT_URL : URL cible, par exemple https://api.example.com/v1/data.
  • PROTOCOL : liaison de protocole pour l'interface. Les valeurs valides sont HTTP_JSON, GRPC ou JSONRPC.

Enregistrer un point de terminaison d'API Google composite

Dans une architecture multiprojet, un projet de gouvernance central héberge une infrastructure partagée telle que l'Agent Registry et l'Agent Gateway, et des projets Google Cloud distincts hébergent des instances de calcul d'agents.

Lorsque vous acheminez le trafic de l'agent via Agent Gateway en mode de sortie, le trafic réseau sortant est bloqué par défaut. Pour permettre aux agents de projets Google Cloud distincts de communiquer avec les APIGoogle Cloud essentielles, vous pouvez regrouper plusieurs interfaces d'API dans une seule ressource Service composite dans le projet de gouvernance central.

Le regroupement des interfaces dans un seul point de terminaison simplifie l'administration des règles en vous permettant de gérer une seule liaison de règle Identity-Aware Proxy (IAP) pour l'ensemble des API Google principales.

Pour enregistrer un point de terminaison d'API Google composite, procédez comme suit :

gcloud

Enregistrez le point de terminaison avec plusieurs URL d'interface dans le projet de gouvernance central à l'aide de la commande gcloud agent-registry services create :

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

Remplacez les éléments suivants :

  • SERVICE_NAME : identifiant du service, par exemple core-gapi-services. Le nom doit comporter entre 4 et 63 caractères, et ne peut contenir que des lettres minuscules, des chiffres et des traits d'union.
  • CENTRAL_PROJECT_ID : ID du projet de gouvernance central hébergeant Agent Registry et Agent Gateway.
  • REGION : région où se trouvent votre passerelle et votre registre.
  • DISPLAY_NAME : nom lisible par l'humain, par exemple Core Google APIs.
  • DESCRIPTION : brève description, par exemple Essential Google APIs for agent operations.
  • API_URL : URL de l'API Google principale, par exemple https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL : répétez l'option --interfaces pour chaque URL ou variante de Google APIs supplémentaire requise par vos agents, par exemple https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com, ou des variantes régionales et mTLS telles que https://telemetry.mtls.googleapis.com.

Terraform

Pour enregistrer le point de terminaison composite des API Google à l'aide de Terraform, définissez la ressource google_agent_registry_service avec plusieurs blocs 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"
  }
}

Remplacez les éléments suivants :

  • CENTRAL_PROJECT_ID : ID du projet de gouvernance central.
  • REGION : région du registre.
  • SERVICE_NAME : ID du service, par exemple core-gapi-services. Le nom doit comporter entre 4 et 63 caractères, et ne peut contenir que des lettres minuscules, des chiffres et des traits d'union.
  • DISPLAY_NAME : nom lisible par l'humain, par exemple Core Google APIs.
  • DESCRIPTION : description du point de terminaison.
  • API_URL : URL de l'API Google principale, par exemple https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL : répétez le bloc interfaces pour chaque URL d'API Google supplémentaire ou variante requise par vos agents, par exemple https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com ou des variantes régionales et mTLS telles que https://telemetry.mtls.googleapis.com.

Étapes suivantes