View a markdown version of this page

搜尋登錄檔記錄 - Amazon Bedrock AgentCore
請求參數中繼資料篩選條件主控台AWS CLI （使用 IAM 型傳入授權註冊）AWS SDK （使用 IAM 型傳入授權註冊）HTTP 用戶端 （以 OAuth 為基礎的傳入授權註冊）AWS 客服人員登錄檔搜尋中的最終一致性記錄屬性如何影響搜尋相關性

搜尋登錄檔記錄

即將進行的命名空間遷移

AWS 客服人員登錄檔目前在 bedrock-agentcore 命名空間下為公開預覽。從 2026 年 8 月 6 日開始，服務會移至代理程式登錄命名空間。如果您使用 AWS 代理程式登錄檔，則必須更新端點、IAM 政策、SDK 用戶端、CLI 指令碼和登錄檔資料。如需從公有預覽遷移的詳細資訊，請參閱 綜合登錄遷移指南。

請求參數

  • searchQuery （必要）：可以是 1-256 個字元的任何自然語言查詢

  • registryIds （必要）：在哪個登錄檔中執行搜尋。僅支援一個登錄 ARN 或 ID

  • maxResults （選用）：搜尋回應中傳回多少筆記錄。可以採用介於 1–20 和預設值為 10 之間的任何值

  • 篩選條件 （選用） — 中繼資料篩選條件表達式

中繼資料篩選條件

運算子：$eq、$ne、$in。邏輯：$and、$or。欄位：名稱、descriptorType、版本。

範例：{"descriptorType": {"$eq": "MCP"}}

合併： {"$and": [{"descriptorType": {"$eq": "MCP"}}, {"version": {"$eq": "1.0"}}]}

主控台

  1. 開啟登錄檔詳細資訊頁面。

  2. 選擇搜尋記錄索引標籤。

  3. 輸入您的搜尋查詢並檢視結果。

注意

主控台搜尋僅適用於 IAM 授權的登錄檔。對於 JWT 授權的登錄檔，請直接使用搜尋 API 搭配 HTTP 用戶端 （例如 curl ) 和有效的 JWT 承載字符，或透過 MCP 用戶端使用登錄檔的 MCP 端點。

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 查詢不會傳回剛核准的記錄。

  • 登錄檔 MCP InvokeRegistryMcp 端點 () 不會在工具結果中包含最近核准的記錄。

只有處於核准狀態的記錄才會包含在搜尋結果中。SearchRegistryRecords 或 永遠不會傳回草稿、待核准、已拒絕或已棄用狀態的記錄InvokeRegistryMcp。您可以呼叫 GetRegistryRecord 來驗證記錄的目前狀態，無論索引狀態為何，它一律會傳回最新的修訂版。

若要處理應用程式中的最終一致性，建議您執行下列動作：

  • 核准記錄後，使用包含指數退避的重試策略呼叫 SearchRegistryRecords ，確認它是可探索的。

  • 如果記錄未在核准後立即出現在搜尋結果中，請勿假設該記錄在登錄檔中遺失。呼叫 GetRegistryRecord 以驗證記錄的狀態。

  • 如果您要透過 Amazon EventBridge 和 UpdateRegistryRecordStatus 整合核准工作流程，請在下游系統查詢新核准記錄的搜尋 API 之前新增短暫延遲。

如需設定重試行為 AWS SDKs的一般指引，請參閱 AWS SDKs和工具參考指南中的重試行為。

記錄屬性如何影響搜尋相關性

AWS 客服人員登錄檔使用混合式搜尋，結合語意理解與關鍵字比對，以傳回相關結果。如果您預期找到的記錄未出現在搜尋結果中，請了解哪些記錄屬性會影響搜尋。

用於搜尋的記錄屬性

您的登錄檔記錄中的下列屬性用於判斷搜尋相關性：

  • 名稱 — 用於關鍵字比對。清楚的描述性名稱，反映資源所做的功能，可改善確切和部分名稱查詢的可探索性。

  • 描述 — 用於關鍵字和語意比對。以自然語言撰寫的描述，說明資源的用途和常見使用案例比繁複的技術標籤更容易探索。

  • 描述項 — 通訊協定定義 (MCP 伺服器定義、代理程式卡、技能文件或自訂 JSON) 的完整內容用於語意比對。這包括工具名稱、工具描述、輸入參數名稱和功能摘要。

  • 版本和描述項類型 — 可作為可篩選欄位使用。消費者可以在 name 、 descriptorType 和 上使用中繼資料篩選條件來縮小結果version。

如何處理搜尋查詢

