메모리 레코드 스트리밍

Amazon Bedrock AgentCore 메모리의 메모리 레코드 스트리밍은 메모리 레코드가 생성, 업데이트 또는 삭제될 때 실시간 알림을 제공합니다. APIs 폴링하여 변경 사항을 감지하는 대신 계정의 Kinesis Data Stream으로 푸시 기반 이벤트를 수신하여 메모리 레코드 수명 주기 변경 발생 시 이에 대응하는 이벤트 기반 아키텍처를 활성화합니다.

메모리 레코드 스트리밍을 사용하면 다음을 수행할 수 있습니다.

작동 방식

메모리 레코드 스트리밍은 푸시 기반 전송 모델을 사용합니다. 메모리 레코드가 변경되면 이벤트가 Kinesis Data Stream에 자동으로 게시됩니다.

이벤트는 다음 작업에 의해 트리거됩니다.

스트림 이벤트 유형

다음 표에서는 지원되는 스트림 이벤트 유형과 트리거 시기를 설명합니다.

이벤트 스키마

MemoryRecordCreated / MemoryRecordUpdated

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

memoryRecordText 필드는 스트림 전송 구성의 콘텐츠 수준이 FULL_CONTENT 로 설정된 경우에만 포함됩니다. 자세한 내용은 이벤트 콘텐츠 수준 구성을 참조하세요.

MemoryRecordDeleted

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

삭제 이벤트에는 구성된 콘텐츠 수준에 관계없이 메모리 및 레코드 식별자만 포함됩니다.

사전 조건

메모리 레코드 스트리밍을 설정하기 전에 다음이 있는지 확인합니다.

스트리밍 설정

1단계: Kinesis 데이터 스트림 생성

계정에서 Amazon Bedrock AgentCore가 메모리 레코드 수명 주기 이벤트를 게시할 Kinesis Data Stream을 생성합니다.

AWS 콘솔, CDK, CloudFormation 또는 AWS CLI를 사용하여 스트림을 생성할 수 있습니다. Kinesis 서버 측 암호화를 활성화하는 경우 KMS 키 ARN을 기록해 둡니다. IAM 역할 권한에 필요합니다.

2단계: 소비자 설정

Kinesis Data Stream의 이벤트를 처리하도록 소비자를 설정합니다.

소비자AmazonKinesisReadOnlyAccess(또는 이에 상응하는 권한)에게 권한을 부여하고 Kinesis Data Stream을 트리거로 추가합니다.

3단계 - IAM 역할 생성

Amazon Bedrock AgentCore가 Kinesis Data Stream에 이벤트를 게시하기 위해 수임할 수 있는 IAM 역할을 생성합니다.

신뢰 정책:

{
"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단계: 스트리밍이 활성화된 메모리 생성

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단계: 스트리밍 통합 확인

스트리밍이 활성화된 메모리를 생성하면 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>"
  }
}

이벤트 콘텐츠 수준 구성

contentConfigurations 필드는 각 이벤트에 포함되는 데이터를 제어합니다. 다음 두 가지 콘텐츠 수준 중에서 선택할 수 있습니다.

변경이 발생했음을 알기만 하면 되는 경량 이벤트 알림에 METADATA_ONLY를 사용합니다. 다운스트림 처리에 추가 API 호출 없이 메모리 레코드 텍스트가 필요할 FULL_CONTENT 때 사용합니다.

구현 테스트

1단계: 테스트 이벤트 생성

데이터 영역 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단계: 전송 확인

소비자를 확인하여 이벤트가 수신되고 있는지 확인합니다. 두 방법 중 하나를 통해 생성된 레코드에 대한 MemoryRecordCreated 이벤트가 표시되어야 합니다.

지표 및 로그를 사용하여 전송 상태를 모니터링할 수도 있습니다.

ListMemoryRecords API를 사용하여 다음을 상호 참조할 수 있습니다.

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

스트리밍 구성 관리

스트리밍 구성 업데이트

UpdateMemory API를 사용하여 스트림 전송 리소스를 수정하거나 제거합니다.

스트리밍 제거:

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

콘텐츠 수준 변경

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

관찰성

Amazon Bedrock AgentCore 메모리는 CloudWatch 지표와 로그를 AWS 계정에 제공하므로 메모리 레코드 스트림 전송의 상태와 상태를 파악할 수 있습니다.

Metrics

지표는 AWS/Bedrock-AgentCore 네임스페이스 아래의 계정에 게시됩니다.

모든 지표는 다음 차원을 가진 Count 단위로 내보내집니다.

로그

Amazon Bedrock AgentCore 메모리는 터미널(재시도 불가) 게시 실패가 발생할 때 계정에 로그를 제공합니다.