Ricerca di record di registro

Parametri della richiesta

Filtri per metadati

Operatori:$eq,$ne,$in. Logico:$and,$or. Campi: nome, DescriptorType, versione.

Ad esempio: {"descriptorType": {"$eq": "MCP"}}

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

Console

AWS CLI (registro con autorizzazione in entrata basata su IAM)

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

AWS SDK (registro con autorizzazione in entrata basata su 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 (registro con autorizzazione in entrata basata su OAuth)

Per prima cosa procurati un token al portatore:

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'

Quindi cerca con il token bearer:

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

Eventuale coerenza in AWS Ricerca nel registro degli agenti

AWS Agent Registry utilizza un modello alla fine coerente per l'indicizzazione delle ricerche. Quando si approva un record di registro chiamando UpdateRegistryRecordStatus o tramite la console, il record non viene visualizzato SearchRegistryRecords né InvokeRegistryMcp risulta immediatamente. In genere sono necessari alcuni secondi prima che il record approvato venga indicizzato e reso individuabile, ma in alcuni casi possono essere necessari alcuni minuti.

Durante questo periodo, potresti osservare il seguente comportamento:

Nei risultati della ricerca sono inclusi solo i record con stato Approvato. I record con stato Bozza, In attesa di approvazione, Rifiutato o Obsoleto non vengono mai restituiti da o. SearchRegistryRecords InvokeRegistryMcp È possibile verificare lo stato corrente di un record chiamandoGetRegistryRecord, che restituisce sempre la revisione più recente indipendentemente dallo stato di indicizzazione.

Per gestire l'eventuale coerenza della tua applicazione, ti consigliamo quanto segue:

Per indicazioni generali sulla configurazione del comportamento di ripetizione dei tentativi negli AWS SDK, consulta il comportamento dei tentativi di ripetizione nella Guida di riferimento agli SDK e agli strumenti. AWS

In che modo gli attributi dei record influiscono sulla pertinenza della ricerca

AWS Agent Registry utilizza la ricerca ibrida che combina la comprensione semantica con la corrispondenza delle parole chiave per restituire risultati pertinenti. Se un record che prevedi di trovare non viene visualizzato nei risultati di ricerca, può essere utile capire quali attributi del record influenzano la ricerca.

Quali attributi di record vengono utilizzati per la ricerca

I seguenti attributi del record di registro vengono utilizzati per determinare la pertinenza della ricerca:

Come vengono elaborate le query di ricerca

Quando si chiamaSearchRegistryRecords, AWS Agent Registry esegue due ricerche in parallelo sullo stesso set di record indicizzati e unisce i risultati:

Se includi filtri per i metadati nella tua richiesta, i filtri vengono applicati a entrambe le ricerche prima che i risultati vengano valutati e classificati. Ciò significa che i filtri riducono il set di candidati su cui opera sia la ricerca semantica che quella per parole chiave, anziché filtrare i risultati dopo il posizionamento.

Come vengono classificati i risultati

I risultati della ricerca semantica e per parole chiave vengono combinati in un unico elenco classificato e restituiti in ordine di pertinenza, con il record più pertinente per primo. La posizione finale di ogni risultato è determinata dalla sua pertinenza in entrambe le ricerche: un record con un buon posizionamento sia nei risultati semantici che nelle parole chiave apparirà più in alto rispetto a un record con un punteggio elevato in una sola. Nella ricerca per parole chiave, il nome del record ha la maggiore influenza sul posizionamento, seguito dalla descrizione e dal contenuto del descrittore, che contribuiscono in egual misura. Poiché entrambe le modalità di ricerca vengono sempre eseguite e contribuiscono alla classifica finale, il modo in cui si scrive la query influisce sulla visualizzazione dei record. Le seguenti indicazioni possono aiutarti a ottenere risultati migliori a seconda delle tue intenzioni.

Scrivere query di ricerca efficaci

Quando conosci il nome o l'identificatore esatto, usa una query breve e specifica. La ricerca per parole chiave confronta il testo esatto con i nomi dei record, le descrizioni e il contenuto dei descrittori. Le query brevi come «weather-api-v2" o «pdf-processing» sono efficaci per trovare i record per nome.

Quando esplori per funzionalità o caso d'uso, usa una descrizione in linguaggio naturale di ciò di cui hai bisogno. La ricerca semantica comprende l'intento concettuale, quindi domande come «trova uno strumento in grado di prenotare voli» o «estrarre dati strutturati da documenti PDF» possono corrispondere ai record pertinenti anche se quelle parole esatte non compaiono nei metadati del record.

Evita di mescolare vincoli simili a filtri con intenti descrittivi nella stessa query. Una query come «trova tutti i server MCP per le previsioni meteorologiche» invia l'intera frase tramite la ricerca semantica e per parole chiave. La componente semantica interpreta l'intera frase come un intento concettuale, che può far emergere record concettualmente correlati ma che non corrispondono all'attributo specifico che intendevi vincolare. Utilizza invece filtri di metadati per i vincoli basati sugli attributi e mantieni la query incentrata sull'argomento. Vedi Quando utilizzare i filtri dei metadati rispetto al testo della query.

Scrittura di record rilevabili

Quando utilizzare i filtri per i metadati anziché il testo delle query

Utilizza i filtri per i metadati quando il tuo intento è vincolare i risultati in base a un attributo noto come il tipo di record, il nome o la versione. Non incorporate vincoli simili a filtri nel testo della query stessa. Ad esempio, se desideri trovare tutti i server MCP relativi alle condizioni meteorologiche, utilizza un filtro di metadati per il tipo di record e una query per l'argomento:

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

Evita di inserire un vincolo nel testo della query, ad esempio «trova tutti i server MCP per le previsioni meteorologiche». Poiché le interrogazioni più lunghe tendono alla corrispondenza semantica, le parole «server MCP» vengono interpretate come parte dell'intento concettuale piuttosto che come un filtro esatto. Ciò può far sì che il componente semantico restituisca record concettualmente correlati alla frase completa ma che non corrispondono all'attributo specifico in base al quale intendevi filtrare, ad esempio restituendo i record degli agenti sulle condizioni meteorologiche insieme ai record del server MCP. Lo stesso vale per qualsiasi vincolo basato sugli attributi. Se desideri record con un nome, una versione o un tipo specifici, utilizza il filtro dei metadati corrispondente anziché includere tali termini nella query.

Puoi filtrare in base ai seguenti campi:

I filtri supportano gli operatori $eq (uguale a), $ne (non uguale) e $in (corrisponde a qualsiasi valore in un elenco) e possono essere combinati utilizzando la logica and. $and $or

Ad esempio, per cercare solo server MCP relativi alle condizioni meteorologiche:

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

Per escludere un tipo di risorsa specifico:

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

Per abbinare una delle diverse versioni:

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

La ricerca restituisce solo i record approvati

Solo i record con stato Approvato vengono visualizzati nei risultati di ricerca e tramite l'endpoint MCP. I record con stato Bozza, In attesa di approvazione, Rifiutato o Obsoleto non vengono restituiti. Se un record approvato di recente non viene visualizzato nei risultati, vedere Eventuale coerenza nella ricerca nel registro degli agenti. AWS