As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Pesquisar registros de registro

Como consumidor, você pode pesquisar os registros aprovados de um registro usando a API do SearchDiscoverableRegistryRecords plano de dados. A API aceita uma consulta de linguagem natural, aplica uma pesquisa híbrida que combina compreensão semântica com correspondência de palavras-chave e retorna resultados classificados limitados aos registros cuja revisão mais recente tem status Aprovada. Registros com status Rascunho, Aprovação pendente , Rejeitado ou Obsoleto não são retornados. Para navegar pelo catálogo sem uma consulta, use ListDiscoverableRegistryRecords e, BatchGetDiscoverableRegistryRecord em vez disso, consulte Procurar registros aprovados.

Você também pode invocar as APIs do plano de dados de descoberta por meio do endpoint MCP do registro () usando qualquer cliente. InvokeRegistryMcp MCP-compatible O endpoint expõe SearchDiscoverableRegistryRecordsListDiscoverableRegistryRecords, e BatchGetDiscoverableRegistryRecord como ferramentas MCP que você pode chamar diretamente.

Parâmetros da solicitação

Filtros de metadados

Operadores:$eq,$ne,$in. Lógico:$and,$or. Campos:name,recordType,recordVersion.

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

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

Console

AWS CLI (Registro com autorização de entrada baseada em IAM)

AWS SDK (registro com autorização de entrada baseada em IAM)

Cliente HTTP (Registro com autorização de entrada baseada em OAuth)

Primeiro, obtenha um token de portador:

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'

Em seguida, pesquise com o token do portador:

Consistência eventual em AWS Pesquisa no Registro de Agentes

AWS O Agent Registry usa um modelo eventualmente consistente para indexação de pesquisa. Quando você aprova um registro do registro ligando UpdateRegistryRecordStatus ou usando o console, o registro não aparece nem aparece InvokeRegistryMcp imediatamente. SearchDiscoverableRegistryRecords Normalmente, leva alguns segundos para que o registro aprovado seja indexado e se torne detectável, mas, em alguns casos, pode levar até alguns minutos.

Durante esse período, você pode observar o seguinte comportamento:

Somente os registros no status Aprovado são incluídos nos resultados detectáveis. Os registros nos status Rascunho, Aprovação Pendente, Rejeitado ou Obsoleto nunca são retornados pelas APIs detectáveis do plano de dados ou por. InvokeRegistryMcp Você pode verificar o status atual de um registro chamandoGetRegistryRecord, que sempre retorna a revisão mais recente, independentemente do estado da indexação.

Para lidar com a consistência eventual em seu aplicativo, recomendamos o seguinte:

Para obter orientação geral sobre como configurar o comportamento de novas tentativas em AWS SDKs, consulte Comportamento de novas tentativas no Guia de referência de AWS SDKs e ferramentas.

Como os atributos do registro afetam a relevância da pesquisa

AWS O Agent Registry usa pesquisa híbrida que combina compreensão semântica com correspondência de palavras-chave para retornar resultados relevantes. Se um registro que você espera encontrar não aparecer nos resultados da pesquisa, entender quais atributos do registro influenciam a pesquisa pode ajudar.

Quais atributos de registro são usados para pesquisa

Os seguintes atributos do seu registro de registro são usados para determinar a relevância da pesquisa:

Como as consultas de pesquisa são processadas

Quando você ligaSearchDiscoverableRegistryRecords, o AWS Agent Registry executa duas pesquisas em paralelo no mesmo conjunto de registros indexados e mescla os resultados:

Se você incluir filtros de metadados em sua solicitação, os filtros serão aplicados às duas pesquisas antes que os resultados sejam pontuados e classificados. Isso significa que os filtros reduzem o conjunto de candidatos no qual a pesquisa semântica e por palavra-chave opera, em vez de filtrar os resultados após a classificação.

Como os resultados são classificados

