Gérer les agents

Agent Registry vous permet d'inspecter, de mettre à jour et de supprimer les agents enregistrés afin que votre registre reflète précisément les fonctionnalités actives de votre écosystème d'IA. Vous pouvez lister et afficher tous les agents enregistrés, mettre à jour les métadonnées ou le point de terminaison des agents enregistrés manuellement, et supprimer les agents qui ne sont plus utilisés.

Avant de commencer

  1. Configurer le registre d'agents.

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

  3. Enregistrez vos agents dans Agent Registry.

  4. 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 gérer les agents enregistrés 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.

Découvrir les agents disponibles

Après avoir enregistré des agents, vous pouvez les découvrir dans votre environnement et afficher leurs configurations détaillées, telles que leurs points de terminaison, leurs compétences A2A et les métadonnées associées.

Lister et afficher tous les agents

Vous pouvez lister tous les agents enregistrés dans votre environnement et afficher leurs configurations détaillées, telles que leurs points de terminaison, leurs compétences A2A et les métadonnées associées.

Si vous avez configuré un périmètre de gestion, vous pouvez lister les agents de plusieurs projets membres à partir de votre projet de gestion.

Pour lister les agents, procédez comme suit :

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

    La page affiche la liste de tous les agents enregistrés. La liste inclut le nom, l'identifiant, le type, la description, la version, l'environnement d'exécution et l'emplacement de l'agent.

  4. Pour afficher les détails complets d'un agent, cliquez sur son nom.

gcloud

Pour lister tous les agents d'un emplacement spécifique, exécutez la commande gcloud agent-registry agents list :

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

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet. Si vous avez configuré une limite de gestion, spécifiez l'ID de votre projet de gestion pour lister les agents de l'emplacement spécifié dans tous les projets membres de la limite. Chaque nom de ressource renvoyé conserve l'ID de l'agent et utilise le projet spécifié dans la requête.
  • REGION : emplacement du registre, par exemple us-central1, eu ou global. Dans un projet de gestion, la spécification d'un emplacement regroupe les agents de ce même emplacement dans tous les projets membres du périmètre.

Filtrer les agents enregistrés

Si vous disposez de plusieurs agents ou si vous souhaitez confirmer l'enregistrement d'un agent spécifique, vous pouvez filtrer la liste en fonction des métadonnées de l'agent :

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é le registre d'agents.

  3. Sélectionnez l'onglet Agents.

    La page affiche la liste de tous les agents enregistrés. La liste inclut le nom, l'identifiant, le type, la description, la version, l'environnement d'exécution et l'emplacement de l'agent.

  4. Filtrez la liste par emplacement, ressource d'exécution ou identifiant de l'agent :

    • Pour filtrer par emplacement, cliquez sur le menu Emplacement, sélectionnez les emplacements que vous souhaitez filtrer, puis cliquez sur Appliquer.
    • Pour filtrer par environnement d'exécution, cliquez sur le menu Environnement d'exécution, sélectionnez les environnements d'exécution que vous souhaitez filtrer, puis cliquez sur Appliquer.
    • Pour afficher ou masquer les agents Google créés par le système, cliquez sur Afficher les agents créés par le système ou Masquer les agents créés par le système dans la barre d'outils du tableau. Pour ne lister que les agents Google intégrés, cliquez sur Filtrer, saisissez urn:agent:googleapis.com: dans le champ ID de l'agent, puis cliquez sur Appliquer.

    La page affiche une liste filtrée des agents enregistrés pour les conditions sélectionnées.

gcloud

Filtrez votre liste d'agents pour ne renvoyer que les ressources correspondant à des métadonnées spécifiques en transmettant l'option --filter à la commande gcloud agent-registry agents list :

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 du registre.
  • FILTER_EXPRESSION : expression de filtre pour les agents que vous souhaitez filtrer. Par exemple, vous pouvez utiliser les filtres suivants :
    • Pour filtrer par nom à afficher, utilisez displayName='DISPLAY_NAME'.
    • Pour effectuer une recherche par identifiant d'agent unique (URN), utilisez agentId='urn:agent:AGENT_URN'.
    • Pour lister uniquement les agents Google intégrés, utilisez agentId:"urn:agent:googleapis.com:".
    • Pour filtrer par projet membre spécifique lors de l'interrogation d'un projet de gestion, utilisez agentId:"urn:agent:projects-MEMBER_PROJECT_NUMBER:".

Terraform

Pour récupérer un agent enregistré spécifique en filtrant ses métadonnées, configurez la source de données google_agent_registry_agent avec l'argument filter :

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

Remplacez les éléments suivants :

  • REGION : région du registre.
  • DISPLAY_NAME : nom lisible par l'humain de l'agent à utiliser pour le filtrage, par exemple Support Agent.

Afficher les détails d'un agent

