Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Búsqueda de registros

Como consumidor, puedes buscar en los registros aprobados de un registro mediante la API de SearchDiscoverableRegistryRecords plano de datos. La API acepta consultas en lenguaje natural, aplica una búsqueda híbrida que combina la comprensión semántica con la coincidencia de palabras clave, y arroja resultados clasificados limitados a los registros cuya última revisión tenga el estado Aprobada. No se devuelven los registros en estado de borrador , pendiente de aprobación, rechazado o obsoleto. Para explorar el catálogo sin realizar ninguna consulta, utilice ListDiscoverableRegistryRecords y, BatchGetDiscoverableRegistryRecord en su lugar, consulte Examinar los registros aprobados.

También puede invocar las API del plano de datos de descubrimiento a través del punto final MCP del registro (InvokeRegistryMcp) con cualquier cliente. MCP-compatible El punto final lo expone SearchDiscoverableRegistryRecords y BatchGetDiscoverableRegistryRecord como herramientas de MCP a las que puede llamar directamente. ListDiscoverableRegistryRecords

Parámetros de la solicitud

Filtros de metadatos

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

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

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

Consola

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

AWS SDK (registro con autorización entrante basada en IAM)

Cliente HTTP (registro con autorización entrante basada en OAuth)

Primero obtenga 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 del portador:

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

AWS El registro de agentes utiliza un modelo eventualmente coherente para la indexación de búsquedas. Cuando se aprueba un registro de registro mediante una llamada UpdateRegistryRecordStatus o a través de la consola, el registro no aparece ni se genera SearchDiscoverableRegistryRecords de forma inmediata. InvokeRegistryMcp Por lo general, el registro aprobado tarda unos segundos en indexarse y ser visible, pero en algunos casos puede tardar unos minutos.

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

Solo los registros con el estado Aprobado se incluyen en los resultados detectables. Los registros en estado de borrador, pendiente de aprobación, rechazado o obsoleto nunca son devueltos ni por las API del plano de datos detectables ni por InvokeRegistryMcp Puede verificar el estado actual de un registro mediante una llamadaGetRegistryRecord, que siempre devuelve la última revisión, independientemente del estado de indexación.

Para garantizar la coherencia eventual de tu aplicación, te recomendamos lo siguiente:

Para obtener instrucciones generales sobre cómo configurar el comportamiento de reintento en AWS los SDK, consulte el comportamiento de reintento en la Guía de referencia de herramientas y AWS SDK.

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 búsqueda, puede resultar útil saber qué atributos del registro influyen en la búsqueda.

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

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

Cómo se procesan las consultas de búsqueda

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

Si incluyes filtros de metadatos en tu 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 se basan las búsquedas semánticas y de palabras clave, en lugar de filtrar los resultados en función de la clasificación.

Cómo se clasifican los resultados

Los resultados de las búsquedas semánticas y de palabras clave se combinan en una sola 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á más alto que un registro que ocupe un lugar destacado solo en una. En la búsqueda 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 por igual. Como ambos modos de búsqueda siempre se ejecutan y contribuyen a la clasificación final, la forma en que escribes la consulta afecta a los registros que aparecen. La siguiente guía puede ayudarle a obtener mejores resultados en función de su intención.

Redacción de 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 de los descriptores. Las consultas breves como «weather-api-v2" o «pdf-processing» 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 «encuentra una herramienta que pueda reservar vuelos» o «extraer datos estructurados de documentos PDF» pueden hacer coincidir los registros pertinentes, 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 «buscar todos los servidores MCP para pronósticos meteorológicos» envía la oración completa a través de una búsqueda semántica y de palabras clave. El componente semántico interpreta la oración completa como una intención conceptual, lo que puede mostrar registros que están relacionados conceptualmente pero que no coinciden con el atributo específico que pretendía restringir. En su lugar, usa filtros de metadatos para las restricciones basadas en atributos y mantén la consulta centrada en el tema. Consulta Cuándo usar filtros de metadatos en lugar de texto de consulta.

Escribir registros detectables

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

Usa filtros de metadatos cuando tu intención sea restringir los resultados según un atributo conocido, como el tipo de registro, el nombre o la versión. No incruste restricciones similares a las de un 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": {
    "recordType": { "$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 que estén relacionados conceptualmente con la oración completa, pero que no coincidan con el atributo específico por el que pretendía filtrar (por ejemplo, devolver 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, una versión o un 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 $eq los operadores $ne (es igual a), $in (no es igual a) y (coincide con cualquier valor de una lista) y se pueden combinar mediante $and una $or lógica.

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

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

Para excluir un tipo de recurso específico:

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

Para que coincida con cualquiera de las varias versiones:

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

La búsqueda solo devuelve los registros aprobados

Solo los registros con el estado Aprobado aparecen en los resultados de la búsqueda y a través del punto final del MCP. No se devuelven los registros en estado de borrador, pendiente de aprobación, rechazado o obsoleto. Si un registro aprobado recientemente no aparece en los resultados, consulte Consistencia final en la búsqueda en el registro de AWS agentes.