Os resultados da pesquisa semântica e de palavras-chave são combinados em uma única lista classificada e retornados em ordem de relevância, com o registro mais relevante primeiro. A posição final de cada resultado é determinada por sua relevância em ambas as pesquisas — um registro com alta classificação nos resultados semânticos e de palavras-chave aparecerá mais alto do que um registro com alta classificação em apenas uma. Na pesquisa por palavra-chave, o nome do registro tem a maior influência na classificação, seguido pela descrição e pelo conteúdo do descritor, que contribuem igualmente. Como os dois modos de pesquisa sempre são executados e contribuem para a classificação final, a forma como você escreve sua consulta afeta quais registros aparecem. As orientações a seguir podem ajudá-lo a obter melhores resultados, dependendo da sua intenção.

Escrevendo consultas de pesquisa eficazes

Quando você souber o nome ou o identificador exatos, use uma consulta curta e específica. A pesquisa por palavra-chave combina o texto exato com nomes de registros, descrições e conteúdo do descritor. Consultas curtas como “weather-api-v2" ou “pdf-processing” são eficazes para encontrar registros por nome.

Ao explorar por capacidade ou caso de uso, use uma descrição em linguagem natural do que você precisa. A pesquisa semântica entende a intenção conceitual, portanto, consultas como “encontrar uma ferramenta que possa reservar voos” ou “extrair dados estruturados de documentos PDF” podem corresponder a registros relevantes, mesmo que essas palavras exatas não apareçam nos metadados do registro.

Evite misturar restrições semelhantes a filtros com intenção descritiva na mesma consulta. Uma consulta como “encontrar todos os servidores MCP para previsões meteorológicas” envia a frase inteira por meio de pesquisa semântica e por palavra-chave. O componente semântico interpreta a frase completa como uma intenção conceitual, que pode revelar registros que estão conceitualmente relacionados, mas não correspondem ao atributo específico que você pretendia restringir. Em vez disso, use filtros de metadados para restrições baseadas em atributos e mantenha a consulta focada no tópico. Consulte Quando usar filtros de metadados versus texto de consulta.

Escrevendo registros detectáveis

Quando usar filtros de metadados versus texto de consulta

Use filtros de metadados quando sua intenção for restringir os resultados por meio de um atributo conhecido, como tipo de registro, nome ou versão. Não incorpore restrições semelhantes a filtros no próprio texto da consulta. Por exemplo, se você quiser encontrar todos os servidores MCP relacionados ao clima, use um filtro de metadados para o tipo de registro e uma consulta para o tópico:

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

Evite colocar restrições no texto da consulta, como “encontre todos os servidores MCP para previsões meteorológicas”. Como as consultas mais longas tendem para a correspondência semântica, as palavras “servidores MCP” são interpretadas como parte da intenção conceitual e não como um filtro exato. Isso pode fazer com que o componente semântico retorne registros conceitualmente relacionados à frase completa, mas que não correspondam ao atributo específico que você pretendia filtrar — por exemplo, retornar registros do agente sobre o clima junto com os registros do servidor MCP. O mesmo se aplica a qualquer restrição baseada em atributos. Se você quiser registros com um nome, versão ou tipo específico, use o filtro de metadados correspondente em vez de incluir esses termos na consulta.

Você pode filtrar nos seguintes campos:

Os filtros suportam operadores $eq (iguais), $ne (não iguais) e $in (correspondem a qualquer valor em uma lista) e podem ser combinados usando uma lógica. $and $or

Por exemplo, para pesquisar somente servidores MCP relacionados ao clima:

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

Para excluir um tipo de recurso específico:

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

Para combinar com qualquer uma das várias versões:

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

A pesquisa retorna somente registros aprovados

Somente os registros no status Aprovado aparecem nos resultados da pesquisa e por meio do endpoint MCP. Os registros nos status Rascunho, Aprovação Pendente, Rejeitado ou Obsoleto não são retornados. Se um registro aprovado recentemente não aparecer nos resultados, consulte Consistência eventual na pesquisa do AWS Agent Registry.