當您呼叫 SearchRegistryRecords 時， AWS 代理登錄檔會對同一組索引記錄平行執行兩個搜尋，並合併結果：

  • 語意搜尋 — 您的查詢會轉換為向量表示法，並與索引記錄的向量表示法進行比較。即使查詢中的確切字詞未出現在記錄中，這仍會尋找概念相關的記錄。例如，「預訂航班」的查詢可以比對名為「travel-reservation-service」的記錄。

  • 關鍵字搜尋：您的查詢會與使用傳統關鍵字相關性的記錄欄位文字內容相符。這對於確切的名稱查詢和特定的技術術語有效。例如，「weather-api-v2」的查詢符合包含該確切文字的記錄。

如果您在請求中包含中繼資料篩選條件，則在對結果進行評分和排名之前，篩選條件會套用到兩個搜尋。這表示篩選條件會減少語意搜尋和關鍵字搜尋操作的候選集，而不是在排名後篩選結果。

如何排名結果

語意和關鍵字搜尋的結果會合併為單一排名清單，並依相關性順序傳回，最相關的記錄優先。每個結果的最終位置取決於其在兩個搜尋之間的相關性 — 在語意和關鍵字結果中排名較高的記錄，會比僅在一個結果中排名較高的記錄來得高。在關鍵字搜尋中，記錄名稱對排名的影響最大，其次是描述和描述項內容，貢獻相等。由於這兩種搜尋模式一律會執行並有助於最終排名，因此撰寫查詢的方式會影響哪些記錄表面。下列指引可協助您根據您的意圖獲得更好的結果。

撰寫有效的搜尋查詢

當您知道確切的名稱或識別符 時，請使用簡短的特定查詢。關鍵字搜尋會比對確切的文字與記錄名稱、描述和描述項內容。「weather-api-v2」或「pdf-processing」等簡短查詢可有效依名稱尋找記錄。

當您依功能或使用案例 進行探索時，請使用您需要的內容的自然語言描述。語意搜尋了解概念意圖，因此「尋找可預訂航班的工具」或「從 PDF 文件擷取結構化資料」等查詢可以符合相關記錄，即使這些確切文字未出現在記錄中繼資料中。

避免在同一個查詢中混合類似篩選條件的限制與描述性意圖。像是「尋找所有 MCP 伺服器進行天氣預測」的查詢會透過語意和關鍵字搜尋來傳送整個句子。語意元件將完整句子解譯為概念意圖，這可以顯示概念上相關的記錄，但不符合您打算限制的特定屬性。反之，請針對屬性型限制條件使用中繼資料篩選條件，並將查詢著重於主題。請參閱何時使用中繼資料篩選條件與查詢文字。

撰寫可探索的記錄

  • 撰寫說明，說明資源的功能及其解決的問題。語意搜尋了解意圖，因此「協助客戶追蹤套件交付」比「delivery-status-endpoint」更可探索。

  • 提供 MCP 伺服器的完整工具定義。工具描述和輸入參數描述都有助於搜尋相關性。

  • 在名稱和描述中包含相關關鍵字。關鍵字搜尋符合確切的文字，因此如果消費者可能搜尋特定詞彙，請確定這些詞彙出現在您的記錄中。

何時使用中繼資料篩選條件與查詢文字

當您的意圖是透過記錄類型、名稱或版本等已知屬性來限制結果時，請使用中繼資料篩選條件。請勿在查詢文字本身中嵌入類似篩選條件的限制。例如，如果您想要尋找與天氣相關的所有 MCP 伺服器，請使用記錄類型的中繼資料篩選條件和主題的查詢：

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

避免將限制條件放入查詢文字，例如「尋找所有 MCP 伺服器進行天氣預測」。由於較長的查詢傾向於語意比對，因此「MCP 伺服器」一詞會解釋為概念意圖的一部分，而不是確切的篩選條件。這可能會導致語意元件傳回概念上與完整句子相關的記錄，但不符合您要篩選的特定屬性，例如，傳回有關天氣的客服人員記錄與 MCP 伺服器記錄。這同樣適用於任何屬性型限制條件。如果您想要具有特定名稱、版本或類型的記錄，請使用對應的中繼資料篩選條件，而不是在查詢中包含這些詞彙。

您可以篩選下列欄位：

  • name — 依確切名稱比對記錄。

  • descriptorType — 依資源類型比對記錄 MCP （例如，、A2A、SKILL、CUSTOM)。

  • version — 依版本字串比對記錄。

篩選條件支援 $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 客服人員登錄檔搜尋中的最終一致性。