레지스트리 레코드 검색

요청 파라미터

메타데이터 필터

연산자: $eq , $ne , $in . 논리적: $and , $or . 필드: name, descriptorType, version.

예시: {"descriptorType": {"$eq": "MCP"}}

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

콘솔

AWS CLI(IAM 기반 인바운드 권한 부여를 사용한 등록)

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

AWS SDK(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']}")

HTTP 클라이언트(OAuth 기반 인바운드 권한 부여를 사용한 등록)

먼저 보유자 토큰을 얻습니다.

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'

그런 다음 보유자 토큰으로 검색합니다.

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

AWS 에이전트 레지스트리 검색의 최종 일관성

AWS 에이전트 레지스트리는 검색 인덱싱에 최종적으로 일관된 모델을 사용합니다. 를 호출UpdateRegistryRecordStatus하거나 콘솔을 통해 레지스트리 레코드를 승인하면 레코드가 SearchRegistryRecords 또는 InvokeRegistryMcp에 즉시 표시되지 않습니다. 일반적으로 승인된 레코드가 인덱싱되고 검색 가능하게 되는 데 몇 초가 걸리지만 경우에 따라 최대 몇 분이 걸릴 수 있습니다.

이 시간 동안 다음 동작을 관찰할 수 있습니다.

승인된 상태의 레코드만 검색 결과에 포함됩니다. 초안, 승인 보류 중, 거부됨 또는 사용 중단 상태의 레코드는 SearchRegistryRecords 또는 InvokeRegistryMcp에서 반환되지 않습니다. 를 호출하여 레코드의 현재 상태를 확인할 수 GetRegistryRecord 있습니다. 인덱싱 상태에 관계없이 항상 최신 개정을 반환합니다.

애플리케이션의 최종 일관성을 처리하려면 다음을 수행하는 것이 좋습니다.

AWS SDKs에서 재시도 동작을 구성하는 방법에 대한 일반적인 지침은 SDK 및 도구 참조 안내서의 재시도 동작을 참조하세요. AWS SDKs

레코드 속성이 검색 관련성에 미치는 영향

AWS 에이전트 레지스트리는 의미론적 이해와 키워드 일치를 결합하여 관련 결과를 반환하는 하이브리드 검색을 사용합니다. 찾을 것으로 예상되는 레코드가 검색 결과에 표시되지 않는 경우 검색에 영향을 미치는 레코드 속성을 이해하는 것이 도움이 될 수 있습니다.

검색에 사용되는 레코드 속성

레지스트리 레코드의 다음 속성은 검색 관련성을 결정하는 데 사용됩니다.

검색 쿼리 처리 방법

를 호출하면 AWS 에이전트 레지스트리는 동일한 SearchRegistryRecords 인덱싱된 레코드 세트에 대해 두 개의 검색을 병렬로 실행하고 결과를 병합합니다.

요청에 메타데이터 필터를 포함하면 결과가 채점되고 순위가 매겨지기 전에 필터가 두 검색에 모두 적용됩니다. 즉, 필터는 순위 지정 후 결과를 필터링하는 대신 의미 체계 검색과 키워드 검색이 모두 작동하는 후보 집합을 줄입니다.

결과 순위 지정 방법

의미 체계 검색과 키워드 검색의 결과는 하나의 순위 목록으로 결합되고 관련성 순서대로 반환되며 가장 관련성이 높은 레코드가 먼저 반환됩니다. 각 결과의 최종 위치는 두 검색 간의 관련성에 따라 결정됩니다. 의미와 키워드 결과 모두에서 순위가 높은 레코드는 하나에서만 순위가 높은 레코드보다 높게 나타납니다. 키워드 검색 내에서 레코드 이름은 순위에 가장 큰 영향을 미치며, 설명 및 설명자 콘텐츠가 그 뒤에 똑같이 기여합니다. 두 검색 모드 모두 항상 실행되고 최종 순위에 포함되므로 쿼리를 작성하는 방법은 레코드 표면에 영향을 미칩니다. 다음 지침은 의도에 따라 더 나은 결과를 얻는 데 도움이 될 수 있습니다.

효과적인 검색 쿼리 작성

정확한 이름 또는 식별자를 알고 있는 경우 짧은 특정 쿼리를 사용합니다. 키워드 검색은 레코드 이름, 설명 및 설명자 콘텐츠와 정확한 텍스트를 일치시킵니다. "™-api-v2" 또는 "pdf-processing"과 같은 짧은 쿼리는 이름으로 레코드를 찾는 데 효과적입니다.

기능 또는 사용 사례별로 탐색할 때는 필요한 사항에 대한 자연어 설명을 사용합니다. 의미 체계 검색은 개념적 의도를 이해하므로 "항공편을 예약할 수 있는 도구 찾기" 또는 "PDF 문서에서 구조화된 데이터 추출"과 같은 쿼리는 정확한 단어가 레코드 메타데이터에 표시되지 않더라도 관련 레코드와 일치할 수 있습니다.

동일한 쿼리에서 필터와 유사한 제약 조건을 설명 의도와 혼합하지 마십시오. "날씨 예측을 위한 모든 MCP 서버 찾기"와 같은 쿼리는 의미 체계 및 키워드 검색을 통해 전체 문장을 보냅니다. 의미 체계 구성 요소는 전체 문장을 개념적 의도로 해석합니다.이 의도는 개념적으로 관련이 있지만 제약하려는 특정 속성과 일치하지 않는 레코드를 표시할 수 있습니다. 대신 속성 기반 제약 조건에 메타데이터 필터를 사용하고 쿼리를 주제에 집중합니다. 메타데이터 필터와 쿼리 텍스트를 언제 사용해야 하는지를 참조하세요.

검색 가능한 레코드 작성

메타데이터 필터와 쿼리 텍스트를 사용해야 하는 경우

레코드 유형, 이름 또는 버전과 같은 알려진 속성으로 결과를 제한하려는 의도가 있는 경우 메타데이터 필터를 사용합니다. 쿼리 텍스트 자체에 필터와 유사한 제약 조건을 포함하지 마십시오. 예를 들어 날씨와 관련된 모든 MCP 서버를 찾으려면 레코드 유형에 메타데이터 필터를 사용하고 주제에 대한 쿼리를 사용합니다.

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

"날씨 예측을 위해 모든 MCP 서버 찾기"와 같은 쿼리 텍스트에 제약 조건을 넣지 마세요. 쿼리가 길수록 의미 체계 일치에 의존하기 때문에 "MCP 서버"라는 단어는 정확한 필터가 아닌 개념적 의도의 일부로 해석됩니다. 이로 인해 의미 체계 구성 요소가 개념적으로 전체 문장과 관련이 있지만 필터링하려는 특정 속성과 일치하지 않는 레코드를 반환할 수 있습니다. 예를 들어 MCP 서버 레코드와 함께 날씨에 대한 에이전트 레코드를 반환합니다. 속성 기반 제약 조건에도 동일하게 적용됩니다. 특정 이름, 버전 또는 유형의 레코드를 원하는 경우 쿼리에 해당 용어를 포함하지 않고 해당 메타데이터 필터를 사용합니다.

다음 필드를 기준으로 필터링할 수 있습니다.

필터는 $eq (같음), $ne (같지 않음) 및 $in (목록의 모든 값과 일치) 연산자를 지원하며 및 $and $or 로직을 사용하여 결합할 수 있습니다.

예를 들어 날씨 관련 MCP 서버만 검색하려면:

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

특정 리소스 유형을 제외하려면:

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

여러 버전 중 하나와 일치시키려면:

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

검색은 승인된 레코드만 반환합니다.

승인된 상태의 레코드만 검색 결과 및 MCP 엔드포인트를 통해 표시됩니다. 초안, 승인 보류 중, 거부됨 또는 사용 중단됨 상태의 레코드는 반환되지 않습니다. 최근에 승인된 레코드가 결과에 표시되지 않는 경우 AWS 에이전트 레지스트리 검색의 최종 일관성을 참조하세요.