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 pour les agents

Agent Registry vous permet d'enregistrer manuellement des agents REST standards et conformes à la norme A2A qui sont hébergés en dehors de Google Cloud, qui s'exécutent sur des environnements d'exécution non compatibles ou qui sont déployés sur différents projets Google Cloud . En créant une ressource Service pour ces agents, vous rendez leurs points de terminaison et leurs fonctionnalités détectables dans votre écosystème d'IA.

Le registre d'agents utilise un projet de gouvernance central Google Cloud. Dans ce document, le terme distant fait référence aux agents hébergés en dehors du projet de gouvernance ou de la limite de gestion, par exemple dans des projets Google Cloud distincts sans limite de gestion, des environnements sur site ou des clouds externes, ou s'exécutant sur des environnements d'exécution non compatibles. L'enregistrement automatique ne détecte que les ressources compatibles déployées dans le projet de gouvernance où Agent Registry est activé, ou dans plusieurs projets lorsque vous configurez une limite de gestion. Dans tous les autres cas, vous devez donc enregistrer manuellement les agents distants dans le registre du projet de gouvernance.

Types d'agents et limites

Vous pouvez enregistrer manuellement deux types d'agents :

Agents compatibles A2A : agents qui implémentent la spécification Agent2Agent (A2A) avec le type A2A_AGENT_CARD. Le registre analyse le point de terminaison de leur carte d'agent agent-card.json pour indexer leurs compétences A2A.
Agents REST standards : agents distants qui n'implémentent pas la spécification A2A et utilisent le type NO_SPEC, tels que les agents qui exposent un point de terminaison d'API REST.

L'enregistrement manuel 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

Configurer le registre d'agents.
Pour une configuration à projet unique, obtenez l'ID de projet du projet de gouvernance où le registre d'agents est activé. Si vous avez configuré une limite de gestion pour plusieurs projets, utilisez l'ID de votre projet de gestion pour la découverte et l'enregistrement à l'échelle de la limite, ou spécifiez l'ID d'un projet membre pour les opérations sur un seul projet.
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 manuellement des agents dans le registre d'agents, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet de gouvernance où le registre d'agents est activé :

Pour enregistrer des agents dans Agent Registry : Éditeur de l'API Agent Registry (roles/agentregistry.editor)
Pour l'enregistrement multiprojet, afin d'accéder aux métadonnées de l'agent dans un autre projet Google Cloud : 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 pas besoin d'autorisations supplémentaires si le point de terminaison de l'agent ou la fiche d'agent sont accessibles à l'aide d'URL publiques standards ou authentifiés via des identifiants préconfigurés.

Enregistrer un agent compatible A2A

Si votre agent distant implémente la spécification 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 qu'elles puissent être découvertes.

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é le registre d'agents.
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 où vous souhaitez enregistrer l'agent.
Choisissez l'une des options suivantes :
- Pour enregistrer l'agent à l'aide de l'URL de sa fiche d'agent, sélectionnez l'onglet À partir d'un URI, puis saisissez une URL valide dans le champ URI. Cliquez ensuite sur Importer pour obtenir la fiche d'agent à partir de l'URL.
- Pour copier et coller le contenu de la fiche d'agent, sélectionnez l'onglet Coller le code JSON et collez l'intégralité du contenu de votre fichier agent-card.json.
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 enregistrer un agent A2A, enregistrez la carte d'agent de l'agent en tant que fichier JSON local, par exemple agent-card.json, puis exécutez la commande gcloud agent-registry services create :

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 : ID que vous souhaitez attribuer à votre agent, par exemple my-support-agent. L'ID 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 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 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 agent compatible 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({
      name               = "AGENT_NAME"
      description        = "A custom support agent registered using Terraform."
      version            = "1.0.0"
      capabilities       = {}
      defaultInputModes  = ["text/plain"]
      defaultOutputModes = ["text/plain"]
      supportedInterfaces = [
        {
          url             = "https://api.example.com/v1/agents/support"
          protocolBinding = "JSONRPC"
          protocolVersion = "1.0"
        }
      ]
      skills = [
        {
          id          = "customer_lookup"
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
          tags        = ["support", "customer"]
        }
      ]
    })
  }
}

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 : identifiant unique que vous souhaitez attribuer à votre agent, par exemple my-support-agent. L'ID 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 que vous souhaitez attribuer à votre agent, par exemple Support Agent.

Enregistrer un agent REST standard

Les agents REST standards sont découvrables par nom et description, mais ne disposent pas de compétences A2A consultables, 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 non-A2A. Agent Registry génère une ressource Agent en lecture seule pour l'agent non-A2A dans la collection agents, y compris l'URL de son point de terminaison, afin que les orchestrateurs, les autres agents et Agent Gateway puissent découvrir l'agent et s'y connecter.

Définir le type d'agent sur Non-A2A dans la console Google Cloud ou utiliser l'option --agent-spec-type=no-spec dans les commandes gcloud CLI enregistre un agent IA. N'enregistrez pas cet agent séparément en tant que ressource Endpoint. N'enregistrez une ressource Endpoint que si vous souhaitez gérer les connexions de sortie de l'agent vers une API REST ou un service Web qui n'est pas un agent, comme une API de base de données, une API SaaS tierce ou des Google APIs. Pour savoir comment enregistrer des destinations d'API sans agent, 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é le registre d'agents.
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 lisible à afficher 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 où vous souhaitez enregistrer l'agent.
- Point de terminaison : saisissez le point de terminaison où l'agent est hébergé.
Cliquez sur Enregistrer.