Affichez les détails d'un agent spécifique, y compris ses protocoles, ses compétences A2A et son identité :

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é le registre d'agents.

  3. Sélectionnez l'onglet Agents.

    La page affiche la liste de tous les agents enregistrés. La liste inclut le nom, l'identifiant, le type, la description, la version, l'environnement d'exécution et l'emplacement de l'agent.

  4. Cliquez sur le nom de l'agent que vous souhaitez afficher.

    La page d'informations comprend des onglets pour les détails de l'agent.

  5. Cliquez sur l'onglet correspondant pour afficher les détails d'un agent spécifique.

    La disponibilité des fonctionnalités dépend de votre environnement d'exécution. Les onglets tels que Sessions, Playground, Mémoires et Évaluation sont des fonctionnalités spécifiques qui s'affichent pour les agents créés sur des environnements d'exécution gérés, tels que Agent Runtime sur Gemini Enterprise Agent Platform :

    • Aperçu : informations de base sur l'agent, y compris son nom, son identifiant, son emplacement, sa description et son environnement d'exécution. La vue d'ensemble affiche également les compétences A2A et la référence d'exécution, dont vous avez besoin pour créer des requêtes dans le graphique de topologie.
    • Observabilité : insights axés sur l'application, tels que la latence, le trafic, les erreurs et les dépenses en jetons. Cet onglet s'intègre aux outils Google Cloud Observability pour afficher des métriques de performances en temps réel et l'utilisation au niveau du système, afin de vous aider à gérer les coûts et l'expérience utilisateur. Pour en savoir plus, consultez la présentation de l'observabilité.
    • Traces : chemin exact d'une conversation étape par étape, y compris la mise en forme détaillée des messages d'entrée et de l'assistant pour déboguer les boucles de raisonnement multi-agents complexes ou les erreurs d'appel d'outil en temps réel. Pour en savoir plus, consultez Afficher les traces de l'agent.
    • Sécurité : résultats de Model Armor et de Security Command Center, y compris les cas de non-respect des règles relatives au contenu, les risques de fuite de données et les évaluations de la conformité. Pour en savoir plus sur la sécurité, consultez Afficher les résultats de sécurité.
    • Topologie : carte visuelle des relations et des flux de trafic entre un agent, l'Agent Gateway qui lui est attribuée et les serveurs MCP avec lesquels il interagit. Pour en savoir plus sur Agent Gateway, consultez la présentation d'Agent Gateway. Pour en savoir plus sur la topologie, consultez Afficher les graphiques d'un agent enregistré.
    • Identité : principal d'agent utilisé pour l'application des règles. Vous utilisez cette identité, par exemple, pour configurer des liaisons de fournisseur d'authentification pour l'authentification auprès des outils et des ressources.
    • Sessions : historique des conversations persistant et suivi des interactions actives avec l'agent.
    • Playground : interface de chat direct pour tester le comportement de l'agent.
    • Souvenirs : fonctionnalités de personnalisation à long terme qui génèrent ou rappellent des détails de conversations passées avec l'agent pour préserver le contexte entre les interactions.
    • Évaluation : détails de toutes les tâches d'évaluation des agents. Cet onglet vous permet de créer des tâches d'évaluation, d'importer des métriques et d'évaluer les performances cognitives de l'agent et la fiabilité du modèle par rapport au trafic réel ou à des simulations synthétiques.

gcloud

Pour afficher les métadonnées détaillées d'un agent spécifique, exécutez la commande gcloud agent-registry agents describe :

gcloud agent-registry agents describe AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION

Remplacez les éléments suivants :

  • AGENT_NAME : nom de votre agent, par exemple my-custom-agent.
  • PROJECT_ID : ID du projet. Dans une limite de gestion, vous pouvez spécifier l'ID du projet de gestion ou l'ID du projet membre dans lequel l'agent est déployé. Le nom de ressource renvoyé conserve l'ID de l'agent et utilise le projet spécifié dans votre requête.
  • REGION : région du registre.

Terraform

Pour récupérer des informations sur un agent enregistré spécifique à l'aide de son ID, configurez la source de données google_agent_registry_agent :

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  agent_id = "AGENT_ID"
}

output "agent_create_time" {
  description = "The timestamp when the agent was registered."
  value       = data.google_agent_registry_agent.my_agent.create_time
}

output "agent_update_time" {
  description = "The timestamp when the agent was last updated."
  value       = data.google_agent_registry_agent.my_agent.update_time
}

Remplacez les éléments suivants :

  • REGION : région du registre.
  • AGENT_ID : identifiant unique de votre agent, par exemple my-custom-agent.

Mettre à jour les métadonnées et les points de terminaison de l'agent

Si l'URL d'exécution de votre agent change, ou si vous souhaitez remplacer son nom à afficher, sa description ou sa spécification, vous pouvez mettre à jour les métadonnées de l'agent.

