Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Utiliser l'enregistrement manuel

Vous devez enregistrer manuellement les agents dans le registre d'agents s'ils sont hébergés en dehors deGoogle Cloud, s'ils s'exécutent sur des runtimes non compatibles ou s'ils sont déployés dans différents projets Google Cloud . Ce document vous explique comment enregistrer manuellement des agents dans le Registre des agents.

Avertissement : Cette fonctionnalité 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

Avant de commencer, configurez Agent Registry. Vous avez besoin de l'ID du projet pour effectuer ces tâches.

Pour utiliser les commandes Google Cloud CLI de ce document, assurez-vous d'avoir configuré votre environnement gcloud CLI.

Rôles requis

Pour obtenir les autorisations nécessaires pour enregistrer manuellement des agents dans le registre d'agents, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

Pour enregistrer des agents dans Agent Registry : Éditeur de l'API Agent Registry (roles/agentregistry.editor)
Pour l'enregistrement inter-projets, afin d'accéder aux métadonnées de l'agent dans un projet distant : Lecteur de l'API Agent Registry (roles/agentregistry.viewer)

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.

Vous n'avez besoin d'aucune autorisation supplémentaire si le point de terminaison ou la fiche de l'agent sont accessibles à l'aide d'URL publiques standards ou authentifiés à l'aide d'identifiants préconfigurés.

Enregistrer un agent conforme à A2A

Si votre agent à distance implémente la spécification Agent2Agent (A2A), dirigez le registre d'agents vers la charge utile agent-card.json de l'agent. Le registre synchronise automatiquement la carte d'agent et indexe les compétences A2A disponibles de l'agent pour la découverte.

Pour enregistrer l'agent, procédez comme suit :

Console

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

Accéder au registre d'agents
Dans le sélecteur de projets, sélectionnez le projet Google Cloud dans lequel vous avez configuré Agent Registry.
Sélectionnez l'onglet Agents.
Cliquez sur Ajouter un agent.
Dans le panneau Détails de l'agent, saisissez les informations suivantes :
- Type : sélectionnez A2A.
- Région : sélectionnez l'emplacement géographique dans lequel vous souhaitez enregistrer l'agent.
Choisissez l'une des options suivantes :
- Pour enregistrer l'agent à l'aide de l'URL de sa carte d'agent, sélectionnez l'onglet À partir de l'URI et saisissez une URL valide dans le champ URI. Cliquez ensuite sur Importer pour obtenir la fiche de l'agent à partir de l'URL.
- Pour copier et coller le contenu de la fiche de l'agent, sélectionnez l'onglet Coller le JSON et collez l'intégralité du contenu de votre fichier agent-card.json.
Cliquez sur Enregistrer.

gcloud

Les indicateurs de spécification que vous utilisez déterminent la collection de ressources à laquelle appartient votre service. Pour obtenir un mappage complet des indicateurs aux collections de ressources, consultez Ressources d'API.

Pour enregistrer un agent A2A, enregistrez sa carte d'agent en tant que fichier JSON local (par exemple, agent-card.json), puis procédez comme suit :

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json

La taille maximale du fichier de spécification est de 10 Ko.

Remplacez les éléments suivants :

AGENT_NAME : nom que vous souhaitez attribuer à votre agent, par exemple my-support-agent.
PROJECT_ID : ID du projet.
REGION : région dans laquelle vous souhaitez enregistrer l'agent. Si vous ne souhaitez pas utiliser de région spécifique, utilisez la valeur global.
DISPLAY_NAME : nom lisible par l'humain que vous souhaitez attribuer à votre agent, par exemple Support Agent.

Terraform

Le bloc de spécification que vous configurez, par exemple agent_spec, détermine la collection de ressources à laquelle appartient votre service. Pour obtenir un mappage complet des spécifications aux collections de ressources, consultez Ressources d'API.

Pour enregistrer un agent conforme à A2A, configurez la ressource google_agent_registry_service. Spécifiez le bloc agent_spec avec le type A2A_AGENT_CARD et le content représentant la charge utile JSON de votre carte d'agent :

resource "google_agent_registry_service" "a2a_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"

  agent_spec {
    type    = "A2A_AGENT_CARD"
    content = jsonencode({
      schemaVersion = "v1"
      displayName   = "DISPLAY_NAME"
      description   = "A custom support agent registered using Terraform."
      skills = [
        {
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
        }
      ]
    })
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.a2a_agent.registry_resource
}

Remplacez les éléments suivants :

REGION : région dans laquelle vous enregistrez l'agent.
AGENT_NAME : nom unique que vous souhaitez attribuer à votre agent, par exemple my-support-agent.
DISPLAY_NAME : nom lisible par l'humain que vous souhaitez attribuer à votre agent, par exemple Support Agent.

Enregistrer un agent REST standard

Les agents REST standards sont découvrables par leur nom et leur description, mais ne disposent pas de compétences A2A pouvant être recherchées, sauf s'ils adoptent le protocole A2A.