gcloud

Pour enregistrer un agent REST standard et spécifier l'URL du point de terminaison où l'agent est hébergé, exécutez la commande gcloud agent-registry services create avec --agent-spec-type=no-spec et l'option --interfaces :

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 : ID que vous souhaitez attribuer à votre agent, par exemple my-remote-rest-agent. L'ID 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 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.example.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 de l'interface du 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 : identifiant unique que vous souhaitez attribuer à votre agent, par exemple my-remote-rest-agent. L'ID 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 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.example.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 d'un autre projet

Si vous configurez une limite de gestion, Agent Registry regroupe automatiquement les agents compatibles des projets membres dans votre projet de gestion. Si vous ne configurez pas de limite de gestion ou si l'agent distant s'exécute sur un environnement d'exécution non compatible, vous devez enregistrer manuellement chaque agent distant dans le registre du projet de gouvernance central où vous souhaitez le gérer.

Par exemple, si votre organisation déploie des agents sur plusieurs projetsGoogle Cloud et utilise une passerelle d'agent centrale en mode de sortie Agent-to-Anywhere pour gérer le trafic, vous pouvez enregistrer les agents de ces autres projets Google Cloud dans le registre du projet de gouvernance central. Pour en savoir plus sur cette architecture, consultez Exemples de modèles de déploiement.

Remarques concernant l'enregistrement multiprojet

Avant d'enregistrer manuellement des agents dans plusieurs projets, tenez compte des 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.
Découverte automatique entre projets : la découverte entre projets n'est possible automatiquement que lorsque vous configurez une limite de gestion. Pour les agents personnalisés ou enregistrés manuellement, vous devez créer la ressource Service dans le projet de gestion. Sans limite de gestion, vous ne pouvez découvrir que les ressources du projet dans lequel elles sont déployées.
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 se produisent dans l'autre projetGoogle Cloud où l'agent s'exécute. 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 de sortie Agent-to-Anywhere. Les passerelles d'entrée client-agent nécessitent que l'agent et la passerelle se trouvent dans le même projet.

Enregistrer un agent distant

Pour enregistrer manuellement un agent 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 dans 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 à votre passerelle centrale et au déploiement de l'agent distant.
Indiquez le point de terminaison de l'agent :
- Pour les agents A2A, sélectionnez À partir d'un URI et saisissez l'URL de la carte d'agent de l'agent distant, ou sélectionnez Coller le code JSON et collez le contenu agent-card.json.
- Pour les agents non A2A, saisissez l'URL du point de terminaison de l'agent distant.
Cliquez sur Enregistrer.

gcloud

Agent A2A : pour enregistrer un agent A2A d'un autre projet, exécutez la commande gcloud agent-registry services create :

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 d'un autre projet, exécutez la commande gcloud agent-registry services create :

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 : ID de votre agent dans le registre central, par exemple remote-support-agent. L'ID 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.
REGION : région dans laquelle vous enregistrez l'agent et où résident la passerelle centrale et l'agent distant, par exemple us-central1.
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 distant exécuté dans l'autre projet Google Cloud , par exemple https://remote-support-agent-abc123.us-central1.run.app ou https://api.example.com/v1/agents/support.
PROTOCOL : liaison de protocole pour le point de terminaison. Les valeurs valides sont http-json, grpc ou jsonrpc.

Terraform

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

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 AGENT_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 central.
REGION : région dans laquelle vous enregistrez l'agent et où résident la passerelle centrale et l'agent distant, par exemple us-central1.
AGENT_NAME : identifiant unique de votre agent dans le registre, par exemple remote-support-agent. L'ID 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 de l'agent, par exemple Remote Support Agent.
AGENT_PROJECT_ID : ID du projet Google Cloud distinct dans lequel l'agent distant est hébergé.
REMOTE_ENDPOINT_URL : URL du point de terminaison de l'agent distant exécuté dans l'autre projet Google Cloud , par exemple https://remote-support-agent-abc123.us-central1.run.app ou https://api.example.com/v1/agents/support.
PROTOCOL : liaison de protocole pour le point de terminaison. Les valeurs valides sont HTTP_JSON, GRPC ou JSONRPC.

Vérifier l'enregistrement

Après avoir enregistré votre agent, vérifiez qu'Agent Registry a bien traité la ressource Service et créé la ressource Agent en lecture seule 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é le registre d'agents.
Sélectionnez l'onglet Agents.

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

gcloud

Répertoriez les agents enregistrés dans votre registre à l'aide de la commande gcloud agent-registry agents list :

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 en fonction des 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 d'agent (URN) unique au monde, vous pouvez utiliser agentId='urn:agent:AGENT_URN'.

Terraform

Référencez 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 sur des environnements d'exécution gérés.

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

Types d'agents et limites

Avant de commencer

Rôles requis

Enregistrer un agent compatible A2A

Console

gcloud

Terraform

Enregistrer un agent REST standard

Console

gcloud

Terraform

Enregistrer un agent d'un autre projet

Remarques concernant l'enregistrement multiprojet

Enregistrer un agent distant

Console

gcloud

Terraform

Vérifier l'enregistrement

Console

gcloud

Terraform

Étapes suivantes

Utiliser l'enregistrement manuel pour les agents