Utiliser l'enregistrement manuel

Vous devez procéder à un enregistrement manuel dans Agent Registry pour les agents 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 Google Cloud projets. Ce document explique comment enregistrer manuellement des agents dans Agent Registry.

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 Agent Registry, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

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 via 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 carte d'agent de l'agent est accessible à l'aide d'URL publiques standards ou authentifié via des identifiants préconfigurés.

Enregistrer un agent compatible A2A

Si votre agent distant implémente la spécification Agent2Agent (A2A), dirigez Agent Registry 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

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

    Accéder à Agent Registry

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

  3. Sélectionnez l'onglet Agents.

  4. Cliquez sur Ajouter un agent.

  5. 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.

  6. Choisissez l'une des options suivantes :

    • Pour enregistrer l'agent à l'aide de son URI de ressource, sélectionnez l'onglet À partir de l'URI et saisissez une URL valide dans le champ URI. Cliquez ensuite sur Importer pour obtenir la carte d'agent à partir de l'URL.
    • Pour copier et coller le contenu de la carte d'agent, sélectionnez l'onglet Coller JSON et collez l'intégralité du contenu de votre fichier agent-card.json.

  7. Cliquez sur Enregistrer.

gcloud

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 que vous souhaitez attribuer à votre agent, par exemple Support Agent.

Terraform

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 votre charge utile JSON de 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 que vous souhaitez attribuer à votre agent, par exemple Support Agent.

Enregistrer un agent REST standard

Les agents REST standards peuvent être découverts par leur nom et leur description, mais ne disposent pas de compétences A2A pouvant faire l'objet d'une recherche, sauf s'ils adoptent le protocole A2A.

Si vous souhaitez enregistrer un agent distant qui n'implémente pas la spécification A2A, tel qu'un point de terminaison d'API REST ou SaaS standard, l'API Agent Registry crée une ressource Service sans spécification de protocole d'agent.

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

Console

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

    Accéder à Agent Registry

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

  3. Sélectionnez l'onglet Agents.

  4. Cliquez sur Ajouter un agent.

  5. 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 dans lequel vous souhaitez enregistrer l'agent.
    • Point de terminaison : saisissez le point de terminaison où l'agent est hébergé.

  6. Cliquez sur Enregistrer.

gcloud

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

Pour enregistrer un agent REST standard, procédez comme suit :

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 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 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 à partir d'un autre projet

Si votre organisation déploie des agents sur plusieurs Google Cloud projets et utilise une passerelle d'agent centrale pour régir le trafic sortant, vous pouvez enregistrer des agents à partir de projets spoke 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.

Considérations concernant l'enregistrement multiprojets

Avant d'enregistrer des agents sur plusieurs projets, examinez les points suivants :

  • Emplacements compatibles : l'instance Agent Registry, l'Agent Gateway et les points de terminaison de l'agent doivent résider dans la même région géographique ou dans l'emplacement global.
  • Limitation de la découverte automatique : la découverte automatique multiprojets n'est pas disponible. Vous devez enregistrer manuellement chaque agent distant.
  • Gestion du cycle de vie : les entrées manuelles dans Agent Registry 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 de sortie uniquement : la gouvernance multiprojets avec l'Agent Gateway n'est disponible que pour les passerelles Agent-to-Anywhere (sortie). Les passerelles d'entrée Client-to-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 à partir d'un autre projet, procédez comme suit :

Console

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

    Accéder à Agent Registry

  2. Dans le sélecteur de projets, sélectionnez le projet de gouvernance central Google Cloud dans lequel vous souhaitez enregistrer l'agent.

  3. Sélectionnez l'onglet Agents.

  4. Cliquez sur Ajouter un agent.

  5. 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.

  6. Fournissez 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 JSON et collez le contenu agent-card.json.
    • Pour les agents non A2A, saisissez l'URL du point de terminaison de l'agent distant.

  7. Cliquez sur Enregistrer.

gcloud

  • Agent A2A : pour enregistrer un agent A2A à partir d'un autre projet à l'aide de la gcloud CLI, 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=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 central.
  • REGION : région dans laquelle vous enregistrez l'agent.
  • DISPLAY_NAME: nom lisible 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 distant 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 central.
  • 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 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.

Vérifier l'enregistrement

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

Console

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

    Accéder à Agent Registry

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

  3. Sélectionnez l'onglet Agents.

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

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 l' identifiant unique global (URN), 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 lisible à afficher de l'agent.

Étape suivante