Búsqueda de registros

Parámetros de la solicitud

Filtros de metadatos

Operadores:$eq,$ne,$in. Lógico:$and,$or. Campos: nombre, tipo de descripción, versión.

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

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

Consola

AWS CLI (registro con autorización de entrada basada en IAM)

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

AWS SDK (registro con autorización de entrada basada en 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 con autorización de entrada basada en OAuth)

Primero obtén un 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'

Luego busca con la ficha de 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}'

Coherencia eventual en AWS Búsqueda en el registro de agentes

AWS Agent Registry utiliza un modelo eventualmente coherente para la indexación de búsquedas. Al aprobar un registro de registro mediante una llamada UpdateRegistryRecordStatus o a través de la consola, el registro no aparece SearchRegistryRecords o aparece InvokeRegistryMcp inmediatamente. Normalmente, el registro aprobado tarda unos segundos en indexarse y hacerse visible, pero en algunos casos puede tardar hasta unos minutos.

Durante este tiempo, es posible que observe el siguiente comportamiento:

Solo los registros con el estado Aprobado se incluyen en los resultados de la búsqueda. Los registros en estado Borrador, Pendiente de aprobación, Rechazado o Obsoleto nunca son devueltos por SearchRegistryRecords oInvokeRegistryMcp. Puede comprobar el estado actual de un registro mediante una llamadaGetRegistryRecord, que siempre devuelve la última revisión, independientemente del estado de indexación.

Para gestionar la posible coherencia de su solicitud, le recomendamos lo siguiente:

Para obtener información general sobre cómo configurar el comportamiento de reintento en AWS los SDK, consulta el artículo sobre el comportamiento de los reintentos en la Guía de referencia de los AWS SDK y las herramientas.

Cómo afectan los atributos de los registros a la relevancia de las búsquedas

AWS Agent Registry utiliza una búsqueda híbrida que combina la comprensión semántica con la coincidencia de palabras clave para obtener resultados relevantes. Si un registro que espera encontrar no aparece en los resultados de la búsqueda, puede ser útil comprender qué atributos del registro influyen en la búsqueda.

Qué atributos de registro se utilizan para la búsqueda

Los siguientes atributos del registro se utilizan para determinar la relevancia de la búsqueda:

Cómo se procesan las consultas de búsqueda

Cuando llamaSearchRegistryRecords, AWS Agent Registry ejecuta dos búsquedas en paralelo en el mismo conjunto de registros indexados y combina los resultados:

Si incluye filtros de metadatos en la solicitud, los filtros se aplican a ambas búsquedas antes de puntuar y clasificar los resultados. Esto significa que los filtros reducen el conjunto de candidatos en el que funcionan las búsquedas semánticas y por palabras clave, en lugar de filtrar los resultados después de clasificarlos.

¿Cómo se clasifican los resultados

Los resultados de las búsquedas semánticas y de palabras clave se combinan en una única lista de clasificación y se muestran por orden de relevancia, con el registro más relevante en primer lugar. La posición final de cada resultado viene determinada por su relevancia en ambas búsquedas: un registro que ocupe un lugar destacado tanto en los resultados semánticos como en los de palabras clave aparecerá por encima de un registro que ocupe un lugar destacado solo en una. En las búsquedas por palabras clave, el nombre del registro es el que más influye en la clasificación, seguido por la descripción y el contenido del descriptor, que contribuyen en igual medida. Como ambos modos de búsqueda se ejecutan siempre y contribuyen a la clasificación final, la forma en que escribas la consulta afecta a los registros que aparecen. La siguiente guía puede ayudarte a obtener mejores resultados en función de tu intención.

Redactar consultas de búsqueda eficaces

Cuando sepas el nombre o el identificador exactos, utiliza una consulta breve y específica. La búsqueda por palabra clave compara el texto exacto con los nombres de los registros, las descripciones y el contenido del descriptor. Las consultas breves, como «weather-api-v2" o «procesamiento de archivos PDF», son eficaces para buscar registros por nombre.

Cuando explore por capacidad o caso de uso, utilice una descripción en lenguaje natural de lo que necesita. La búsqueda semántica entiende la intención conceptual, por lo que consultas como «buscar una herramienta que pueda reservar vuelos» o «extraer datos estructurados de documentos PDF» pueden coincidir con los registros relevantes, incluso si esas palabras exactas no aparecen en los metadatos del registro.

Evita mezclar restricciones similares a las de un filtro con una intención descriptiva en la misma consulta. Una consulta como «busca todos los servidores MCP para obtener pronósticos meteorológicos» envía la oración completa mediante una búsqueda semántica y por palabra clave. El componente semántico interpreta la oración completa como una intención conceptual, que permite mostrar registros que están relacionados conceptualmente pero que no coinciden con el atributo específico que se pretendía restringir. En su lugar, utilice filtros de metadatos para las restricciones basadas en atributos y mantenga la consulta centrada en el tema. Consulte Cuándo usar filtros de metadatos en lugar de consultar texto.

Escribir registros identificables

Cuándo usar filtros de metadatos en lugar de texto de consulta

Use filtros de metadatos cuando su intención sea restringir los resultados por un atributo conocido, como el tipo de registro, el nombre o la versión. No incruste restricciones tipo filtro en el propio texto de la consulta. Por ejemplo, si desea buscar todos los servidores MCP relacionados con el clima, utilice un filtro de metadatos para el tipo de registro y una consulta para el tema:

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

Evite incluir una restricción en el texto de la consulta, por ejemplo, «busque todos los servidores MCP para las previsiones meteorológicas». Como las consultas más largas tienden a buscar coincidencias semánticas, las palabras «servidores MCP» se interpretan como parte de la intención conceptual y no como un filtro exacto. Esto puede provocar que el componente semántico devuelva registros relacionados conceptualmente con la oración completa, pero que no coincidan con el atributo específico por el que pretendía filtrar; por ejemplo, devuelva registros de agentes sobre el clima junto con los registros del servidor MCP. Lo mismo se aplica a cualquier restricción basada en atributos. Si desea registros con un nombre, versión o tipo específicos, utilice el filtro de metadatos correspondiente en lugar de incluir esos términos en la consulta.

Puede filtrar por los siguientes campos:

Los filtros admiten operadores $eq (iguales), $ne (no iguales) y $in (coinciden con cualquier valor de una lista) y se pueden combinar mediante $and la $or lógica.

Por ejemplo, para buscar únicamente servidores MCP relacionados con el clima:

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

Para excluir un tipo de recurso específico:

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

Para que coincida con alguna de las distintas versiones:

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

La búsqueda devuelve solo los registros aprobados

Solo los registros con el estado Aprobado aparecen en los resultados de búsqueda y en el punto final del MCP. No se devuelven los registros en estado Borrador, Pendiente de aprobación, Rechazado o Obsoleto. Si un registro aprobado recientemente no aparece en los resultados, consulte Coherencia eventual en la búsqueda en el Registro de AWS Agentes.