Pour enregistrer un agent distant qui n'implémente pas la spécification A2A, créez une ressource Service configurée avec --agent-spec-type=no-spec. Le registre d'agents génère ensuite une ressource Agent correspondante dans la collection agents.

L'utilisation de --agent-spec-type=no-spec enregistre un agent, et non une destination d'API cible. Si vous souhaitez enregistrer une destination d'API externe à laquelle les agents se connectent, vous devez enregistrer un point de terminaison. Pour obtenir des instructions, consultez Enregistrer des points de terminaison.

Pour enregistrer l'agent, procédez comme suit :

Console

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

Accéder au registre d'agents
Dans le sélecteur de projets, sélectionnez le projet Google Cloud dans lequel vous avez configuré Agent Registry.
Sélectionnez l'onglet Agents.
Cliquez sur Ajouter un agent.
Dans le panneau Détails de l'agent, saisissez les informations suivantes :
- Type : sélectionnez Non-A2A.
- Nom : saisissez un nom à afficher lisible par l'humain pour votre agent, par exemple Travel Agent.
- Description : saisissez une description des capacités de l'agent, par exemple A test agent that plans travel itineraries..
- Région : sélectionnez l'emplacement géographique dans lequel vous souhaitez enregistrer l'agent.
- Point de terminaison : saisissez le point de terminaison où l'agent est hébergé.
Cliquez sur Enregistrer.

gcloud

Vous pouvez éventuellement fournir l'interface de point de terminaison HTTP/JSON définie avec l'indicateur --interfaces afin que le registre établisse une connexion avec l'agent.

Pour enregistrer un agent REST standard :

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

Remplacez les éléments suivants :

AGENT_NAME : nom que vous souhaitez attribuer à votre agent, par exemple my-remote-rest-agent.
PROJECT_ID : ID du projet.
REGION : région du registre.
DISPLAY_NAME : nom lisible par l'humain que vous souhaitez attribuer à votre agent, par exemple Remote REST Agent.
ENDPOINT_URL : URL du point de terminaison de l'API de l'agent, par exemple https://api.remote-service.com/v1/agents/1234.
PROTOCOL : liaison de protocole pour le point de terminaison. Les valeurs valides sont http-json, grpc ou jsonrpc.

Terraform

Pour enregistrer un agent REST standard, configurez la ressource google_agent_registry_service avec agent_spec défini sur le type NO_SPEC, puis définissez les connexions d'interface de point de terminaison :

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "A standard REST agent registered using Terraform."

  agent_spec {
    type = "NO_SPEC"
  }

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

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.rest_agent.registry_resource
}

Remplacez les éléments suivants :

REGION : région dans laquelle vous enregistrez l'agent.
AGENT_NAME : nom unique que vous souhaitez attribuer à votre agent, par exemple my-remote-rest-agent.
DISPLAY_NAME : nom lisible par l'humain que vous souhaitez attribuer à votre agent, par exemple Remote REST Agent.
ENDPOINT_URL : URL du point de terminaison de l'API de l'agent, par exemple https://api.remote-service.com/v1/agents/1234.
PROTOCOL : liaison de protocole pour le point de terminaison. Les valeurs valides sont HTTP_JSON, GRPC ou JSONRPC.

Enregistrer un agent provenant d'un autre projet

Si votre organisation déploie des agents dans plusieurs projets Google Cloudet utilise une Agent Gateway centrale pour régir le trafic de sortie, vous pouvez enregistrer les agents des projets spokes ou de charge de travail dans le catalogue central Agent Registry.

Étant donné que l'enregistrement automatique ne détecte que les ressources créées dans le même projet, vous devez enregistrer manuellement chaque agent distant dans le registre du projet de gouvernance central.

Points à prendre en compte pour l'enregistrement interprojets

Avant d'enregistrer des agents dans plusieurs projets, vérifiez les points suivants :

Emplacements compatibles : l'instance Agent Registry, la passerelle Agent Gateway et les points de terminaison de l'agent doivent se trouver dans la même région géographique ou dans l'emplacement global.
Limitation de la découverte automatique : la découverte multiprojet automatique n'est pas acceptée. Vous devez enregistrer manuellement chaque agent distant.
Gestion du cycle de vie : les entrées manuelles dans le registre d'agents ne sont pas automatiquement mises à jour ni supprimées lorsque des modifications sont apportées au projet distant. Vous devez gérer le cycle de vie de ces entrées dans le registre central lorsque des agents distants sont modifiés ou supprimés.
Mode sortie uniquement : la gouvernance interprojets avec Agent Gateway n'est compatible qu'avec les passerelles Agent-to-Anywhere (sortie). Les passerelles Ingress client-agent nécessitent que l'agent et la passerelle se trouvent dans le même projet.

Enregistrer l'agent distant

Pour enregistrer manuellement un agent provenant d'un autre projet, procédez comme suit :

Console

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

