Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Rechercher des enregistrements de registre

En tant que consommateur, vous pouvez rechercher les enregistrements approuvés d'un registre à l'aide de l'API du SearchDiscoverableRegistryRecords plan de données. L'API accepte une requête en langage naturel, applique une recherche hybride combinant compréhension sémantique et correspondance de mots clés, et renvoie des résultats classés limités aux enregistrements dont la dernière révision a le statut Approuvé. Les enregistrements dont le statut est Brouillon , En attente d'approbation, Rejeté ou Obsolète ne sont pas renvoyés. Pour parcourir le catalogue sans effectuer de requête, utilisez ListDiscoverableRegistryRecords et à la BatchGetDiscoverableRegistryRecord place — voir Parcourir les enregistrements approuvés.

Vous pouvez également invoquer les API du plan de données de découverte via le point de terminaison MCP du registre (InvokeRegistryMcp) à l'aide de n'importe quel client. MCP-compatible Le point de terminaison expose SearchDiscoverableRegistryRecordsListDiscoverableRegistryRecords, et BatchGetDiscoverableRegistryRecord en tant qu'outils MCP que vous pouvez appeler directement.

Paramètres de demande

Filtres de métadonnées

Opérateurs :$eq,$ne,$in. Logique :$and,$or. Domaines :name,recordType,recordVersion.

Exemple : {"recordType": {"$eq": "MCP"}}

Combiné : {"$and": [{"recordType": {"$eq": "MCP"}}, {"recordVersion": {"$eq": "1.0"}}]}

Console

AWS CLI (registre avec autorisation entrante basée sur IAM)

AWS SDK (registre avec autorisation entrante basée sur IAM)

Client HTTP (registre avec autorisation entrante basée sur OAuth)

Procurez-vous d'abord un jeton porteur :

SECRET_HASH=$(echo -n "<username><appClientId>" | openssl dgst -sha256 -hmac "<appClientSecret>" -binary | base64)

aws cognito-idp initiate-auth \
  --client-id "<appClientId>" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME="<username>",PASSWORD='<password>',SECRET_HASH="$SECRET_HASH" \
  --region us-east-1 | jq -r '.AuthenticationResult.AccessToken'

Effectuez ensuite une recherche à l'aide du jeton porteur :

Cohérence éventuelle dans AWS Recherche dans le registre des agents

AWS Le registre des agents utilise un modèle finalement cohérent pour l'indexation des recherches. Lorsque vous approuvez un enregistrement de registre en appelant UpdateRegistryRecordStatus ou via la console, l'enregistrement n'apparaît pas SearchDiscoverableRegistryRecords ou InvokeRegistryMcp apparaît immédiatement. Il faut généralement quelques secondes pour que l'enregistrement approuvé soit indexé et devienne détectable, mais dans certains cas, cela peut prendre jusqu'à quelques minutes.

Pendant cette période, il est possible que vous observiez le comportement suivant :

Seuls les enregistrements dont le statut est Approuvé sont inclus dans les résultats détectables. Les enregistrements dont le statut est Brouillon, En attente d'approbation, Rejeté ou Obsolète ne sont jamais renvoyés par les API détectables ou par. InvokeRegistryMcp Vous pouvez vérifier l'état actuel d'un enregistrement en appelantGetRegistryRecord, qui renvoie toujours la dernière révision, quel que soit l'état d'indexation.

Pour garantir la cohérence éventuelle de votre candidature, nous vous recommandons ce qui suit :

Pour obtenir des conseils généraux sur la configuration du comportement des nouvelles tentatives dans AWS les SDK, consultez la section Comportement des nouvelles tentatives dans le Guide de référence des AWS kits de développement logiciel et des outils.

Comment les attributs des enregistrements influent sur la pertinence de la recherche

AWS Le registre des agents utilise une recherche hybride qui associe compréhension sémantique et correspondance de mots clés pour obtenir des résultats pertinents. Si un enregistrement que vous vous attendez à trouver n'apparaît pas dans les résultats de recherche, il peut être utile de comprendre quels attributs d'enregistrement influencent la recherche.

Quels attributs d'enregistrement sont utilisés pour la recherche

Les attributs suivants de votre enregistrement de registre sont utilisés pour déterminer la pertinence de la recherche :

Comment les requêtes de recherche sont traitées

Lorsque vous appelezSearchDiscoverableRegistryRecords, AWS Agent Registry effectue deux recherches en parallèle sur le même ensemble d'enregistrements indexés et fusionne les résultats :

Si vous incluez des filtres de métadonnées dans votre demande, les filtres sont appliqués aux deux recherches avant que les résultats ne soient évalués et classés. Cela signifie que les filtres réduisent l'ensemble de candidats sur lequel opèrent à la fois la recherche sémantique et la recherche par mot clé, au lieu de filtrer les résultats après le classement.

Comment sont classés les résultats

