# 記憶體記錄串流
<a name="memory-record-streaming"></a>

Amazon Bedrock AgentCore 記憶體中的記憶體記錄串流會在建立、更新或刪除記憶體記錄時提供即時通知。您不會輪詢 APIs來偵測變更，而是接收推送型事件到帳戶中的 Kinesis Data Stream，讓事件驅動型架構在記憶體記錄生命週期變更發生時做出反應。

透過記憶體記錄串流，您可以：
+ 接收即時事件以建立、更新和刪除記憶體記錄
+ 建置事件驅動型架構而不輪詢 APIs
+ 將記憶體記錄資料串流到資料湖，以進行整合和設定檔管理
+ 擷取新洞見時觸發下游工作流程
+ 追蹤客服人員和工作階段之間的記憶體記錄狀態變更

**Topics**
+ [運作方式](#memory-record-streaming-how-it-works)
+ [串流事件類型](#memory-record-streaming-event-types)
+ [事件結構描述](#memory-record-streaming-event-schema)
+ [先決條件](#memory-record-streaming-prerequisites)
+ [設定串流](#memory-record-streaming-setup)
+ [設定事件內容層級](#memory-record-streaming-content-level)
+ [測試您的實作](#memory-record-streaming-test)
+ [管理串流組態](#memory-record-streaming-manage)
+ [可觀測性](#memory-record-streaming-observability)

## 運作方式
<a name="memory-record-streaming-how-it-works"></a>

記憶體記錄串流使用以推送為基礎的交付模型。當記憶體記錄變更時，事件會自動發佈到您的 Kinesis Data Stream。

事件是由下列操作觸發：

1.  **建立** – 從短期記憶體事件 （透過 `CreateEvent`和記憶體策略） 非同步擷取，或透過 `BatchCreateMemoryRecords` API 直接建立

1.  **更新** – 透過 `BatchUpdateMemoryRecords` API 直接修改

1.  **刪除** – 合併工作流程 （刪除重複/抑制）、`DeleteMemoryRecord`API 或 `BatchDeleteMemoryRecords` API

## 串流事件類型
<a name="memory-record-streaming-event-types"></a>

下表說明支援的串流事件類型以及觸發時間。


| 作業 | 串流事件類型 | 觸發者 | 
| --- | --- | --- | 
| 建立 |  `MemoryRecordCreated`  | 長期記憶體擷取/合併、`BatchCreateMemoryRecords`API | 
| 更新 |  `MemoryRecordUpdated`  |  `BatchUpdateMemoryRecords` API | 
| 刪除 |  `MemoryRecordDeleted`  |  `BatchDeleteMemoryRecords` 、`DeleteMemoryRecord`API、長期記憶體整合 | 

## 事件結構描述
<a name="memory-record-streaming-event-schema"></a>

### MemoryRecordCreated/MemoryRecordUpdated
<a name="memory-record-streaming-created-updated-schema"></a>

 `MemoryRecordCreated` 和 `MemoryRecordUpdated`事件共用相同的結構描述。

```
{
  "memoryStreamEvent": {
    "eventType": "<MemoryRecordCreated, MemoryRecordUpdated>",
    "eventTime": "2026-03-06T16:45:00.000Z",
    "memoryId": "<memory-id>",
    "memoryRecordId": "<memory-record-id>",
    "namespaces": ["<namespace>"],
    "createdAt": 1736622300000,
    "memoryStrategyId": "<memory-strategy-id>",
    "memoryStrategyType": "<memory-strategy-type>",
    "metadata": {<metadata>},
    "memoryRecordText": "<memory-record-text>"
  }
}
```

只有在串流交付組態上的內容層級設定為 `FULL_CONTENT` 時，才會包含 `memoryRecordText` 欄位。如需其他詳細資訊，請參閱[設定事件內容層級](#memory-record-streaming-content-level)。

### MemoryRecordDeleted
<a name="memory-record-streaming-deleted-schema"></a>

```
{
  "memoryStreamEvent": {
    "eventType": "MemoryRecordDeleted",
    "eventTime": "2026-02-16T00:13:54.912530116Z",
    "memoryId": "<memory-id>",
    "memoryRecordId": "<memory-record-id>"
  }
}
```

刪除事件僅包含記憶體和記錄識別符，無論設定的內容層級為何。

## 先決條件
<a name="memory-record-streaming-prerequisites"></a>

設定記憶體記錄串流之前，請確認您已：
+ 具有適當許可 AWS 的帳戶
+ Amazon Bedrock AgentCore 存取
+ 對 AWS IAM 和 Amazon Kinesis Data Streams 的基本了解

## 設定串流
<a name="memory-record-streaming-setup"></a>

### 步驟 1：建立 Kinesis Data Stream
<a name="memory-record-streaming-setup-step1"></a>

在 Amazon Bedrock AgentCore 將發佈記憶體記錄生命週期事件的帳戶中建立 Kinesis Data Stream。

您可以使用 AWS 主控台、CDK、CloudFormation 或 CLI AWS 建立串流。如果您啟用 Kinesis 伺服器端加密，請注意 KMS 金鑰 ARN — 您需要它才能取得 IAM 角色許可。

### 步驟 2：設定取用者
<a name="memory-record-streaming-setup-step2"></a>

設定取用者以處理來自 Kinesis Data Stream 的事件。

授予您的取用者 `AmazonKinesisReadOnlyAccess`（或同等許可），並將 Kinesis Data Stream 新增為觸發條件。

### 步驟 3：建立 IAM 角色
<a name="memory-record-streaming-setup-step3"></a>

建立 Amazon Bedrock AgentCore 可擔任的 IAM 角色，以將事件發佈到您的 Kinesis Data Stream。

信任政策：

```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:<region>:<account-id>:memory/*"
        }
      }
    }
  ]
}
```

許可政策：

對於內建記憶體策略，許可政策如下所示：

```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kinesis:PutRecords",
        "kinesis:DescribeStream"
      ],
      "Resource": "arn:aws:kinesis:<region>:<account-id>:stream/<stream-name>"
    }
  ]
}
```

對於自訂記憶體策略，許可政策如下所示：

```
{
"Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kinesis:PutRecords",
        "kinesis:DescribeStream"
      ],
      "Resource": "arn:aws:kinesis:<region>:<account-id>:stream/<stream-name>"
    },
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/*",
        "arn:aws:bedrock:*:*:inference-profile/*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:ResourceAccount": "${aws:PrincipalAccount}"
        }
      }
    }
  ]
}
```

如果您的 Kinesis Data Stream 使用伺服器端加密，請將以下內容新增至許可政策：

```
{
  "Sid": "KMSPermissions",
  "Effect": "Allow",
  "Action": "kms:GenerateDataKey",
  "Resource": "arn:aws:kms:<region>:<account-id>:key/your-kinesis-data-stream-key-id"
}
```

### 步驟 4：建立啟用串流的記憶體
<a name="memory-record-streaming-setup-step4"></a>

使用 `CreateMemory` API 建立具有串流交付資源的 Amazon Bedrock AgentCore 記憶體。指定串流交付資源`memoryExecutionRoleArn`時，您必須提供 。

```
aws bedrock-agentcore-control create-memory \
  --name "MyStreamingMemory" \
  --description "Memory with long term memory record streaming enabled" \
  --event-expiry-duration 30 \
  --memory-execution-role-arn "arn:aws:iam::<account-id>:role/AgentCoreMemoryRole" \
  --stream-delivery-resources '{
    "resources": [
      {
        "kinesis": {
          "dataStreamArn": "arn:aws:kinesis:<region>:<account-id>:stream/<stream-name>",
          "contentConfigurations": [
            {
              "type": "MEMORY_RECORDS",
              "level": "FULL_CONTENT"
            }
          ]
        }
      }
    ]
  }'
```

### 步驟 5：驗證您的串流整合
<a name="memory-record-streaming-setup-step5"></a>

當您建立啟用串流的記憶體時，Amazon Bedrock AgentCore 記憶體會驗證組態和許可。成功驗證後，`StreamingEnabled`事件會發佈到您的 Kinesis Data Stream。

檢查您的消費者是否有以下格式的驗證事件：

```
{
  "memoryStreamEvent": {
    "eventType": "StreamingEnabled",
    "eventTime": "2026-03-03T19:27:08.344082626Z",
    "memoryId": "<memory-id>",
    "message": "Streaming enabled for memory resource: <memory-id>"
  }
}
```

## 設定事件內容層級
<a name="memory-record-streaming-content-level"></a>

`contentConfigurations` 欄位控制每個事件中包含的資料。您可以選擇兩個內容層級：
+  **METADATA\_ONLY** ：串流事件僅包含中繼資料欄位 `namespaces` (`memoryId`、`memoryRecordId`、`strategyId`、、時間戳記等）。需要 API 呼叫才能擷取完整的記憶體記錄內容。
+  **FULL\_CONTENT** ：串流事件包含所有中繼資料欄位，以及包含記憶體記錄內容`memoryRecordText`的欄位。

`METADATA_ONLY` 用於輕量型事件通知，您只需要知道發生變更。當您的下游處理需要記憶體記錄文字而不進行其他 API 呼叫`FULL_CONTENT`時使用 。

## 測試您的實作
<a name="memory-record-streaming-test"></a>

### 步驟 1：建立測試事件
<a name="memory-record-streaming-test-step1"></a>

使用資料平面 APIs產生記憶體記錄生命週期事件，並確認它們出現在您的取用者中。

透過短期記憶體建立事件 （觸發非同步擷取）：

```
aws bedrock-agentcore create-event \
  --memory-id "<memory-id>" \
  --actor-id "test-user" \
  --session-id "test-session-1" \
  --event-timestamp "$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")" \
  --payload '[
    {
      "conversational": {
        "content": {"text": "I prefer Italian restaurants with outdoor seating"},
        "role": "USER"
      }
    },
    {
      "conversational": {
        "content": {"text": "Noted! I will remember your preference for Italian restaurants with outdoor seating."},
        "role": "ASSISTANT"
      }
    }
  ]'
```

直接建立記錄：

```
aws bedrock-agentcore batch-create-memory-records \
  --memory-id "<memory-id>" \
  --records '[
    {
      "requestIdentifier": "test-1",
      "content": {"text": "User prefers window seats on flights"},
      "namespaces": ["travel/test-user"],
      "timestamp": "1729525989"
    }
  ]'
```

### 步驟 2：驗證交付
<a name="memory-record-streaming-test-step2"></a>

檢查您的取用者以確認收到事件。您應該會看到透過任一方法建立之記錄`MemoryRecordCreated`的事件。

您也可以使用[指標](#memory-record-streaming-metrics)和[日誌](#memory-record-streaming-logs)來監控交付運作狀態。

您可以使用 `ListMemoryRecords` API 進行交叉參考：

```
aws bedrock-agentcore list-memory-records \
  --memory-id "<memory-id>" \
  --namespace "<namespace>"
```

## 管理串流組態
<a name="memory-record-streaming-manage"></a>

### 更新串流組態
<a name="memory-record-streaming-update"></a>

使用 `UpdateMemory` API 來修改或移除串流交付資源。

移除串流：

```
aws bedrock-agentcore-control update-memory \
  --region us-east-1 \
  --memory-id "<memory-id>" \
  --stream-delivery-resources '{"resources": []}'
```

### 變更內容層級
<a name="memory-record-streaming-change-content-level"></a>

```
aws bedrock-agentcore-control update-memory \
  --memory-id "<memory-id>" \
  --stream-delivery-resources '{
    "resources": [
      {
        "kinesis": {
          "dataStreamArn": "arn:aws:kinesis:us-east-1:<account-id>:stream/<stream-name>",
          "contentConfigurations": [
            {
              "type": "MEMORY_RECORDS",
              "level": "METADATA_ONLY"
            }
          ]
        }
      }
    ]
  }'
```

## 可觀測性
<a name="memory-record-streaming-observability"></a>

Amazon Bedrock AgentCore Memory 會將 CloudWatch 指標和日誌提供給 AWS 您的帳戶，讓您了解記憶體記錄串流交付的運作狀態和狀態。

### 指標
<a name="memory-record-streaming-metrics"></a>

指標會在 `AWS/Bedrock-AgentCore` 命名空間下發佈至您的帳戶。


| 指標 | 說明 | 
| --- | --- | 
|  `StreamPublishingSuccess`  | 成功發佈至 Kinesis Data Stream 的記憶體記錄事件數目。 | 
|  `StreamPublishingFailure`  | 無法發佈至 Kinesis Data Stream 的記憶體記錄事件數目。 | 
|  `StreamUserError`  | 由於客戶端組態問題而失敗的事件數量，例如缺少 IAM 許可或無效的 KMS 金鑰狀態。 | 

所有指標都會以具有下列維度的`Count`單位發出：


| 維度 | Value | 說明 | 
| --- | --- | --- | 
| 作業 |  `MemoryStreamEvent`  | 串流操作類型。 | 
| 資源 | 記憶體 ARN | 記憶體資源的 ARN （例如 `arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/memory-123` )。 | 

### 日誌
<a name="memory-record-streaming-logs"></a>

發生終端機 （不可重試） 發佈失敗時，Amazon Bedrock AgentCore 記憶體會將日誌提供給您的帳戶。


| 欄位 | 說明 | 
| --- | --- | 
|  `log`  | 描述失敗的錯誤訊息。 | 
|  `streamArn`  | 目標 Kinesis Data Stream ARN。 | 
|  `errorCode`  | 特定錯誤代碼。 | 
|  `errorMessage`  | 人類可讀取的錯誤描述。 | 
|  `eventType`  | 串流事件類型 `MemoryRecordCreated` (、 `MemoryRecordUpdated` 或 `MemoryRecordDeleted` )。 | 
|  `memoryRecordId`  | 受影響記憶體記錄的識別符。 |