Rechercher des enregistrements de registre

Paramètres de demande

Filtres de métadonnées

Opérateurs :$eq,$ne,$in. Logique :$and,$or. Champs : nom, type de descripteur, version.

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

Combiné : {"$and": [{"descriptorType": {"$eq": "MCP"}}, {"version": {"$eq": "1.0"}}]}

Console

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

aws bedrock-agentcore search-registry-records \
  --search-query "weather" \
  --registry-ids "<registryARN>" \
  --region us-east-1

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

import boto3

client = boto3.client('bedrock-agentcore')

response = client.search_registry_records(
    registryIds=['<registryARN>'],
    searchQuery='weather',
    maxResults=10
)
for record in response['registryRecords']:
    print(f"{record['name']} - {record['descriptorType']} - {record['status']}")

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

Obtenez 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 :

curl -X POST "https://bedrock-agentcore.<region>.amazonaws.com/registry-records/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"registryIds": ["<registryARN>"], "searchQuery": "weather", "maxResults": 10}'

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

AWS Agent Registry utilise un modèle finalement cohérent pour l'indexation des recherches. Lorsque vous approuvez un enregistrement de registre par appel UpdateRegistryRecordStatus ou par le biais de la console, l'enregistrement n'apparaît pas SearchRegistryRecords ou n'InvokeRegistryMcpapparaît pas immédiatement. Il faut généralement quelques secondes pour que l'enregistrement approuvé soit indexé et puisse être découvert, mais dans certains cas, cela peut prendre jusqu'à quelques minutes.

Pendant ce temps, il est possible que vous observiez le comportement suivant :

Seuls les enregistrements ayant le statut Approuvé sont inclus dans les résultats de recherche. Les enregistrements dont le statut est brouillon, en attente d'approbation, rejeté ou obsolète ne sont jamais renvoyés par SearchRegistryRecords ou. 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 une éventuelle cohérence dans votre application, nous vous recommandons ce qui suit :

Pour obtenir des conseils généraux sur la configuration du comportement de nouvelle tentative dans AWS les SDK, voir Comportement de nouvelle tentative dans le Guide de référence des AWS SDK et des outils.

Comment les attributs d'enregistrement affectent la pertinence de la recherche

AWS Agent Registry utilise une recherche hybride qui combine 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 appelezSearchRegistryRecords, AWS Agent Registry exécute 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 notés et classés. Cela signifie que les filtres réduisent l'ensemble de candidats sur lequel s'appuient à la fois la sémantique et la recherche par mots clés, plutôt que de filtrer les résultats après le classement.

Comment les résultats sont classés

Les résultats issus de la recherche sémantique et de la recherche par mot clé sont combinés dans une seule liste classée et renvoyés par ordre de pertinence, l'enregistrement le plus pertinent étant 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 le cadre de 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 y contribuent de manière égale. Comme 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 intentions.

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, aux 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 capable 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 des enregistrements.

Évitez de mélanger des contraintes de type filtre avec une intention descriptive dans la même requête. Une requête telle que « trouver tous les serveurs MCP pour les prévisions météorologiques » envoie la phrase complète par le biais d'une recherche sémantique et d'une recherche 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 liés au concept mais ne correspondant 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 la section Quand utiliser des filtres de métadonnées plutôt que du texte de requête.

Rédaction d'enregistrements détectables

Quand utiliser des filtres de métadonnées plutôt que du texte de requête

Utilisez des filtres de métadonnées lorsque vous souhaitez restreindre 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": {
    "descriptorType": { "$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 axées sur la correspondance sémantique, les mots « 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 de l'agent sur la météo aux côtés des enregistrements du serveur MCP. Il en va de même pour toute contrainte basée sur les 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 sur 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 $and de $or la logique.

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

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

Pour exclure un type de ressource spécifique, procédez comme suit :

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

Pour correspondre à l'une des différentes versions :

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

La recherche ne renvoie que les enregistrements approuvés

Seuls les enregistrements ayant le statut 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.