Rechercher des agents, des outils et des compétences

Agent Registry vous permet d'effectuer des recherches parmi vos agents enregistrés, vos compétences Agent2Agent (A2A), vos compétences autonomes et vos serveurs MCP (Model Context Protocol) par mot clé, préfixe ou langage naturel dans la console Google Cloud , Google Cloud CLI ou l'API Agent Registry. Les recherches par mot clé et par préfixe vous aident à trouver rapidement des ressources par nom, identifiant ou métadonnées. La recherche sémantique trouve des fonctionnalités conceptuellement liées dans les instructions et les descriptions en langage naturel en fonction de l'intention.

Les requêtes de recherche évaluent les descriptions des capacités des agents, des serveurs MCP et des compétences, les schémas d'outils et les instructions de compétences. Vous ne pouvez pas utiliser de requêtes de recherche pour découvrir des points de terminaison. Pour savoir comment lister et filtrer les points de terminaison par métadonnées, consultez Découvrir des points de terminaison et filtrer des composants par métadonnées.

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 un agent, un serveur MCP ou une compétence 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 rechercher des agents, des outils et des compétences dans Agent Registry, demandez à votre administrateur de vous accorder le rôle IAM Lecteur de l'API Agent Registry (roles/agentregistry.viewer) sur le projet de gouvernance où Agent Registry 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.

Rechercher des agents et des outils

Pour découvrir les fonctionnalités de votre registre, vous pouvez rechercher des agents et des serveurs MCP enregistrés dans la console Google Cloud , la gcloud CLI ou l'API REST.

Lorsque vous recherchez des agents ou des serveurs MCP, vous pouvez effectuer une requête par nom à afficher, description ou mots clés de capacité :

• Agents : les requêtes de recherche vérifient le nom à afficher, la description et l'identifiant de l'agent, ainsi que les noms, descriptions et tags des compétences A2A intégrées déclarées dans sa fiche d'agent pour trouver une correspondance.
• Serveurs MCP : les requêtes de recherche vérifient le nom à afficher, la description, l'identifiant du serveur MCP, ainsi que les noms et descriptions de ses outils pour trouver une correspondance.

Rechercher par mots clés

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

Les requêtes par mot clé acceptent les chaînes de texte libre et sont compatibles avec les opérateurs logiques AND, OR et NOT :

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 votre projet Google Cloud .

3. Dans la barre Rechercher dans votre registre en haut de la page, saisissez une requête par mot clé d'au moins trois caractères, telle que flight ou database, ou un filtre de champ, tel que Name:booking, puis appuyez sur Enter.

   Le tableau Résultats de recherche affiche les agents, les serveurs MCP et les compétences autonomes correspondants dans les emplacements sélectionnés.

gcloud

Fournissez l'option --search-string à la commande gcloud agent-registry agents search ou gcloud agent-registry mcp-servers search.

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"

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 ou global.

REST

Envoyez une requête POST au point de terminaison agents:search ou mcpServers:search avec le champ searchString dans le corps de la requête.

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

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "flight OR booking"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

Recherchez un serveur MCP qui fournit des outils de base de données :

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "database"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/mcpServers:search"

Remplacez les éléments suivants :

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

Rechercher par préfixe

Les recherches par préfixe sont optimisées pour une faible latence, ce qui permet à vos applications de récupérer dynamiquement les agents et les outils pertinents à mesure qu'un utilisateur tape.

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 trouver des résultats commençant par une chaîne donnée. Les recherches de préfixe utilisent le caractère générique de suffixe * pour rechercher le début d'un mot :

gcloud

Exécutez la commande gcloud agent-registry agents search ou gcloud agent-registry mcp-servers search avec une expression de préfixe.

Par exemple, recherchez les agents dont le nom à afficher commence par Best_A2A_* :

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

De même, recherchez les serveurs MCP dont le nom à afficher commence par 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 ou global.

REST

Transmettez l'expression de préfixe dans le champ searchString du corps de la requête :

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"searchString": "displayName:Best_A2A_*"}' \
    "https://agentregistry.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/agents:search"

Remplacez les éléments suivants :

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

Rechercher au-delà d'une limite de gestion

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Si vous avez configuré une limite de gestion, vous pouvez rechercher des agents et des serveurs MCP dans un emplacement de tous les projets membres de cette limite à partir de votre projet de gestion :

gcloud agent-registry agents search \
    --project=MANAGEMENT_PROJECT_ID \
    --location=LOCATION \
    --search-string="analytics"

Remplacez les éléments suivants :

• MANAGEMENT_PROJECT_ID : ID de votre projet de gestion.
• LOCATION : emplacement à rechercher dans la limite de gestion, par exemple une région telle que us-central1, un emplacement multirégional tel que us ou eu, ou global. Le registre d'agents agrège les ressources situées au même emplacement dans le projet de gestion et tous les projets membres de la limite.

Pour limiter les résultats du projet de gestion à un projet membre spécifique, transmettez l'option --filter définie sur "project_id=MEMBER_PROJECT_ID". Pour effectuer une recherche exclusivement dans un seul projet membre sans cumul multiprojet, spécifiez l'ID de ce projet membre dans l'option --project.

Lorsque vous effectuez une recherche à partir du projet de gestion :

