# 建立和管理記錄
<a name="registry-create-manage-records"></a>

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

## 建立登錄檔記錄
<a name="registry-create-record"></a>

### 主控台
<a name="registry-create-record-console"></a>

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

1. 在**登錄檔記錄**區段中，選擇**建立記錄**。

1. 選擇來源類型：

   1.  **從端點同步 **- 提供端點 URL 和選用登入資料來叫用端點，而登錄檔會從來源擷取中繼資料。僅適用於 MCP 和客服人員記錄類型。若要在來源變更後更新記錄，您必須手動觸發同步。如需詳細資訊，請參閱[從外部來源同步記錄](registry-sync-records.md)。

   1.  **手動** — 手動設定記錄詳細資訊和通訊協定組態。

 **從端點同步** 

1. 在**記錄詳細資訊**下，選取記錄類型：**MCP** 或**客服人員**。
**注意**  
只有 MCP 和客服人員記錄類型才支援同步。客服人員技能和自訂記錄類型不支援同步 - 請改用手動來源類型。

1. 輸入**端點** URL。必須是有效的 HTTPS URL。

1. 在**登入資料類型**下，選擇登錄檔授權端點的方式：

   1.  **IAM** — 提供 SigV4 簽署**的角色 ARN** 和服務****名稱 （例如，、`bedrock-agentcore``execute-api`、`lambda`)。選擇性地指定要簽署**的區域**。

   1.  **OAuth** — 從 AgentCore Identity 選取或輸入**登入資料提供者** ARN。選擇性地在其他組態下設定**範圍**和**自訂參數**。

   1.  **無** — 無授權 （適用於公有端點）。

1. 選擇**建立記錄**。

   記錄會以 CREATING 狀態建立。登錄檔會連線至端點、擷取中繼資料，並填入記錄的描述項。同步完成後，記錄會轉換為 DRAFT。如果同步失敗，記錄會轉換為 CREATE\_FAILED 狀態，並在記錄詳細資訊頁面上的狀態原因欄位中提供錯誤詳細資訊。如需故障診斷，請參閱[記錄同步錯誤](registry-troubleshooting.md#registry-troubleshooting-sync-errors)。若要在來源變更時更新記錄，請使用記錄詳細資訊頁面上的**同步**按鈕，或在編輯期間**從端點選取重新同步**。

如需使用同步建立記錄的 AWS CLI 和 SDK 範例，請參閱[從外部來源同步記錄](registry-sync-records.md)。

 **手動** 

1. 在**記錄詳細資訊** 下，輸入：

   1.  **名稱** — 必須以字母或數字開頭。有效字元為 a-z、A-Z、0-9、\_ （底線）、- （連字號）、. （點） 和 / （正斜線）。名稱最多可有 255 個字元。

   1.  **描述** （選用） — 1 到 4，096 個字元。

   1.  **記錄版本** — 指定此記錄的版本 （例如 1.0.0、2.1 版）。

1. 在**記錄類型** 下，選取下列其中一項：**MCP** 、**客服人員** 、**客服人員技能** 或**自訂**。

1. 類型特定的編輯器隨即出現。以 JSON 格式輸入您的通訊協定組態。

   1. 對於**客服人員**和 **MCP** 類型，切換**顯示官方結構描述**以side-by-side顯示參考結構描述以獲得指導。

   1. 主控台會根據官方結構描述驗證您的 JSON，並使用 **Amazon Q 診斷**按鈕顯示內嵌錯誤 （例如「遺失屬性 'name')。

1. 選擇以下一項：

   1.  **建立為草稿** — 以草稿狀態建立記錄。

   1.  **建立並提交以供核准** — 建立記錄並立即提交以供核准。

### AWS CLI
<a name="registry-create-record-cli"></a>

```
aws bedrock-agentcore-control create-registry-record \
  --registry-id <registryId> \
  --name "MyMCPServer" \
  --descriptor-type MCP \
  --descriptors '{"mcp": {"server": {"inlineContent": "{\"name\": \"my/mcp-server\", \"description\": \"My MCP server\", \"version\": \"1.0.0\"}"}}}' \
  --record-version "1.0" \
  --region us-east-1
```

### AWS 開發套件
<a name="registry-create-record-sdk"></a>

