View a markdown version of this page

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

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

搜尋登錄檔記錄

遷移現已開啟

AWS 代理程式登錄檔已在新的agent-registry命名空間下啟動。公有預覽bedrock-agentcore命名空間的支援將於 2026 年 9 月 17 日停止。如需遷移說明，請參閱綜合登錄遷移指南。

身為消費者，您可以使用SearchDiscoverableRegistryRecords資料平面 API 搜尋登錄檔核准的記錄。API 接受自然語言查詢、套用結合語意理解與關鍵字比對的混合式搜尋，以及傳回僅限最新修訂版狀態為已核准之記錄的排名結果。不會傳回草稿、待核准、已拒絕或已棄用狀態的記錄。若要在沒有查詢的情況下瀏覽目錄，請BatchGetDiscoverableRegistryRecord改用 ListDiscoverableRegistryRecords和 - 請參閱瀏覽核准的記錄。

您也可以使用任何 MCP 相容用戶端，透過登錄檔的 MCP 端點 (InvokeRegistryMcp) 叫用探索資料平面 APIs。端點會將 SearchDiscoverableRegistryRecords、 ListDiscoverableRegistryRecords和 公開BatchGetDiscoverableRegistryRecord為您可以直接呼叫的 MCP 工具。

請求參數

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

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

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

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

中繼資料篩選條件

運算子：$eq、$ne、$in。邏輯：$and、$or。欄位：name、recordType、recordVersion。

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

合併： {"$and": [{"recordType": {"$eq": "MCP"}}, {"recordVersion": {"$eq": "1.0"}}]}

主控台

範例
AWS Agent Registry namespace

  1. 開啟 AWS 代理程式登錄檔主控台。

  2. 在導覽窗格中，選擇錄製目錄。

  3. 選擇您要搜尋的登錄檔。頁面會自動呼叫 ，ListDiscoverableRegistryRecords並在登錄檔中顯示已核准的記錄。

  4. 在搜尋列中，輸入您的搜尋查詢。這會觸發SearchDiscoverableRegistryRecords並顯示排名結果。

  5. （選用） 若要依特定屬性篩選結果，請選擇搜尋欄位以展開屬性功能表，然後選擇篩選條件：名稱、記錄類型或版本。

  6. 從結果中選擇記錄，以檢視其完整的描述項內容。

Amazon Bedrock AgentCore namespace (to be deprecated)

  1. 在 Bedrock-AgentCore 主控台中開啟 AWS 代理程式登錄頁面。

  2. 在導覽窗格中，選擇登錄檔，然後選擇登錄檔名稱。

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

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

注意

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

AWS CLI （使用 IAM 型傳入授權註冊）

範例
AWS Agent Registry namespace
aws agent-registry search-discoverable-registry-records \
  --search-query "weather" \
  --registry-ids "<registryARN>" \
  --region us-east-1
Amazon Bedrock AgentCore namespace (to be deprecated)
aws bedrock-agentcore search-registry-records \
  --search-query "weather" \
  --registry-ids "<registryARN>" \
  --region us-east-1

AWS SDK （使用 IAM 型傳入授權註冊）

範例
AWS Agent Registry namespace
import boto3

client = boto3.client('agent-registry')

response = client.search_discoverable_registry_records(
    registryIds=['<registryARN>'],
    searchQuery='weather',
    maxResults=10
)
for record in response['registryRecords']:
    print(f"{record['displayName']} ({record['name']}) - {record['recordType']} - {record['status']}")
Amazon Bedrock AgentCore namespace (to be deprecated)
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'

然後使用承載字符進行搜尋：

範例
AWS Agent Registry namespace
curl -X POST "https://agent-registry.<region>.api.aws/discoverable-records-search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"registryIds": ["<registryARN>"], "searchQuery": "weather", "maxResults": 10}'
Amazon Bedrock AgentCore namespace (to be deprecated)
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或透過主控台核准登錄檔記錄時，記錄不會立即出現在 SearchDiscoverableRegistryRecords或 InvokeRegistryMcp 結果中。已核准的記錄通常需要幾秒鐘的時間才能編製索引並變得可探索，但在某些情況下，可能需要幾分鐘的時間。

在此期間，您可能會觀察到下列行為：

  • SearchDiscoverableRegistryRecords 查詢不會傳回剛核准的記錄。

  • ListDiscoverableRegistryRecords 或 BatchGetDiscoverableRegistryRecord呼叫不包含記錄。

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

  • 相反地，控制平面 APIs(GetRegistryRecord 和 ListRegistryRecords) 會在 UpdateRegistryRecordStatus 完成後立即傳回新核准的記錄。最終一致性僅適用於探索資料平面 APIs 和登錄 MCP 端點。

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

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

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

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

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

注意

SearchDiscoverableRegistryRecords 已在 bedrock-agentcore 命名空間SearchRegistryRecords中命名。

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

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

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

用於搜尋的記錄屬性

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

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

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

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

  • 記錄類型和版本 — 可作為可篩選欄位使用。您可以在 name、 recordType和 上使用中繼資料篩選條件來縮小結果recordVersion。

如何處理搜尋查詢

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

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

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

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

如何排名結果

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

撰寫有效的搜尋查詢

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

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

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

撰寫可探索的記錄

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

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

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

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

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

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

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

您可以篩選下列欄位：

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

  • recordType — 依語意類型 (AGENT、MCP、SKILL、) 比對記錄CUSTOM。

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

篩選條件支援 $eq（等於）、 $ne （不等於） 和 $in（符合清單中的任何值） 運算子，並且可以使用 $and和 $or 邏輯組合。

例如，若要僅搜尋與天氣相關的 MCP 伺服器：

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

若要排除特定資源類型：

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

若要符合多個版本中的任何一個：

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

搜尋只會傳回已核准的記錄

只有處於核准狀態的記錄會顯示在搜尋結果中，並透過 MCP 端點顯示。不會傳回草稿、待核准、已拒絕或已棄用狀態的記錄。如果最近核准的記錄未出現在結果中，請參閱AWS 客服人員登錄檔搜尋中的最終一致性。