Pesquisar registros de registro

Parâmetros da solicitação

Filtros de metadados

Operadores:$eq,$ne,$in. Lógico:$and,$or. Campos: nome, tipo de descritor, versão.

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

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

Console

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

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

AWS SDK (registro com autorização de entrada baseada em 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']}")

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

Primeiro, obtenha uma ficha 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:

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

Consistência eventual em AWS Pesquisa de registro de agentes

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

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

Somente registros com status Aprovado são incluídos nos resultados da pesquisa. Registros com status Rascunho, Aprovação Pendente, Rejeitado ou Obsoleto nunca são retornados por ou. SearchRegistryRecords InvokeRegistryMcp Você pode verificar o status atual de um registro chamandoGetRegistryRecord, que sempre retorna a revisão mais recente, independentemente do estado de indexação.

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

Para obter orientação geral sobre como configurar o comportamento de repetição em AWS SDKs, consulte Comportamento de repetição 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ê ligaSearchRegistryRecords, o AWS Agent Registry executa duas pesquisas paralelamente 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 por palavra-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 nas duas 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 identificador exato, 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 recurso ou caso de uso, use uma descrição em linguagem natural do que você precisa. A pesquisa semântica compreende a intenção conceitual, então 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 “encontre todos os servidores MCP para previsões meteorológicas” envia a frase inteira por meio da pesquisa semântica e por palavra-chave. O componente semântico interpreta a frase completa como uma intenção conceitual, que pode revelar registros conceitualmente relacionados, mas que 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 em vez de texto de consulta.

Escrevendo registros detectáveis

Quando usar filtros de metadados em vez de texto de consulta

Use filtros de metadados quando sua intenção for restringir os resultados por 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": {
    "descriptorType": { "$eq": "MCP" }
  }
}

Evite colocar restrições no texto da consulta, como “encontre todos os servidores MCP para previsões meteorológicas”. Como consultas mais longas tendem à 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 correspondem 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": {
    "descriptorType": { "$eq": "MCP" }
  }
}

Para excluir um tipo de recurso específico:

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

Para corresponder a qualquer uma das várias versões:

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

A pesquisa retorna somente registros aprovados

Somente registros com status Aprovado aparecem nos resultados da pesquisa e por meio do endpoint MCP. Registros com 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.