```
import boto3
import json

client = boto3.client('bedrock-agentcore-control')

server_content = json.dumps({
    "name": "my/mcp-server",
    "description": "My MCP server",
    "version": "1.0.0"
})

response = client.create_registry_record(
    registryId='<registryId>',
    name='MyMCPServer',
    descriptorType='MCP',
    descriptors={
        'mcp': {
            'server': {
                'inlineContent': server_content
            }
        }
    },
    recordVersion='1.0'
)
print(f"Record ARN: {response['recordArn']}")
print(f"Status: {response['status']}")  # CREATING
```

## 列出登錄檔記錄
<a name="registry-list-records"></a>

### 主控台
<a name="registry-list-records-console"></a>

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

1. **登錄檔記錄**區段會顯示：

   1.  **狀態摘要計數器** — 提交總數、待核准、已核准、已棄用、已拒絕。

   1.  包含資料欄**的記錄資料表**：名稱、描述、狀態、記錄類型、記錄 ARN、上次更新。

1. 使用**搜尋記錄**列依名稱篩選。

1. 使用**更新狀態**下拉式清單，對選取的記錄執行大量狀態變更。

### AWS CLI
<a name="registry-list-records-cli"></a>

```
aws bedrock-agentcore-control list-registry-records \
  --registry-id "<registryId>" \
  --region us-east-1
```

### AWS 開發套件
<a name="registry-list-records-sdk"></a>

```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.list_registry_records(
    registryId='<registryId>'
)
for record in response['registryRecords']:
    print(f"{record['name']} - {record['status']} - {record['descriptorType']}")
```

## 檢視記錄詳細資訊
<a name="registry-view-record"></a>

### 主控台
<a name="registry-view-record-console"></a>

1. 在登錄檔詳細資訊頁面中，從記錄資料表中選擇記錄名稱。

1. 記錄詳細資訊頁面會顯示：

   1.  **記錄詳細資訊**區段 — 名稱、描述、記錄 ARN、狀態 （顯示為記錄名稱旁的徽章）、版本、上次更新日期、記錄類型、記錄 ID、建立日期。

   1.  **同步組態**區段 （如果已設定） — 同步類型、來源 URL 和憑證提供者詳細資訊 (IAM 角色 ARN、服務、區域或 OAuth 供應商 ARN、授予類型、範圍、自訂參數）。

   1.  **通訊協定組態**區段 — 以格式化 JSON 顯示的描述項內容 （例如，A2A 記錄的「代理程式卡」、MCP 記錄的「伺服器」和「工具」)。

1. 可用的動作：

   1.  **同步**按鈕 （僅限 MCP 和客服人員記錄） — 從設定的端點觸發新的同步。在繼續之前開啟確認對話方塊。記錄會在同步期間轉換為 UPDATING 狀態。

   1.  **更新狀態**下拉式清單 — 提交以進行核准、核准、拒絕或棄用。

   1.  **三點式選單 (⋮)** — 編輯或刪除。

### AWS CLI
<a name="registry-view-record-cli"></a>

```
aws bedrock-agentcore-control get-registry-record \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --region us-east-1
```

### AWS 開發套件
<a name="registry-view-record-sdk"></a>

```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.get_registry_record(
    registryId='<registryId>',
    recordId='<recordId>'
)
print(f"Name: {response['name']}")
print(f"Description: {response['description']}")
print(f"Status: {response['status']}")
print(f"Descriptor Type: {response['descriptorType']}")
print(f"Version: {response['recordVersion']}")
```

## 更新登錄檔記錄
<a name="registry-update-record"></a>

### 主控台
<a name="registry-update-record-console"></a>

1. 在記錄詳細資訊頁面中，選擇三點選單 (⋮)，然後選擇**編輯**。

1. 在**編輯記錄**頁面上，更新下列任何項目：

   1.  **名稱** 、**描述** 、**記錄詳細資訊下的記錄版本**。

   1.  **記錄類型** — 視需要變更通訊協定類型。