Les résultats de la recherche sémantique et de la recherche par mot clé sont combinés en une seule liste classée et renvoyés par ordre de pertinence, l'enregistrement le plus pertinent en premier. La position finale de chaque résultat est déterminée par sa pertinence dans les deux recherches : un enregistrement bien classé dans les résultats sémantiques et par mots clés apparaîtra plus haut qu'un enregistrement bien classé dans une seule recherche. Dans la recherche par mot clé, le nom de l'enregistrement a la plus grande influence sur le classement, suivi de la description et du contenu du descripteur, qui contribuent de manière égale. Étant donné que les deux modes de recherche fonctionnent toujours et contribuent au classement final, la façon dont vous rédigez votre requête influe sur les enregistrements qui apparaissent. Les conseils suivants peuvent vous aider à obtenir de meilleurs résultats en fonction de vos objectifs.

Rédaction de requêtes de recherche efficaces

Lorsque vous connaissez le nom ou l'identifiant exact, utilisez une requête courte et précise. La recherche par mot clé fait correspondre le texte exact aux noms des enregistrements, à leurs descriptions et au contenu des descripteurs. Les requêtes courtes telles que « weather-api-v2 » ou « pdf-processing » sont efficaces pour rechercher des enregistrements par leur nom.

Lorsque vous explorez par fonctionnalité ou par cas d'utilisation, utilisez une description en langage naturel de ce dont vous avez besoin. La recherche sémantique comprend l'intention conceptuelle, de sorte que des requêtes telles que « trouver un outil permettant de réserver des vols » ou « extraire des données structurées de documents PDF » peuvent correspondre à des enregistrements pertinents même si ces mots exacts n'apparaissent pas dans les métadonnées de l'enregistrement.

Évitez de mélanger des contraintes de type filtre avec une intention descriptive dans la même requête. Une requête telle que « Rechercher tous les serveurs MCP pour les prévisions météorologiques » envoie la phrase entière par le biais d'une recherche sémantique et par mot-clé. Le composant sémantique interprète la phrase complète comme une intention conceptuelle, ce qui peut faire apparaître des enregistrements qui sont liés conceptuellement mais ne correspondent pas à l'attribut spécifique que vous vouliez restreindre. Utilisez plutôt des filtres de métadonnées pour les contraintes basées sur les attributs et concentrez la requête sur le sujet. Consultez Quand utiliser les filtres de métadonnées par rapport au texte de requête.

Rédaction de documents détectables

Quand utiliser les filtres de métadonnées par rapport au texte de requête

Utilisez des filtres de métadonnées lorsque vous souhaitez limiter les résultats en fonction d'un attribut connu tel que le type d'enregistrement, le nom ou la version. N'intégrez pas de contraintes de type filtre dans le texte de la requête lui-même. Par exemple, si vous souhaitez rechercher tous les serveurs MCP liés à la météo, utilisez un filtre de métadonnées pour le type d'enregistrement et une requête pour le sujet :

{
  "searchQuery": "weather forecast",
  "filters": {
    "recordType": { "$eq": "MCP" }
  }
}

Évitez de mettre une contrainte dans le texte de la requête, comme « trouver tous les serveurs MCP pour les prévisions météorologiques ». Les requêtes plus longues étant orientées vers une correspondance sémantique, les termes « serveurs MCP » sont interprétés comme faisant partie de l'intention conceptuelle plutôt que comme un filtre exact. Cela peut amener le composant sémantique à renvoyer des enregistrements qui sont conceptuellement liés à la phrase complète mais qui ne correspondent pas à l'attribut spécifique sur lequel vous vouliez filtrer, par exemple, renvoyer des enregistrements d'agents sur la météo en même temps que des enregistrements de serveur MCP. Il en va de même pour toute contrainte basée sur des attributs. Si vous souhaitez des enregistrements portant un nom, une version ou un type spécifique, utilisez le filtre de métadonnées correspondant plutôt que d'inclure ces termes dans la requête.

Vous pouvez filtrer selon les champs suivants :

Les filtres prennent en charge les opérateurs $eq $ne (égal), (non égal) et $in (correspond à n'importe quelle valeur d'une liste) et peuvent être combinés à l'aide d'$andune $or logique.

Par exemple, pour rechercher uniquement des serveurs MCP liés à la météo :

{
  "searchQuery": "weather forecast",
  "filters": {
    "recordType": { "$eq": "MCP" }
  }
}

Pour exclure un type de ressource spécifique :

{
  "searchQuery": "<your query>",
  "filters": {
    "recordType": { "$ne": "CUSTOM" }
  }
}

Pour correspondre à l'une des versions suivantes :

{
  "filters": {
    "recordVersion": { "$in": ["1.0", "1.1", "2.0"] }
  }
}

La recherche ne renvoie que les enregistrements approuvés

Seuls les enregistrements dont le statut est Approuvé apparaissent dans les résultats de recherche et via le point de terminaison MCP. Les enregistrements dont le statut est Brouillon, En attente d'approbation, Rejeté ou Obsolète ne sont pas renvoyés. Si un enregistrement récemment approuvé n'apparaît pas dans les résultats, voir Cohérence éventuelle dans la recherche dans le registre des AWS agents.