Accéder au registre d'agents
Dans le sélecteur de projets, sélectionnez le projet de gouvernance centralisée Google Clouddans lequel vous souhaitez enregistrer l'agent.
Sélectionnez l'onglet Agents.
Cliquez sur Ajouter un agent.
Dans le panneau Détails de l'agent, saisissez les informations suivantes :
- Type : sélectionnez A2A si l'agent distant implémente le protocole A2A, ou Non-A2A pour un point de terminaison REST standard.
- Région : sélectionnez la région correspondant au déploiement de votre passerelle centrale et de votre agent à distance.
Indiquez le point de terminaison de l'agent :
- Pour les agents A2A, sélectionnez À partir de l'URI et saisissez l'URL de la carte d'agent de l'agent distant, ou sélectionnez Coller le JSON et collez le contenu agent-card.json.
- Pour les agents non A2A, saisissez l'URL Endpoint de l'agent distant.
Cliquez sur Enregistrer.

gcloud

Agent A2A : pour enregistrer un agent A2A provenant d'un autre projet à l'aide de gcloud CLI, exécutez la commande suivante dans le projet de gouvernance centralisée :

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=@agent-card.json

Agent REST : pour enregistrer un agent REST standard à partir d'un autre projet, exécutez la commande suivante dans le projet de gouvernance central :

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=REMOTE_ENDPOINT_URL,protocolBinding=PROTOCOL

Remplacez les éléments suivants :

AGENT_NAME : nom de votre agent dans le registre central, par exemple remote-support-agent.
CENTRAL_PROJECT_ID : ID du projet de gouvernance centralisée.
REGION : région dans laquelle vous enregistrez l'agent.
DISPLAY_NAME : nom lisible par l'humain de l'agent, par exemple Remote Support Agent.
REMOTE_ENDPOINT_URL : URL du point de terminaison de l'agent s'exécutant dans le projet distant, par exemple https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app.
PROTOCOL : liaison de protocole pour le point de terminaison. Les valeurs valides sont http-json, grpc ou jsonrpc.

Terraform

Pour enregistrer un agent à distance dans un projet de gouvernance central à l'aide de Terraform, configurez la ressource google_agent_registry_service et spécifiez le projet central :

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project REMOTE_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

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

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.remote_agent.registry_resource
}

Remplacez les éléments suivants :

CENTRAL_PROJECT_ID : ID du projet de gouvernance centralisée.
REGION : région dans laquelle vous enregistrez l'agent.
AGENT_NAME : nom unique de votre agent dans le registre, par exemple remote-support-agent.
DISPLAY_NAME : nom lisible par l'humain de l'agent, par exemple Remote Support Agent.
REMOTE_PROJECT_ID : ID du projet dans lequel l'agent est hébergé.
REMOTE_ENDPOINT_URL : URL du point de terminaison de l'agent s'exécutant dans le projet distant.
PROTOCOL : liaison de protocole pour le point de terminaison. Les valeurs valides sont HTTP_JSON, GRPC ou JSONRPC.

Valider l'enregistrement

Après avoir enregistré votre agent, vérifiez que le registre d'agents a bien traité le Service et créé la ressource Agent correspondante :

Console

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

Accéder au registre d'agents
Dans le sélecteur de projets, sélectionnez le projet Google Cloud dans lequel vous avez configuré Agent Registry.
Sélectionnez l'onglet Agents.

La page affiche la liste de tous les agents enregistrés et leurs informations.

gcloud

gcloud agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

Si vous avez plusieurs agents ou si vous souhaitez confirmer l'enregistrement d'un seul agent, vous pouvez filtrer la liste par métadonnées de l'agent :

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

Remplacez les éléments suivants :

PROJECT_ID : ID du projet.
REGION : région dans laquelle vous souhaitez enregistrer l'agent. Si vous ne souhaitez pas utiliser de région spécifique, utilisez la valeur global.
FILTER_EXPRESSION : expression de filtre pour les agents que vous souhaitez filtrer. Par exemple, pour filtrer par nom à afficher, vous pouvez utiliser displayName='DISPLAY_NAME'. Pour filtrer par identifiant (URN) unique au niveau mondial, vous pouvez utiliser agentId='urn:agent:AGENT_URN'.

Terraform

Faites référence à votre agent enregistré dans d'autres configurations Terraform à l'aide de la source de données google_agent_registry_agent :

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  filter = "displayName=\"DISPLAY_NAME\""
}

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}

Remplacez les éléments suivants :

REGION : région du registre.
DISPLAY_NAME : nom à afficher de l'agent, lisible par l'humain.

Étapes suivantes

Découvrez comment gérer les agents enregistrés.
Découvrez l'enregistrement automatique, la méthode recommandée pour enregistrer les agents déployés dans des runtimes gérés.

Utiliser l'enregistrement manuel Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Avant de commencer

Rôles requis

Enregistrer un agent conforme à A2A

Console

gcloud

Terraform

Enregistrer un agent REST standard

Console

gcloud

Terraform

Enregistrer un agent provenant d'un autre projet

Points à prendre en compte pour l'enregistrement interprojets

Enregistrer l'agent distant

Console

gcloud

Terraform

Valider l'enregistrement

Console

gcloud

Terraform

Étapes suivantes

Utiliser l'enregistrement manuel