Utiliser l'enregistrement manuel

Vous devez procéder à un enregistrement manuel dans Agent Registry pour les agents hébergés en dehors des environnements d'exécution compatibles ou exécutés sur ces environnements.Google Cloud 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 le rôle IAM Éditeur de l'API Agent Registry (roles/agentregistry.editor) 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 avec des rôles personnalisés ou d'autres rôles prédéfinis.

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 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 la zone géographique dans laquelle 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 , puis 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 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 à afficher lisible 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 la zone géographique dans laquelle 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 également 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.

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 doit afficher 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 à afficher lisible de l'agent.

Étape suivante