Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Cerca i record del registro

In qualità di consumatore, puoi cercare i record approvati di un registro utilizzando l'API SearchDiscoverableRegistryRecords data-plane. L'API accetta una query in linguaggio naturale, applica la ricerca ibrida che combina la comprensione semantica con la corrispondenza delle parole chiave e restituisce risultati classificati limitatamente ai record la cui ultima revisione ha lo stato Approvato. I record con stato Bozza, In attesa di approvazione , Rifiutato o Obsoleto non vengono restituiti. Per sfogliare il catalogo senza una richiesta, utilizza BatchGetDiscoverableRegistryRecord invece ListDiscoverableRegistryRecords and: consulta Sfoglia i record approvati.

È inoltre possibile richiamare le API di discovery data-plane tramite l'endpoint MCP () del registro utilizzando qualsiasi client. InvokeRegistryMcp MCP-compatible L'endpoint espone e BatchGetDiscoverableRegistryRecord come strumenti SearchDiscoverableRegistryRecords MCP che ListDiscoverableRegistryRecords puoi chiamare direttamente.

Parametri della richiesta

Filtri per metadati

Operatori:$eq,,$ne. $in Logico:$and,$or. Campi:name,recordType,recordVersion.

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

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

Console

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

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

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 al portatore:

Eventuale coerenza in AWS Ricerca nel registro degli agenti

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

Durante questo periodo, potresti osservare il seguente comportamento:

Solo i record in stato Approvato sono inclusi nei risultati rilevabili. I record con stato Bozza, In attesa di approvazione, Rifiutato o Obsoleto non vengono mai restituiti dalle API del piano dati rilevabili o da. InvokeRegistryMcp È possibile verificare lo stato corrente di un record chiamandoGetRegistryRecord, che restituisce sempre l'ultima revisione indipendentemente dallo stato di indicizzazione.

Per garantire l'eventuale coerenza della domanda, consigliamo quanto segue:

Per indicazioni generali sulla configurazione del comportamento dei tentativi di ripetizione negli AWS SDK, consulta il comportamento dei tentativi nella Guida di riferimento per SDK and Tools. 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 dei 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 chiamaSearchDiscoverableRegistryRecords, 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 ciascun risultato è determinata dalla sua pertinenza in entrambe le ricerche: un record con un posizionamento elevato sia nei risultati semantici che nei risultati relativi alle parole chiave apparirà più alto di un record con un punteggio elevato solo in una. Nella ricerca per parole chiave, il nome del record ha la maggiore influenza sul posizionamento, seguito dalla descrizione e dal contenuto descrittivo, 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 linee guida possono aiutarti a ottenere risultati migliori in base alle tue intenzioni.

Scrivere query di ricerca efficaci

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

Quando esplori per funzionalità o caso d'uso, utilizza 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 dei 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 ricerca semantica e per parola chiave. La componente semantica interpreta l'intera frase come un intento concettuale, che può far emergere record correlati concettualmente 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 dei metadati rispetto al testo delle query

Utilizza i filtri per i metadati quando intendi 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": {
    "recordType": { "$eq": "MCP" }
  }
}

Evita di inserire vincoli nel testo della query, ad esempio «trova tutti i server MCP per le previsioni meteorologiche». Poiché le query 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 la componente semantica restituisca record concettualmente correlati alla frase completa ma che non corrispondono all'attributo specifico in base al quale intendevi filtrare, ad esempio, la restituzione dei record degli agenti relativi alle 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 di metadati corrispondente anziché includere tali termini nella query.

Puoi filtrare in base ai seguenti campi:

I filtri supportano gli operatori $eq (uguale), $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": {
    "recordType": { "$eq": "MCP" }
  }
}

Per escludere un tipo di risorsa specifico:

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

Per abbinare una qualsiasi delle diverse versioni:

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

La ricerca restituisce solo i record approvati

Solo i record con stato Approvato vengono visualizzati nei risultati della ricerca e tramite l'endpoint MCP. I record in stato Bozza, In attesa di approvazione, Rifiutato o Obsoleto non vengono restituiti. Se un record approvato di recente non viene visualizzato nei risultati, vedi Eventual consistency in AWS Agent Registry search.