1. （僅限 MCP 和客服人員記錄） **在從端點同步**下，選擇性地設定同步：

   您可以透過同步更新記錄，無論它們最初是否使用同步建立。在更新期間觸發同步時，記錄會轉換為 UPDATING 狀態。如果成功，則會以 DRAFT 狀態建立新的記錄版本。如果失敗，記錄會轉換為 UPDATE\_FAILED 狀態，並在狀態原因欄位中包含錯誤詳細資訊。同步資料會以來源中找到的值覆寫記錄的名稱、描述、版本、工具定義和伺服器定義，但不會修改來源未提供的欄位。管理員或策展者必須檢閱並核准新的草稿，才能在搜尋中顯示。在此之前，先前的核准修訂 （如果有的話） 仍可供搜尋。如需雙修訂版行為的詳細資訊，請參閱[記錄生命週期](registry-record-lifecycle.md)。

   1. 輸入**端點** URL 以啟用同步。提供端點時，登入資料類型欄位會出現。如果記錄已設定同步，端點和登入資料提供者欄位會預先填入現有的組態。

   1. 選擇**登入資料類型** (IAM、OAuth 或無） 並填寫必要欄位。如果記錄先前已使用登入資料提供者設定，則會預先填入現有的值。

   1. 選取**從端點重新同步**以在儲存時觸發新的同步。記錄會在同步期間轉換為 UPDATING 狀態。

   1. 若要移除同步，請選擇端點欄位旁的清除按鈕。這會重設端點和所有登入資料欄位。

1. 在**記錄組態**下，更新 JSON 編輯器中的記錄定義。

   1. 您可以同時設定 端點以進行同步處理，並手動編輯記錄的定義。觸發同步時，登錄檔會從端點擷取最新的中繼資料，並以來源中找到的值更新記錄的名稱、描述、版本、工具定義和伺服器定義，優先於對這些欄位的任何手動編輯。不會修改來源未提供的欄位。

1. 主控台會根據官方結構描述驗證您的 JSON，並顯示使用 **Amazon Q 診斷按鈕的**內嵌錯誤。

1. 選擇以下一項：

   1.  **儲存變更** — 將記錄儲存為草稿。

   1.  **儲存並提交以供核准** — 在一個步驟中儲存並提交。

成功橫幅確認：「【Name】 已更新並成功提交核准。」

### AWS CLI
<a name="registry-update-record-cli"></a>

```
aws bedrock-agentcore-control update-registry-record \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --description "Updated description" \
  --region us-east-1
```

### AWS 開發套件
<a name="registry-update-record-sdk"></a>

```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.update_registry_record(
    registryId='<registryId>',
    recordId='<recordId>',
    description='Updated description'
)
print(f"Updated: {response['name']} - Status: {response['status']}")
```

## 提交記錄以供核准
<a name="registry-submit-record"></a>

### 主控台
<a name="registry-submit-record-console"></a>

從記錄詳細資訊頁面 -

1. 選擇**更新狀態**下拉式清單

1. 然後，選擇**提交以進行核准**。

   1. 或者，使用**建立並提交以供核准**，或在建立或編輯期間**儲存並提交以供核准**。

**注意**  
如果登錄檔的自動核准組態設為 TRUE，則提交記錄以供核准會自動核准。否則，如果自動核准組態設為 FALSE，則記錄會移至「待核准」狀態，並等待 Curator 核准或拒絕它。此外，會觸發 Amazon EventBridge 通知，指出已請求核准新記錄。

### AWS CLI
<a name="registry-submit-record-cli"></a>

```
aws bedrock-agentcore-control submit-registry-record-for-approval \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --region us-east-1
```

### AWS 開發套件
<a name="registry-submit-record-sdk"></a>

```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.submit_registry_record_for_approval(
    registryId='<registryId>',
    recordId='<recordId>'
)
print(f"Status: {response['status']}")  # PENDING_APPROVAL or APPROVED
```

## 刪除登錄檔記錄
<a name="registry-delete-record"></a>

### 主控台
<a name="registry-delete-record-console"></a>

1. 從記錄詳細資訊頁面，選擇三點選單 (⋮)，然後選擇**刪除**。

1. 出現提示時輸入 'delete' 以確認刪除

刪除是永久的，無法復原。

### AWS CLI
<a name="registry-delete-record-cli"></a>

```
aws bedrock-agentcore-control delete-registry-record \
  --registry-id "<registryId>" \
  --record-id "<recordId>" \
  --region us-east-1
```

### AWS 開發套件
<a name="registry-delete-record-sdk"></a>

```
import boto3

client = boto3.client('bedrock-agentcore-control')

response = client.delete_registry_record(
    registryId='<registryId>',
    recordId='<recordId>'
)
print("Record deleted successfully")
```

## 結構描述驗證
<a name="registry-schema-validation"></a>

當您建立或編輯記錄時，主控台和 API 會根據所選記錄類型的官方結構描述來驗證您的通訊協定組態。如需驗證的詳細資訊，請參閱[支援的記錄類型](registry-supported-record-types.md)。