Suchen Sie nach Registrierungseinträgen

Anforderungsparameter

Metadatenfilter

Operatoren:$eq,$ne,$in. Logisch:$and,$or. Felder: Name, DescriptorType, Version.

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

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

Konsole

AWS CLI (Registrierung mit IAM-basierter eingehender Autorisierung)

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

AWS SDK (Registrierung mit IAM-basierter eingehender Autorisierung)

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']}")

HTTP-Client (Registrierung mit OAuth-basierter eingehender Autorisierung)

Besorgen Sie sich zunächst ein Inhaber-Token:

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'

Suchen Sie dann mit dem Inhaber-Token:

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}'

Eventuelle Konsistenz in AWS Suche in der Agentenregistrierung

AWS Agent Registry verwendet ein letztlich konsistentes Modell für die Suchindexierung. Wenn Sie einen Registrierungseintrag per Anruf UpdateRegistryRecordStatus oder über die Konsole genehmigen, wird der Eintrag nicht sofort in den InvokeRegistryMcp Ergebnissen angezeigt SearchRegistryRecords oder angezeigt. In der Regel dauert es einige Sekunden, bis der genehmigte Datensatz indexiert und auffindbar ist. In einigen Fällen kann es jedoch auch einige Minuten dauern.

Während dieser Zeit können Sie das folgende Verhalten beobachten:

Nur Datensätze mit dem Status Genehmigt sind in den Suchergebnissen enthalten. Datensätze mit dem Status „Entwurf“, „Genehmigung ausstehend“, „Abgelehnt“ oder „Veraltet“ werden niemals von SearchRegistryRecords oder zurückgegeben. InvokeRegistryMcp Sie können den aktuellen Status eines Datensatzes überprüfenGetRegistryRecord, indem Sie anrufen. Dabei wird unabhängig vom Indexierungsstatus immer die neueste Version zurückgegeben.

Um sicherzustellen, dass Ihre Anwendung letztendlich konsistent ist, empfehlen wir Folgendes:

Allgemeine Hinweise zur Konfiguration des Wiederholungsverhaltens in AWS SDKs finden Sie unter Wiederholungsverhalten im Referenzhandbuch für AWS SDKs und Tools.

Wie wirken sich Datensatzattribute auf die Suchrelevanz aus

AWS Agent Registry verwendet eine Hybridsuche, bei der semantisches Verständnis mit Stichwortabgleich kombiniert wird, um relevante Ergebnisse zurückzugeben. Wenn ein Datensatz, den Sie voraussichtlich finden werden, nicht in den Suchergebnissen erscheint, kann es hilfreich sein, zu verstehen, welche Datensatzattribute die Suche beeinflussen.

Welche Datensatzattribute werden für die Suche verwendet

Die folgenden Attribute aus Ihrem Registrierungseintrag werden verwendet, um die Suchrelevanz zu bestimmen:

Wie werden Suchanfragen verarbeitet

Wenn Sie anrufenSearchRegistryRecords, führt AWS Agent Registry zwei Suchvorgänge parallel für denselben Satz indizierter Datensätze durch und führt die Ergebnisse zusammen:

Wenn Sie Metadatenfilter in Ihre Anfrage aufnehmen, werden die Filter auf beide Suchanfragen angewendet, bevor die Ergebnisse bewertet und eingestuft werden. Das bedeutet, dass Filter die Kandidatenmenge reduzieren, auf der sowohl die semantische Suche als auch die Stichwortsuche basiert, anstatt die Ergebnisse nach dem Ranking zu filtern.

Wie werden die Ergebnisse eingestuft

Ergebnisse sowohl der semantischen Suche als auch der Stichwortsuche werden in einer einzigen Rangliste zusammengefasst und in der Reihenfolge ihrer Relevanz angezeigt, wobei der relevanteste Datensatz an erster Stelle steht. Die endgültige Position jedes Ergebnisses wird durch seine Relevanz für beide Suchanfragen bestimmt. Ein Datensatz, der sowohl in den semantischen Ergebnissen als auch in den Keyword-Ergebnissen einen hohen Rang einnimmt, wird höher angezeigt als ein Datensatz, der nur in einer Suche einen hohen Rang einnimmt. Bei der Stichwortsuche hat der Datensatzname den stärksten Einfluss auf das Ranking, gefolgt von der Beschreibung und dem Deskriptorinhalt, die zu gleichen Teilen beitragen. Da beide Suchmodi immer ausgeführt werden und zum endgültigen Ranking beitragen, wirkt sich die Art und Weise, wie Sie Ihre Abfrage schreiben, darauf aus, welche Datensätze angezeigt werden. Die folgenden Hinweise können Ihnen dabei helfen, je nach Ihrer Absicht bessere Ergebnisse zu erzielen.