Dans Agent Registry, les ressources Agent sont des ressources de découverte en lecture seule. Pour mettre à jour un agent enregistré manuellement, vous devez mettre à jour directement sa ressource Service accessible en écriture en spécifiant l'ID du projet dans lequel cette ressource Service a été enregistrée. Pour les agents enregistrés automatiquement, mettez à jour l'agent dans son environnement d'exécution sous-jacent afin qu'Agent Registry synchronise les modifications.

Console

Mettez à jour les informations disponibles sur l'agent depuis la console Google Cloud  :

  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é le registre d'agents.

  3. Sélectionnez l'onglet Agents.

    La page affiche la liste de tous les agents enregistrés. La liste inclut le nom, l'identifiant, le type, la description, la version, l'environnement d'exécution et l'emplacement de l'agent.

  4. Cliquez sur le nom de l'agent que vous souhaitez mettre à jour.

  5. Dans l'onglet Aperçu de l'agent, cliquez sur  Modifier.

  6. Dans le panneau Modifier le service, saisissez les informations mises à jour de votre agent, telles que son nouveau nom ou sa nouvelle description.

  7. Cliquez sur Enregistrer.

gcloud

Exécutez la commande gcloud agent-registry services update avec des options spécifiques pour modifier les paramètres de l'agent :

  • Mettre à jour le nom à afficher et la description : utilisez les options --display-name et --description, par exemple :

    gcloud agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="New display name" \
    --description="Updated description of the agent's purpose."

    Remplacez les éléments suivants :

    • AGENT_NAME : nom de votre agent, par exemple my-support-agent.
    • PROJECT_ID : ID du projet.
    • REGION : région du registre.

  • Mettre à jour l'URL du point de terminaison : utilisez l'option --interfaces pour spécifier le nouveau point de terminaison, par exemple :

    gcloud agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

    Remplacez les éléments suivants :

    • AGENT_NAME : nom de votre agent, par exemple my-support-agent.
    • PROJECT_ID : ID du projet.
    • REGION : région du registre.
    • ENDPOINT_URL : URL du nouveau point de terminaison de l'agent, par exemple https://new-api.example.com/agent.
    • PROTOCOL : liaison de protocole pour le point de terminaison. Les valeurs valides sont http-json, grpc ou jsonrpc.

  • Mettre à jour la spécification de l'agent : utilisez l'option --agent-spec-content, par exemple si vous avez une nouvelle fiche d'agent :

    gcloud agent-registry services update AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --agent-spec-content=AGENT_SPEC_FILE

    Remplacez les éléments suivants :

    • AGENT_NAME : nom de votre agent, par exemple my-support-agent.
    • PROJECT_ID : ID du projet.
    • REGION : région du registre.
    • AGENT_SPEC_FILE : chemin d'accès au nouveau fichier de spécification de l'agent, par exemple new-agent-card.json. La taille maximale du fichier de spécification est de 10 Ko.

Terraform

Pour mettre à jour les métadonnées, l'URL du point de terminaison ou la spécification de votre agent enregistré, modifiez les paramètres de la ressource google_agent_registry_service existante dans votre configuration, puis exécutez terraform apply :

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "New Display Name"
  description  = "Updated description of the agent's purpose."

  agent_spec {
    type = "NO_SPEC"
  }

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

Remplacez les éléments suivants :

  • REGION : région du registre.
  • AGENT_NAME : nom unique que vous souhaitez attribuer à votre agent, par exemple my-support-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.

Supprimer un agent

Pour supprimer des agents qui ont été automatiquement enregistrés dans Agent Registry, vous devez supprimer l'agent sous-jacent dans son environnement d'exécution Google Cloud spécifique. L'agent est ensuite automatiquement supprimé du registre.

Pour supprimer un agent enregistré manuellement du registre, vous devez supprimer sa ressource Service en spécifiant l'ID du projet dans lequel cette ressource Service a été enregistrée. Cette action supprime l'agent des résultats de recherche et le rend introuvable pour les autres outils :

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é le registre d'agents.

  3. Sélectionnez l'onglet Agents.

    La page affiche la liste de tous les agents enregistrés. La liste inclut le nom, l'identifiant, le type, la description, la version, l'environnement d'exécution et l'emplacement de l'agent.

  4. Cliquez sur le nom de l'agent que vous souhaitez supprimer.

  5. Dans l'onglet Overview (Aperçu) de l'agent, cliquez sur Delete (Supprimer).

  6. Dans la boîte de dialogue de confirmation, saisissez DELETE pour confirmer l'action.

  7. Cliquez sur Supprimer.

gcloud

Exécutez la commande gcloud agent-registry services delete :

gcloud agent-registry services delete AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION

Remplacez les éléments suivants :

  • AGENT_NAME : nom de l'agent que vous souhaitez supprimer, par exemple my-support-agent.
  • PROJECT_ID : ID du projet.
  • REGION : région du registre.

Terraform

Supprimez la ressource google_agent_registry_service représentant l'agent de votre configuration Terraform, puis exécutez terraform apply.

Étapes suivantes