• Ressources agrégées détectées automatiquement : Agent Registry recherche les agents et les serveurs MCP détectés automatiquement à l'emplacement spécifié dans tous les projets membres de la limite de gestion, ainsi que toutes les ressources Service enregistrées créées à cet emplacement dans le projet de gestion.
• Noms de ressources limités à la requête : dans les résultats de recherche, le champ name de chaque ressource Agent ou McpServer renvoyée conserve l'ID du composant et utilise le projet spécifié dans l'URL de la requête.
• Ressources enregistrées au niveau du projet : les ressources Service enregistrées manuellement et les ressources Binding créées dans un projet membre restent limitées à ce projet membre et n'apparaissent pas dans les résultats de recherche du projet de gestion. Pour les rendre visibles au-delà de la limite de gestion, créez-les dans le projet de gestion.

Rechercher des compétences autonomes

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Vous pouvez rechercher des compétences autonomes enregistrées dans le registre d'agents. Cette fonctionnalité vous permet de découvrir des fonctionnalité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 compétence, consultez Mettre à jour les métadonnées ou la révision par défaut d'une compétence.

Modes de recherche

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

• Recherche par mot clé : n'analyse que les attributs de métadonnées de base, tels que le nom à afficher, la description, le nom de la ressource et l'identifiant de la compétence. Ce mode est optimisé pour les recherches à faible latence, les recherches exactes et la saisie semi-automatique des noms. 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, les scripts et les éléments de métadonnées. Ce mode identifie les thèmes conceptuels et est optimisé pour les agents d'orchestration qui découvrent des bundles 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 par chaînes de mots clés, les champs suivants sont indexés :

Nom du champ	Comportement de la casse	Recherche par préfixe	Recherche dans tous les champs	Description
displayName	Non sensible à la casse	Oui	Oui	Nom à afficher de la compétence. Utilisez ce champ pour rechercher des noms communs.
description	Non sensible à la casse	Non	Oui	Description détaillée de l'objectif et de la fonctionnalité de la compétence. Utilisez ce champ pour rechercher des mots clés.
name	Non sensible à la casse	Oui	Oui	Nom de ressource de la compétence. Utilisez ce champ pour effectuer une recherche par nom de ressource.
skillId	Non sensible à la casse	Oui	Oui	L'identifiant de compétence de la compétence. Utilisez ce champ pour trouver les assets d'un éditeur spécifique. Par exemple, le format des compétences gérées par Google est urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID.
publisher	Non sensible à la casse	Oui	Non	Éditeur associé à la compétence. Utilisez ce champ pour filtrer par organisation de publication.
frontmatter.name	Non sensible à la casse	Non	Non	Nom de la compétence défini dans le front matter du fichier SKILL.md.
frontmatter.description	Non sensible à la casse	Non	Non	Description de la compétence définie dans le front matter du fichier SKILL.md.
frontmatter.compatibility	Non sensible à la casse	Non	Non	La compatibilité de la compétence définie dans le front matter du fichier SKILL.md.
frontmatter.license	Non sensible à la casse	Non	Non	Licence de la compétence définie dans le front matter du 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 les correspondances exactes.
updateTime	Non applicable	Non	Non	Code temporel de la dernière mise à jour de la compétence. Ce champ n'est disponible que dans les filtres. Prend en charge les opérateurs de plage, tels que <, > et les correspondances exactes.

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

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

Rechercher des compétences par mot clé ou expression

Rechercher des compétences ayant un préfixe de nom à afficher et un mot clé de description spécifiques :

gcloud

Exécutez la commande gcloud alpha agent-registry skills search avec --search-type=keyword :

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 ou global.

REST

Envoyez une requête GET au point de terminaison skills:search avec searchString et searchType=KEYWORD :

curl -G -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "searchString=displayName:cloud-* AND description:database" \
    --data-urlencode "searchType=KEYWORD" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/REGION/skills:search"

Remplacez les éléments suivants :

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

Rechercher des compétences par signification sémantique

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

gcloud

Exécutez la commande gcloud alpha agent-registry skills search avec --search-type=semantic :

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 ou global.

REST

Envoyez une requête GET au point de terminaison skills:search avec searchString et searchType=SEMANTIC :

curl -G -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-urlencode "searchString=manage and configure relational databases" \
    --data-urlencode "searchType=SEMANTIC" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/REGION/skills:search"

Remplacez les éléments suivants :

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

compétences gérées par Google

Les compétences gérées par Google sont détectables à partir de n'importe quel projet. Pour obtenir la liste des compétences gérées par Google disponibles, consultez le dépôt google/skills sur GitHub.

Découvrir des points de terminaison et filtrer des composants par métadonnées

Vous pouvez également découvrir n'importe quel composant dans le registre d'agents, y compris les points de terminaison enregistrés, en listant sa collection et en filtrant sur les champs de métadonnées structurés :

• Découvrir des points de terminaison : étant donné que les ressources Endpoint ne sont pas compatibles avec les requêtes :search, vous les découvrez en parcourant l'onglet Points de terminaison dans la consoleGoogle Cloud , en exécutant gcloud agent-registry endpoints list --filter ou en appelant la méthode REST endpoints.list. Pour obtenir des instructions complètes, consultez Gérer et découvrir des points de terminaison.
• Filtrer les agents, les serveurs MCP et les compétences : lorsque vous connaissez l'identifiant de registre (URN), le nom à afficher ou l'attribut d'un composant, filtrez la collection dans la consoleGoogle Cloud ou transmettez --filter à gcloud agent-registry agents list, gcloud agent-registry mcp-servers list ou gcloud alpha agent-registry skills list. Pour en savoir plus, consultez Gérer les agents, Gérer les serveurs et les outils MCP et Gérer les compétences.