Effektive Suchanfragen schreiben

Wenn Sie den genauen Namen oder die Kennung kennen, verwenden Sie eine kurze, spezifische Abfrage. Bei der Stichwortsuche wird exakter Text mit Datensatznamen, Beschreibungen und Deskriptorinhalten abgeglichen. Kurze Abfragen wie „weather-api-v2" oder „pdf-processing“ sind effektiv, um Datensätze anhand des Namens zu finden.

Verwenden Sie bei der Suche nach Funktionen oder Anwendungsfällen eine Beschreibung Ihrer Anforderungen in natürlicher Sprache. Die semantische Suche versteht die konzeptionelle Absicht, sodass Abfragen wie „Suchen Sie ein Tool, das Flüge buchen kann“ oder „Strukturierte Daten aus PDF-Dokumenten extrahieren“ mit relevanten Datensätzen übereinstimmen, auch wenn diese genauen Wörter nicht in den Datensatzmetadaten vorkommen.

Vermeiden Sie es, filterähnliche Einschränkungen mit beschreibender Absicht in derselben Abfrage zu vermischen. Bei einer Abfrage wie „Finde alle MCP-Server für Wettervorhersagen“ wird der gesamte Satz sowohl semantisch als auch anhand von Schlüsselwörtern durchsucht. Die semantische Komponente interpretiert den vollständigen Satz als konzeptionelle Absicht, wodurch Datensätze angezeigt werden können, die konzeptionell verwandt sind, aber nicht dem spezifischen Attribut entsprechen, das Sie einschränken wollten. Verwenden Sie stattdessen Metadatenfilter für attributbasierte Einschränkungen und konzentrieren Sie sich bei der Abfrage stets auf das Thema. Weitere Informationen finden Sie unter Wann sollten Metadatenfilter im Vergleich zu Abfragetext verwendet werden?

Datensätze schreiben, die auffindbar sind

Wann sollten Metadatenfilter anstelle von Abfragetext verwendet werden

Verwenden Sie Metadatenfilter, wenn Sie die Ergebnisse anhand eines bekannten Attributs wie Datensatztyp, Name oder Version einschränken möchten. Betten Sie filterähnliche Einschränkungen nicht in den Abfragetext selbst ein. Wenn Sie beispielsweise nach allen MCP-Servern suchen möchten, die sich auf das Wetter beziehen, verwenden Sie einen Metadatenfilter für den Datensatztyp und eine Abfrage für das Thema:

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

Vermeiden Sie es, die Einschränkung in den Abfragetext einzufügen, z. B. „Finde alle MCP-Server für Wettervorhersagen“. Da längere Abfragen eher auf semantischen Abgleich ausgerichtet sind, werden die Wörter „MCP-Server“ als Teil der konzeptionellen Absicht und nicht als exakter Filter interpretiert. Dies kann dazu führen, dass die semantische Komponente Datensätze zurückgibt, die konzeptionell mit dem ganzen Satz verwandt sind, aber nicht dem spezifischen Attribut entsprechen, nach dem Sie filtern wollten. Beispielsweise werden Agentendatensätze über Wetter zusammen mit MCP-Serverdatensätzen zurückgegeben. Das Gleiche gilt für jede attributbasierte Einschränkung. Wenn Sie Datensätze mit einem bestimmten Namen, einer bestimmten Version oder einem bestimmten Typ suchen, verwenden Sie den entsprechenden Metadatenfilter, anstatt diese Begriffe in die Abfrage aufzunehmen.

Sie können nach den folgenden Feldern filtern:

Filter unterstützen die Operatoren $eq (ist gleich), $ne (ungleich) und $in (entspricht jedem Wert in einer Liste) und können mithilfe $and von AND-Logik kombiniert werden. $or

Um beispielsweise nur nach wetterbedingten MCP-Servern zu suchen, gehen Sie wie folgt vor:

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

Um einen bestimmten Ressourcentyp auszuschließen:

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

Um eine von mehreren Versionen abzugleichen:

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

Die Suche gibt nur genehmigte Datensätze zurück

Nur Datensätze mit dem Status Genehmigt werden in den Suchergebnissen und über den MCP-Endpunkt angezeigt. Datensätze mit dem Status „Entwurf“, „Genehmigung ausstehend“, „Abgelehnt“ oder „Veraltet“ werden nicht zurückgegeben. Wenn ein kürzlich genehmigter Datensatz nicht in den Ergebnissen erscheint, finden Sie weitere Informationen unter Eventuelle Konsistenz bei der Suche in der AWS Agentenregistrierung.