Rechercher des agents, des outils et des compétences

À mesure que votre écosystème agentique se développe, il devient essentiel de trouver l'agent ou l'outil adapté. Agent Registry fournit des fonctionnalités de recherche qui vous permettent d'effectuer des recherches avancées par mot clé, par préfixe et sémantiques dans vos agents, leurs compétences et vos serveurs MCP (Model Context Protocol).

Ce document explique comment construire des requêtes de recherche pour découvrir les fonctionnalités de votre environnement.

Avant de commencer

Avant de rechercher des agents, des outils ou des compétences dans Agent Registry, enregistrez un agent ou un serveur MCP. Vous aurez également besoin de l'ID de votre projet pour effectuer ces tâches.

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

Rôles requis

Pour obtenir les autorisations nécessaires pour rechercher des agents, des outils et des compétences dans le registre d'agents, demandez à votre administrateur de vous accorder le rôle IAM Lecteur de l'API Agent Registry (roles/agentregistry.viewer) 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.

Rechercher des agents et des outils

Pour découvrir les fonctionnalités de votre registre, vous pouvez rechercher les agents et les serveurs MCP enregistrés.

La recherche d'agents correspond à leurs métadonnées de base, à leur description et aux compétences A2A descriptives déclarées en ligne dans leur carte d'agent. La recherche de serveurs MCP correspond à leur description et à leurs outils déterministes.

Vous pouvez effectuer une recherche par mot clé pour trouver des ressources correspondant à des termes spécifiques dans leurs capacités, comme la compétence A2A d'un agent ou l'outil d'un serveur MCP. Pour comprendre comment ces capacités sont structurées dans le registre, consultez Schémas JSON. Pour obtenir la liste complète des champs dans lesquels vous pouvez effectuer des recherches, consultez la documentation de référence de l'API.

Pour effectuer une recherche par mot clé, indiquez l'indicateur --search-string. Ce paramètre accepte les requêtes en texte libre et est compatible avec les opérateurs logiques : AND, OR et NOT.

Par exemple, recherchez un agent capable de gérer les réservations de vols :

gcloud agent-registry agents search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="flight OR booking"

Vous pouvez également rechercher un serveur MCP en fonction des outils spécifiques qu'il propose ou de sa description. Par exemple, recherchez un serveur MCP qui fournit des outils de base de données :

gcloud agent-registry mcp-servers search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="database"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet.
  • REGION : région du registre.

Les recherches par préfixe sont fortement optimisées pour la latence, ce qui permet à vos applications de récupérer dynamiquement les agents et les outils pertinents au fur et à mesure de la saisie de l'utilisateur.

Si vous créez une interface d'orchestrateur ou une fonctionnalité de saisie semi-automatique, vous pouvez effectuer des recherches par préfixe dans Agent Registry pour obtenir des résultats correspondant au début d'une chaîne de requête. Les recherches par préfixe utilisent le symbole générique de suffixe (*) pour faire correspondre le début d'un mot.

Par exemple, recherchez les agents dont le nom à afficher commence par un préfixe spécifique, tel que Best_A2A_* :

gcloud agent-registry agents search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="displayName:Best_A2A_*"

De même, vous pouvez rechercher des serveurs MCP dont le nom à afficher commence par un préfixe spécifique, tel que Prod_Server_* :

gcloud agent-registry mcp-servers search \
  --project=PROJECT_ID \
  --location=REGION \
  --search-string="displayName:Prod_Server_*"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet.
  • REGION : région du registre.

Rechercher des compétences autonomes

Vous pouvez rechercher des skills autonomes enregistrées dans Agent Registry. Cette fonctionnalité vous permet de découvrir des capacités réutilisables à associer à vos agents.

Lorsque vous recherchez des compétences, vous recherchez la révision de compétence par défaut. Pour mettre à jour la révision par défaut d'une skill, consultez Mettre à jour les métadonnées ou la révision par défaut d'une skill.

Modes de recherche

