Streaming de gravação de memória

O streaming de registros de memória no Amazon Bedrock AgentCore Memory fornece notificações em tempo real quando os registros de memória são criados, atualizados ou excluídos. Em vez de pesquisar APIs para detectar alterações, você recebe eventos baseados em push em um Kinesis Data Stream em sua conta, permitindo arquiteturas orientadas por eventos que reagem às mudanças no ciclo de vida do registro de memória à medida que elas ocorrem.

Com o streaming de gravação de memória, você pode:

Como funciona

O streaming de registros de memória usa um modelo de entrega baseado em push. Quando os registros de memória são alterados, os eventos são publicados automaticamente no seu Kinesis Data Stream.

Os eventos são acionados pelas seguintes operações:

Tipos de evento de streaming

A tabela a seguir descreve os tipos de eventos de stream suportados e quando eles são acionados.

Esquema de eventos

MemoryRecordCreated / MemoryRecordUpdated

MemoryRecordCreatede MemoryRecordUpdated os eventos compartilham o mesmo esquema.

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

O memoryRecordText campo só é incluído quando o nível de conteúdo na configuração de entrega do stream está definido comoFULL_CONTENT. Consulte Configurar o nível de conteúdo do evento para obter detalhes adicionais.

MemoryRecordDeleted

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

Os eventos de exclusão contêm somente os identificadores de memória e registro, independentemente do nível de conteúdo configurado.

Pré-requisitos

Antes de configurar o streaming de gravação de memória, verifique se você tem:

Configurar o streaming

Etapa 1: Criar um fluxo de dados Kinesis

Crie um Kinesis Data Stream em sua conta em que o Amazon Bedrock AgentCore publicará eventos do ciclo de vida do registro de memória.

Você pode criar o stream usando o AWS console, o CDK ou a AWS CLI. CloudFormation Se você habilitar a criptografia do lado do servidor Kinesis, observe o ARN da chave KMS — você precisará dele para obter as permissões da função do IAM.

Etapa 2: configurar um consumidor

Configure um consumidor para processar eventos do seu Kinesis Data Stream.

Conceda ao seu consumidor AmazonKinesisReadOnlyAccess (ou permissões equivalentes) e adicione o Kinesis Data Stream como acionador.

Etapa 3: criar um perfil do IAM

Crie uma função do IAM que o Amazon Bedrock AgentCore possa assumir para publicar eventos no seu Kinesis Data Stream.

Política de confiança:

{
"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/*"
        }
      }
    }
  ]
}

Política de permissões:

Para estratégias de memória incorporada, a política de permissões tem a seguinte aparência:

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

Para estratégias de memória personalizadas, a política de permissões tem a seguinte aparência:

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

Se o seu Kinesis Data Stream usa criptografia do lado do servidor, adicione o seguinte à política de permissões:

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

Etapa 4: criar uma memória com o streaming ativado

Use a CreateMemory API para criar uma Amazon Bedrock AgentCore Memory com um recurso de entrega de stream. Você deve fornecer o memoryExecutionRoleArn ao especificar um recurso de entrega de stream.

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

Etapa 5: verifique sua integração de streaming

Quando você cria uma memória com streaming ativado, o Amazon Bedrock AgentCore Memory valida a configuração e as permissões. Após a validação bem-sucedida, um StreamingEnabled evento é publicado no seu Kinesis Data Stream.

Verifique se há um evento de validação em seu consumidor no seguinte formato:

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

Configurar o nível de conteúdo do evento

O contentConfigurations campo controla quais dados são incluídos em cada evento. Você pode escolher entre dois níveis de conteúdo:

Use METADATA_ONLY para notificações de eventos leves, nas quais você só precisa saber que ocorreu uma alteração. Use FULL_CONTENT quando seu processamento posterior precisar do texto do registro de memória sem fazer chamadas adicionais à API.

Teste sua implementação

Etapa 1: criar eventos de teste

Use as APIs do Data Plane para gerar eventos do ciclo de vida do registro de memória e verificar se eles aparecem em seu consumidor.

Crie eventos por meio da memória de curto prazo (aciona a extração assíncrona):

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

Crie registros diretamente:

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

Etapa 2: verificar a entrega

Verifique seu consumidor para confirmar se os eventos estão sendo recebidos. Você deve ver MemoryRecordCreated eventos para registros criados por meio de qualquer um dos métodos.

Você também pode monitorar a integridade da entrega usando métricas e registros.

Você pode usar a ListMemoryRecords API para fazer referência cruzada:

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

Gerenciar a configuração de streaming

Atualizar a configuração de streaming

Use a UpdateMemory API para modificar ou remover o recurso de entrega de stream.

Remova o streaming:

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

Alterar o nível do conteúdo

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

Observabilidade

A Amazon Bedrock AgentCore Memory vende CloudWatch métricas e registros para sua AWS conta, oferecendo visibilidade sobre a integridade e o status da entrega do stream de registros de memória.

Metrics

As métricas são publicadas em sua conta no AWS/Bedrock-AgentCore namespace.

Todas as métricas são emitidas como Count unidades com as seguintes dimensões:

Logs

A Amazon Bedrock AgentCore Memory vende registros para sua conta quando ocorrem falhas de publicação no terminal (que não podem ser repetidas).