Vous pouvez utiliser deux modes de recherche pour les compétences, en fonction de vos besoins :

  • Recherche par mot clé : analyse uniquement les attributs de métadonnées de base tels que le nom à afficher, la description, le nom (URN) et l'ID de compétence. Ce mode est optimisé pour les recherches, les correspondances et la saisie semi-automatique de noms à faible latence. Pour obtenir un exemple, consultez Rechercher des compétences par mot clé ou expression.
  • Recherche sémantique : indexe automatiquement l'intégralité du contenu de la charge utile SKILL.md, y compris les instructions en langage naturel, la structure du code et les composants. Ce mode met en correspondance des thèmes conceptuels et est optimisé pour les agents orchestrateurs qui découvrent des ensembles de fonctionnalités pertinents de manière dynamique, en fonction de votre intention. Pour obtenir un exemple, consultez Rechercher des compétences par signification sémantique.

Champs et syntaxe de recherche

Lorsque vous effectuez une recherche par métadonnées ou chaînes de mots clés, les champs suivants sont indexés :

Nom du champ Comportement des demandes Recherche par préfixe Recherche dans tous les champs Description
displayName Non sensible à la casse Oui Oui Nom de la skill visible par l'utilisateur. Utilisez ce champ pour rechercher des noms communs.
description Non sensible à la casse Non Oui Description détaillée de l'objectif et des fonctionnalités de la compétence. Utilisez ce champ pour faire correspondre des mots clés.
name Non sensible à la casse Oui Oui Identifiant programmatique de la skill. Utilisez ce champ pour les correspondances sur les chaînes d'identifiants.
skillId Non sensible à la casse Oui Oui Nom de ressource uniforme (URN) logique de la compétence. Utilisez ce champ pour trouver les composants d'un éditeur spécifique. Par exemple, le format des skills créées par Google est urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID.
publisher Non sensible à la casse Oui Non Éditeur associé à la skill. Utilisez ce champ pour filtrer les résultats par organisation de publication.
frontmatter.name Non sensible à la casse Non Non Nom de la compétence défini dans le frontmatter du fichier SKILL.md.
frontmatter.description Non sensible à la casse Non Non Description de la compétence définie dans le frontmatter du fichier SKILL.md.
frontmatter.compatibility Non sensible à la casse Non Non Compatibilité de la skill définie dans le frontmatter du fichier SKILL.md.
frontmatter.license Non sensible à la casse Non Non Licence de la skill définie dans le fichier SKILL.md.
createTime Non applicable Non Non Code temporel de la création de la compétence. Ce champ n'est disponible que dans les filtres. Prend en charge les opérateurs de plage, tels que < et >, ainsi que les correspondances exactes.
updateTime Non applicable Non Non Code temporel de la dernière mise à jour de la skill. Ce champ n'est disponible que dans les filtres. Prend en charge les opérateurs de plage, tels que < et >, ainsi que les correspondances exactes.

Pour rechercher des compétences, fournissez une chaîne de requête à l'aide de l'indicateur --query dans gcloud CLI ou du paramètre searchString dans l'API REST. Vous pouvez utiliser les éléments de syntaxe suivants dans vos demandes de recherche :

  • Opérateurs booléens : incluez les opérateurs AND, OR ou NOT pour enchaîner les exigences.
  • Filtres spécifiques aux champs : ciblez un champ à l'aide de l'opérateur :, par exemple displayName:database.
  • Correspondance des préfixes : utilisez le caractère générique de suffixe (*) pour trouver les correspondances commençant par un préfixe spécifique, par exemple displayName:cloud-*.

Rechercher des compétences par mot clé ou expression

Par exemple, recherchez les compétences qui correspondent à un préfixe de nom à afficher et à un mot clé de description :

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="displayName:cloud-* AND description:database" \
  --search-type=keyword

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet
  • REGION : région du registre

Rechercher des compétences par signification sémantique

Par exemple, trouvez des compétences liées à la gestion des bases de données relationnelles à l'aide de la recherche sémantique :

gcloud alpha agent-registry skills search \
  --project=PROJECT_ID \
  --location=REGION \
  --query="manage and configure relational databases" \
  --search-type=semantic

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet
  • REGION : région du registre

Compétences publiques

Les skills publics fournis par Google sont mondiaux et détectables depuis n'importe quel projet. Pour obtenir la liste des compétences publiques disponibles, consultez le dépôt google/skills sur GitHub.

Lorsque vous effectuez une recherche, Agent Registry réécrit dynamiquement les noms de ressources des compétences publiques dans le résultat afin qu'elles apparaissent hébergées dans votre projet local. Ce processus simplifie l'intégration.