View a markdown version of this page

Metadados estruturados para memórias de longo prazo - Amazon Bedrock AgentCore

Metadados estruturados para memórias de longo prazo

A filtragem de metadados no Amazon Bedrock AgentCore Memory permite que você adicione atributos estruturados aos seus registros de memória de longo prazo. Você pode usar esses atributos para restringir quais registros são retornados durante a recuperação. Os namespaces já isolam as memórias por entidade primária (usuário, inquilino, paciente, cliente). No entanto, em um único namespace, uma ampla pesquisa semântica retorna tudo o que tem um significado próximo. Com a filtragem de metadados, você pode recuperar somente resultados que correspondam a valores de atributos específicos. Por exemplo, você pode recuperar somente registros de alta prioridade, somente registros de um departamento específico ou somente registros criados dentro de um determinado intervalo de tempo.

Com a filtragem de metadados, você pode:

  • Recuperação do escopo por dimensões de negócios (prioridade, departamento, canal, intervalo de tempo) em um namespace

  • Anexe metadados estruturados a eventos e registros de memória no momento da criação

  • Faça com que o modelo de linguagem grande (LLM) extraia automaticamente os metadados do conteúdo conversacional durante a ingestão de memória

  • Restrinja LLM-extracted os valores a valores específicos para uma filtragem consistente

  • Combine até 5 filtros por consulta em RetrieveMemoryRecords ouListMemoryRecords, aplicados com AND lógica

  • Filtre os timestamps gerados pelo sistema (x-amz-agentcore-memory-createdAt,x-amz-agentcore-memory-updatedAt) sem declarar chaves indexadas adicionais

Introdução

A configuração da filtragem de metadados envolve cinco etapas:

  1. Crie sua memória com chaves indexadas e um esquema de metadados

    • Chaves indexadas — Use CreateMemory (ouUpdateMemory) para declarar as chaves de metadados que você deseja filtrar (por exemplo,,priority,channel). tags Você pode declarar até 10 chaves indexadas por memória. As chaves indexadas definem quais atributos podem ser consultados em expressões de filtro. Depois que uma chave indexada é adicionada, ela não pode ser removida.

    • Esquema de metadados — Defina uma metadataSchema estratégia para controlar como o LLM extrai valores das conversas. O esquema especifica quais chaves extrair, como resolver conflitos entre eventos e quais restrições de validação aplicar. Um esquema de metadados é opcional — estratégias sem um não realizam a extração de metadados.

  2. Verifique a configuração — Use GetMemory para confirmar se as chaves indexadas e os esquemas de metadados da estratégia estão configurados corretamente.

  3. Ingira dados com metadados — envie eventos usando CreateEvent metadados opcionais ou forneça metadados diretamente nos registros usando. BatchCreateMemoryRecords Para ingestão orientada por eventos, o LLM extrai e preenche automaticamente os metadados nos registros de memória resultantes. Essa extração é baseada no esquema de metadados da estratégia e no conteúdo da conversa, mesmo quando nenhum metadado é anexado aos eventos.

  4. Consulta com filtros de metadados — Use metadataFilters on RetrieveMemoryRecords (pesquisa semântica com pré-filtragem) ou ListMemoryRecords (filtragem somente de metadados) para definir o escopo dos resultados.

  5. Evolua seu esquema ao longo do tempo — adicione novas chaves indexadas ou modifique os esquemas de metadados da estratégia à medida que suas necessidades de filtragem aumentam.

As seções subsequentes descrevem cada etapa detalhadamente.

Principais conceitos

Chaves de metadados indexadas

As chaves indexadas são declaradas no nível do recurso de memória em CreateMemory (ou adicionadas posteriormente por meio deUpdateMemory). As chaves indexadas são armazenadas em um formato otimizado para filtragem rápida de consultas. Somente chaves indexadas podem ser consultadas em e. metadataFilters ListMemoryRecords RetrieveMemoryRecords

O exemplo a seguir declara duas chaves indexadas:

{ "indexedKeys": [ { "key": "priority", "type": "STRING" }, { "key": "tags", "type": "STRINGLIST" } ] }

typeValores suportados:STRING,STRINGLIST,NUMBER.

As chaves devem corresponder ^[a-zA-Z0-9\s._:/=+@-]*$ (máximo de 128 caracteres).

Adicionar uma chave indexada não preenche os registros existentes. Somente registros criados ou atualizados após a declaração da chave são indexados para essa chave. Para obter mais detalhes sobre a evolução do seu esquema ao longo do tempo, consulte. Etapa 5: evolua seu esquema de metadados

Esquema de metadados (por estratégia)

Opcionalmente, a estratégia de memória pode ter um esquema de metadados declarado em. memoryRecordSchema.metadataSchema O esquema de metadados informa ao LLM quais metadados extrair do conteúdo conversacional ao gerar registros de memória. Somente as chaves definidas no esquema de metadados da estratégia são preenchidas nos registros de memória resultantes durante a extração orientada por eventos.

Cada entrada no esquema define:

  • key— O nome da chave de metadados. Se essa chave também for declarada como uma chave indexada, o valor extraído poderá ser filtrado. Se não for uma chave indexada, o valor ainda estará preenchido no registro e visível nas GetMemoryRecord ListMemoryRecords respostas, mas não poderá ser usado em expressões de filtro.

  • type— O tipo de valor (STRING,STRINGLIST,NUMBER).

  • definition(obrigatório) — Uma descrição em linguagem natural do que o campo representa. Seja específico — em vez de “A prioridade”, escreva “Nível de prioridade do problema com base no impacto no cliente”. Os valores variam de críticos (mais graves) a baixos (menos graves).”

  • llmExtractionInstruction(opcional) — Orientação adicional sobre como o LLM deve extrair ou resolver valores. Você pode usar o integrado LATEST_VALUE (mantém o valor mais recente) ou fornecer instruções personalizadas em linguagem natural, como “Classifique com base no impacto nos negócios: use critical para interrupções de serviço que afetam a produção, high para desempenho degradado, para solicitações de recursos, medium para documentação ou problemas cosméticos”. low

  • validation(opcional) — Restringe a saída do LLM a um conjunto controlado de valores. Sem validação, o LLM pode produzir "High""high", ou "HIGH" pelo mesmo conceito, quebrar a correspondência de filtros.

O exemplo a seguir mostra uma entrada do esquema de metadados com validação:

{ "metadataSchema": [ { "key": "priority", "type": "STRING", "extractionConfig": { "llmExtractionConfig": { "definition": "Issue priority level based on customer impact. Values range from critical (most severe) to low (least severe).", "llmExtractionInstruction": "LATEST_VALUE", "validation": { "stringValidation": { "allowedValues": ["critical", "high", "medium", "low"] } } } } } ] }

Opções de validação por tipo:

Tipo Validação Description

STRING

stringValidation.allowedValues

Restringir a um conjunto fixo (máximo de 10 valores, cada um máximo de 256 caracteres, correspondendo^[a-zA-Z0-9\s._:/=+@-]*$)

STRINGLIST

stringListValidation.allowedValues

Restrinja os membros da lista a um conjunto fixo (máximo de 10 valores, cada um com no máximo 256 caracteres, correspondendo^[a-zA-Z0-9\s._:/=+@-]*$)

STRINGLIST

stringListValidation.maxItems

Máximo de itens na lista (1—5)

NUMBER

numberValidation.minValue

Valor mínimo permitido

NUMBER

numberValidation.maxValue

Valor máximo permitido

Metadados determinísticos (tipo de extração STRICTLY_CONSISTENT)

As chaves de metadados determinísticos contêm valores que seu aplicativo já conhece ao criar um evento. Esses valores são copiados exatamente para os registros de memória resultantes sem modificação. Classificadores organizacionais como departmentcompliance_level, ou não agent_id devem ser inferidos pelo LLM. A inferência do LLM introduz variabilidade. Por exemplo, a mesma conversa pode ser produzida "eng" em um registro e "Engineering" em outro.

Para essas chaves, extractionType defina como STRICTLY_CONSISTENT na entrada do esquema de metadados. O valor fornecido no evento se propaga inalterado por meio de extração e consolidação. O LLM não é consultado para essa chave.

O JSON a seguir mostra um esquema de metadados com ambos os STRICTLY_CONSISTENT tipos de extração: LLM_INFERRED

{ "metadataSchema": [ { "key": "department", "type": "STRING", "extractionType": "STRICTLY_CONSISTENT" }, { "key": "compliance_level", "type": "STRING", "extractionType": "STRICTLY_CONSISTENT" }, { "key": "topic", "type": "STRING", "extractionType": "LLM_INFERRED", "extractionConfig": { "llmExtractionConfig": { "definition": "Primary topic of the conversation", "llmExtractionInstruction": "Identify the main topic discussed" } } } ] }

Quando você omiteextractionType, o padrão éLLM_INFERRED.

Isolamento de extração e consolidação

STRICTLY_CONSISTENTas chaves fazem mais do que ignorar a inferência do LLM. Eles agrupam eventos por seus valores determinísticos durante a extração. Eventos com valores diferentes são processados separadamente. A consolidação segue a mesma regra. Os registros de um grupo de valores nunca são mesclados com registros de outro grupo.

O exemplo de Python a seguir mostra uma sessão de suporte com duas chaves determinísticas (departmente): priority

# Event 1: high-priority billing inquiry agentcore_client.create_event( memoryId="mem-support-abc123", actorId="customer-123", sessionId="session-escalation-001", payload=[{"conversational": {"role": "USER", "content": {"text": "I'm seeing duplicate charges on my invoice and it's blocking our deployment."}}}], metadata={ "department": {"stringValue": "billing"}, "priority": {"stringValue": "high"} } ) # Event 2: also high-priority billing (same deterministic values as Event 1) agentcore_client.create_event( memoryId="mem-support-abc123", actorId="customer-123", sessionId="session-escalation-001", payload=[{"conversational": {"role": "USER", "content": {"text": "The charges appeared after we upgraded from standard to enterprise tier last week."}}}], metadata={ "department": {"stringValue": "billing"}, "priority": {"stringValue": "high"} } ) # Event 3: high-priority engineering (same priority, different department) agentcore_client.create_event( memoryId="mem-support-abc123", actorId="customer-123", sessionId="session-escalation-001", payload=[{"conversational": {"role": "USER", "content": {"text": "Your team found a provisioning bug that triggered the duplicate charge."}}}], metadata={ "department": {"stringValue": "engineering"}, "priority": {"stringValue": "high"} } ) # Event 4: low-priority billing (same department as Events 1-2, different priority) agentcore_client.create_event( memoryId="mem-support-abc123", actorId="customer-123", sessionId="session-escalation-001", payload=[{"conversational": {"role": "USER", "content": {"text": "Also, can you update the billing contact email on file when you get a chance?"}}}], metadata={ "department": {"stringValue": "billing"}, "priority": {"stringValue": "low"} } )

O sistema agrupa eventos pela combinação exata de todos os valores-chave determinísticos:

  • Os eventos 1 e 2 compartilhamdepartment=billing, priority=high. Eles são extraídos juntos.

  • O evento 3 difere emdepartment. Ele é extraído separadamente, apesar do compartilhamentopriority=high.

  • O evento 4 é diferente empriority. Ele é extraído separadamente, apesar do compartilhamentodepartment=billing.

Todos os valores-chave determinísticos devem corresponder para que os eventos sejam agrupados. Uma consulta com department=billing AND priority=high retorna somente os fatos urgentes da cobrança duplicada. Os outros eventos estão em partições separadas. Registros de combinações de valores diferentes nunca são mesclados durante a consolidação.

Restrições

Restrição Detalhes

Máximo de chaves determinísticas por estratégia

3

Tipo de chave

Deve ser STRING

Deve ser indexado

A chave também deve ser declarada na memória indexedKeys

Não extractionConfig

STRICTLY_CONSISTENTas chaves não podem ter umextractionConfig. O valor vem do evento, não do LLM.

Estratégias suportadas

Estratégias semânticas, de preferência do usuário e episódicas (incluindo substituições personalizadas). Não é suportado em estratégias resumidas.

Valores ausentes

Se um evento chegar sem um valor para uma chave determinística, a chave será omitida do agrupamento desse evento e ausente no registro resultante.

Importante

Alterar quais chaves são configuradas como STRICTLY_CONSISTENT altera o agrupamento usado para extração e consolidação. Os registros criados na configuração anterior ficam isolados dos registros criados na nova configuração. Planeje sua configuração de chave determinística antes de ingerir eventos.

Como as chaves indexadas e as chaves do esquema interagem

A relação entre chaves indexadas e chaves de esquema determina como os metadados se comportam:

  • Indexado + no esquema — A chave é preenchida nos registros extraídos pelo LLM e pode ser filtrada em expressões de consulta. Essa é a configuração mais comum para chaves que você deseja extrair e filtrar.

  • Indexado ou não no esquema — A chave não é preenchida nos registros durante a extração orientada por eventos. Os filtros nessa chave não retornam resultados para os registros extraídos. Para preencher essas chaves, use as APIs Batch (BatchCreateMemoryRecordsouBatchUpdateMemoryRecords).

  • No esquema + não indexado — O LLM extrai e preenche o valor nos registros, e ele fica visível nas respostas. GetMemoryRecord ListMemoryRecords No entanto, ele não pode ser usado em expressões de filtro. Isso é útil para enriquecimento de contexto — metadados como sentiment ou summary_notes que enriquecem o registro para consumo posterior sem consumir seu orçamento de chave indexada.

Como os metadados fluem de eventos para registros de memória

Os metadados do evento aceitam somente stringValue entradas. Suporte stringValue e numberValue tipos de registros de memória — preenchidos pelo LLM durante a extração ou fornecidos diretamente por meio das APIs Batch. stringListValue O dateTimeValue tipo é reservado para campos gerados pelo sistema (x-amz-agentcore-memory-createdAtex-amz-agentcore-memory-updatedAt). Somente as chaves definidas na estratégia metadataSchema são preenchidas nos registros extraídos — as chaves de metadados do evento que não estão no esquema são ignoradas. Para limites de entrada, consulteCotas.

System-generated metadados

Cada registro de memória carrega esses campos do sistema, que podem ser consultados com os mesmos operadores de filtro:

Campo Tipo Description

x-amz-agentcore-memory-recordType

stringValue

O tipo do registro de memória

x-amz-agentcore-memory-createdAt

dateTimeValue

Carimbo de data/hora da criação do registro

x-amz-agentcore-memory-updatedAt

dateTimeValue

Registrar data e hora da última atualização

Você não precisa declará-las como chaves indexadas — elas estão sempre disponíveis para filtragem. Esses dateTimeValue campos gerados pelo sistema oferecem suporte BEFORE e AFTER operadores, permitindo consultas por intervalo de tempo sem exigir que você declare chaves indexadas de data e hora.

Pré-requisitos

Antes de configurar a filtragem de metadados, verifique se você tem:

  • Uma AWS conta com permissões para ligar para CreateMemoryUpdateMemory,CreateEvent,ListMemoryRecords,RetrieveMemoryRecords,BatchCreateMemoryRecords, e BatchUpdateMemoryRecords

  • Acesso ao Amazon Bedrock AgentCore

  • Uma visão clara das dimensões de filtro de 3 a 5 que seu agente mais precisa (departamento, prioridade, região, projeto etc.)

Etapa 1: criar uma memória com chaves indexadas e um esquema de metadados

O seguinte cria uma memória de suporte ao cliente com cinco chaves indexadas e um esquema de metadados. priority,agent_type, e sentiment são definidos no esquema de metadados da estratégia — o LLM extrai seus valores do conteúdo da conversa. Observe que sentiment está no esquema, mas não é declarado como uma chave indexada: o LLM deriva seu valor das conversas e o preenche nos registros, mas não pode ser usado em expressões de filtro. tags(STRINGLIST), channel (STRING) e ticket_id (STRING) são declaradas como chaves indexadas, mas não estão no esquema. Elas não são preenchidas durante a extração orientada por eventos, mas podem ser fornecidas por meio das APIs Batch.

aws bedrock-agentcore-control create-memory \ --name "CustomerSupportMemory" \ --event-expiry-duration 30 \ --indexed-keys '[ {"key": "priority", "type": "STRING"}, {"key": "agent_type", "type": "STRING"}, {"key": "tags", "type": "STRINGLIST"}, {"key": "channel", "type": "STRING"}, {"key": "ticket_id", "type": "STRING"} ]' \ --memory-strategies '[ { "semanticMemoryStrategy": { "name": "SupportSemanticStrategy", "description": "Captures support interaction details", "namespaceTemplates": ["support/{actorId}"], "memoryRecordSchema": { "metadataSchema": [ { "key": "priority", "type": "STRING", "extractionConfig": { "llmExtractionConfig": { "definition": "Issue priority level based on customer impact. Values range from critical (most severe) to low (least severe).", "llmExtractionInstruction": "LATEST_VALUE", "validation": { "stringValidation": { "allowedValues": ["critical", "high", "medium", "low"] } } } } }, { "key": "agent_type", "type": "STRING", "extractionConfig": { "llmExtractionConfig": { "definition": "Support agent classification.", "llmExtractionInstruction": "Prefer the most specialized agent type. Hierarchy: specialist > tier3 > tier2 > tier1 > bot." } } }, { "key": "sentiment", "type": "STRING", "extractionConfig": { "llmExtractionConfig": { "definition": "Customer sentiment during the interaction.", "llmExtractionInstruction": "LATEST_VALUE", "validation": { "stringValidation": { "allowedValues": ["positive", "neutral", "negative", "frustrated"] } } } } } ] } } } ]'

Etapa 2: verificar a configuração

Use GetMemory para confirmar que as chaves indexadas e o esquema de metadados foram aceitos:

aws bedrock-agentcore-control get-memory --memory-id "<memory-id>"

Etapa 3: ingerir dados com metadados

Há dois caminhos para colocar metadados em registros de memória.

Event-driven ingestão

Anexe stringValue metadados aos eventos no momento da criação. O LLM usa o esquema de metadados da estratégia para extrair e preencher metadados nos registros de memória resultantes. Somente as chaves definidas na estratégia metadataSchema são preenchidas nos registros resultantes — as chaves de metadados do evento que não estão no esquema são ignoradas durante a extração.

aws bedrock-agentcore create-event \ --memory-id "<memory-id>" \ --actor-id "customer-123" \ --session-id "session-001" \ --event-timestamp "$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")" \ --metadata '{ "priority": {"stringValue": "high"}, "channel": {"stringValue": "email"}, "ticket_id": {"stringValue": "TKT-5001"} }' \ --payload '[ {"conversational": {"role": "USER", "content": {"text": "I have a billing issue that is blocking my production deployment"}}}, {"conversational": {"role": "ASSISTANT", "content": {"text": "I understand this is urgent. Let me escalate to our billing specialist team."}}} ]'

Neste exemplo, priority está na estratégiametadataSchema, então seu valor se propaga para o registro de memória. channele não ticket_id estão no esquema, então são ignorados durante a extração. O LLM também infere agent_type (provavelmente "specialist" com base na escalação) e sentiment (provavelmente"frustrated") a partir do conteúdo da conversa — essas chaves de esquema são preenchidas mesmo que não tenham sido fornecidas como metadados do evento.

Extração implícita de metadados do conteúdo da conversa

Os metadados do evento não são necessários para que as chaves do esquema produzam valores. Quando uma chave de esquema não tem metadados correspondentes nos eventos de origem, o LLM deriva o valor inteiramente do conteúdo da conversa. Ele usa a chave definition e llmExtractionInstruction para determinar o valor. Isso é útil para dimensões que só existem na conversa em si, sem exigir que os chamadores as forneçam no momento da criação do evento.

Usando a mesma memória de suporte ao cliente da Etapa 1, o evento a seguir não tem nenhum metadado:

aws bedrock-agentcore create-event \ --memory-id "<memory-id>" \ --actor-id "customer-789" \ --session-id "session-002" \ --event-timestamp "$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")" \ --payload '[ {"conversational": {"role": "USER", "content": {"text": "My production deployment is down because of a billing hold on our account"}}}, {"conversational": {"role": "ASSISTANT", "content": {"text": "I understand the urgency. Let me connect you with our billing specialist team right away."}}} ]'

O LLM analisa o conteúdo da conversa e preenche todas as três chaves de esquema no registro de memória extraído —priority,agent_type, e sentiment — mesmo que nenhuma tenha sido fornecida como metadado do evento:

{ "content": {"text": "Customer reported a production outage caused by a billing hold. Escalated to billing specialist."}, "metadata": { "priority": {"stringValue": "critical"}, "agent_type": {"stringValue": "specialist"}, "sentiment": {"stringValue": "frustrated"} } }

As regras de validação ainda se aplicam — a saída do LLM é restrita aos valores permitidos especificados, independentemente de o valor ter vindo de metadados de eventos ou inferência de conteúdo.

Como o LLM resolve conflitos entre eventos

Quando vários eventos em uma sessão carregam valores diferentes para a mesma chave de metadados, o LLM usa o. llmExtractionInstruction Isso determina qual valor manter no registro de memória resultante.

Por exemplo, considere uma sessão de suporte em que o primeiro evento tenha ocorrido priority: "low" e um evento posterior aumente parapriority: "critical". O LLM resolve isso com base na instrução:

  • LATEST_VALUE(embutido) — O LLM mantém o valor mais recente. Nesse caso, o registro de memória é obtidopriority: "critical".

  • Instruções personalizadas — Você pode expressar a lógica específica do domínio. Por exemplo, “Manter a severidade mais alta relatada durante a sessão” também produziria"critical", mas por um motivo diferente: é a severidade mais alta, não apenas a mais recente.

Outro exemplo: para agent_type com a instrução “Prefira o tipo de agente mais especializado”. Hierarquia: expert > tier3 > tier2 > tier1 > bot”, se uma sessão começar com um bot e escalar para um agente de nível 2, o registro de memória será obtido. agent_type: "tier2"

Ingestão determinística de metadados

As chaves configuradas como STRICTLY_CONSISTENT seguem um caminho de ingestão diferente. O valor que você fornece no evento é o valor que cai no registro resultante. Não há inferência de LLM nem resolução de conflitos.

AgentCore A memória agrupa eventos por seus valores-chave determinísticos antes da extração. Por exemplo, eventos marcados department: "engineering" são processados separadamente dos eventos marcadosdepartment: "finance".

A consolidação opera dentro desses grupos. Um registro que compliance_level: "hipaa" nunca se funde com um registro rotuladocompliance_level: "standard". Isso torna as chaves determinísticas ideais para:

  • Isolamento de conformidade - registros com diferentes níveis de conformidade nunca se misturam.

  • Roteamento organizacional - Department-scoped recuperação sem contaminação cruzada.

  • Multi-tenant subfiltragem - Tenant-specific atributos preservados exatamente como fornecidos.

Se um evento não tiver valor para uma chave determinística, a chave estará ausente no registro resultante.

Os caminhos de gravação direta (BatchCreateMemoryRecordseBatchUpdateMemoryRecords) ignoram a extração. O tipo de STRICTLY_CONSISTENT extração não tem efeito sobre eles. Forneça metadados diretamente, como você já faz para essas APIs.

Criação direta de registros com Batch APIs

Para importações de base de conhecimento, estratégias autogerenciadas ou conteúdo pré-processado, use BatchCreateMemoryRecords (ouBatchUpdateMemoryRecords) para fornecer metadados explicitamente. Isso ignora totalmente a extração do LLM — o chamador controla os valores dos metadados.

A forma como os metadados são tratados nos registros criados em lote depende de você fornecer: memoryStrategyId

  • Com memoryStrategyId — O serviço filtra os metadados de entrada em relação aos dessa estratégiamemoryRecordSchema. Somente as chaves definidas no esquema são armazenadas no registro. Todas as outras chaves, incluindo chaves indexadas que não estão no esquema, são descartadas silenciosamente. Isso proporciona consistência imposta pelo esquema, garantindo que os registros criados em lote tenham o mesmo formato de metadados dos registros produzidos pela extração orientada por eventos.

  • Sem memoryStrategyId — O serviço armazena todas as chaves de metadados na carga como estão no registro. Isso inclui chaves indexadas, chaves que estão em um esquema de estratégia e chaves que não estão em nenhum dos dois. No entanto, somente as chaves indexadas são filtráveis — a tentativa de filtrar em uma chave não indexada retorna uma. ValidationException Non-indexed as chaves ainda estão visíveis GetMemoryRecord nas ListMemoryRecords respostas.

O exemplo a seguir cria um registro sem memoryStrategyId armazenar todos os metadados fornecidos:

aws bedrock-agentcore batch-create-memory-records \ --memory-id "<memory-id>" \ --records '[{ "requestIdentifier": "import-001", "namespaces": ["support/customer-456"], "content": {"text": "Customer prefers phone support for urgent billing issues"}, "timestamp": "2026-01-15T10:00:00Z", "metadata": { "priority": {"stringValue": "high"}, "agent_type": {"stringValue": "billing_agent"}, "channel": {"stringValue": "phone"}, "ticket_id": {"stringValue": "TKT-7890"} } }]'

Para impor a consistência do esquema, inclua o. memoryStrategyId Nesse caso, somente as chaves presentes nessa estratégia memoryRecordSchema são mantidas:

aws bedrock-agentcore batch-create-memory-records \ --memory-id "<memory-id>" \ --records '[{ "requestIdentifier": "import-002", "namespaces": ["support/customer-456"], "memoryStrategyId": "<strategy-id>", "content": {"text": "Billing dispute resolved after account credit applied"}, "timestamp": "2026-01-16T14:00:00Z", "metadata": { "priority": {"stringValue": "medium"}, "agent_type": {"stringValue": "billing_agent"}, "channel": {"stringValue": "phone"} } }]'

No segundo exemplo, se o esquema da estratégia definir apenaspriority,, e agent_typesentiment, então será channel removido silenciosamente do registro armazenado.

Atualizando registros com BatchUpdateMemoryRecords

BatchUpdateMemoryRecordssegue o mesmo comportamento de filtragem de memoryStrategyId metadados de. BatchCreateMemoryRecords O exemplo a seguir atualiza o conteúdo e os metadados de um registro existente:

aws bedrock-agentcore batch-update-memory-records \ --memory-id "<memory-id>" \ --records '[{ "memoryRecordId": "<record-id>", "namespaces": ["support/customer-456"], "content": {"text": "Customer prefers phone support for urgent billing issues. Account credit applied."}, "metadata": { "priority": {"stringValue": "critical"}, "agent_type": {"stringValue": "billing_agent"}, "channel": {"stringValue": "phone"} } }]'

Etapa 4: consultar com filtros de metadados

Os filtros de metadados são aplicados antes da execução da pesquisa de similaridade vetorial (pré-filtragem). Isso reduz o candidato definido primeiro. Como resultado, a pesquisa de K-nearest vizinhos (KNN) opera em um subconjunto menor e mais relevante.

Estrutura Filter

Cada filtro é uma { left, operator, right } expressão:

{ "left": { "metadataKey": "priority" }, "operator": "EQUALS_TO", "right": { "metadataValue": { "stringValue": "high" } } }

Até 5 filtros podem ser combinados por consulta. Vários filtros são aplicados com AND lógica.

Operadores compatíveis

Operador É necessário o valor correto Funciona com Description

EQUALS_TO

Sim

STRING, NÚMERO

Combinação exata.

CONTAINS

Sim

LISTA DE STRINGS

Retorna registros em que qualquer elemento na STRINGLIST contém a string fornecida como uma correspondência exata.

EXISTS

Não

Todos os tipos

A chave está presente no registro

NOT_EXISTS

Não

Todos os tipos

A chave está ausente do registro

GREATER_THAN

Sim (numberValue)

NUMBER

Comparação numérica maior que a

GREATER_THAN_OR_EQUALS

Sim (numberValue)

NUMBER

Comparação numérica maior que ou igual

LESS_THAN

Sim (numberValue)

NUMBER

Comparação numérica menor que

LESS_THAN_OR_EQUALS

Sim (numberValue)

NUMBER

Comparação numérica menor que ou igual

BEFORE

Sim (dateTimeValue)

encontro TimeValue

O timestamp é anterior ao valor fornecido

AFTER

Sim (dateTimeValue)

encontro TimeValue

O carimbo de data/hora é posterior ao valor fornecido

Observação: os metadados do evento ListEvents filtram somente no suporteEXISTS,NOT_EXISTS, eEQUALS_TO, e somentestringValue.

Recupere com filtros de metadados (pesquisa semântica + pré-filtro)

AtivadoRetrieveMemoryRecords, metadataFilters está aninhado por dentrosearchCriteria. O exemplo a seguir define o escopo dos resultados para registros de alta prioridade do ano atual, antes que a pesquisa semântica corresponda aos “problemas de cobrança”:

aws bedrock-agentcore retrieve-memory-records \ --memory-id "<memory-id>" \ --namespace "support/customer-123" \ --search-criteria '{ "searchQuery": "billing issues", "topK": 10, "metadataFilters": [ { "left": {"metadataKey": "priority"}, "operator": "EQUALS_TO", "right": {"metadataValue": {"stringValue": "high"}} }, { "left": {"metadataKey": "x-amz-agentcore-memory-createdAt"}, "operator": "AFTER", "right": {"metadataValue": {"dateTimeValue": "2026-01-01T00:00:00Z"}} } ] }'

A combinação de um filtro de metadados personalizado com um carimbo de data/hora gerado pelo sistema compacta o conjunto de candidatos em duas dimensões — prioridade comercial e atualidade — antes que a pesquisa por similaridade seja executada.

Lista com filtros de metadados (sem pesquisa semântica)

ListMemoryRecordsfornece filtragem de metadados sem pesquisa semântica. Isso é útil quando você precisa enumerar registros que correspondam a critérios específicos de metadados — por exemplo, listar todos os registros de alta prioridade de um cliente ou extrair todos os registros criados após uma data específica.

ListMemoryRecordsAtivado, metadataFilters é um parâmetro de nível superior:

aws bedrock-agentcore list-memory-records \ --memory-id "<memory-id>" \ --namespace "support/customer-123" \ --metadata-filters '[ { "left": {"metadataKey": "priority"}, "operator": "EQUALS_TO", "right": {"metadataValue": {"stringValue": "high"}} }, { "left": {"metadataKey": "x-amz-agentcore-memory-createdAt"}, "operator": "AFTER", "right": {"metadataValue": {"dateTimeValue": "2026-01-20T00:00:00Z"}} } ]'

Combinando vários filtros

Essa consulta abrange a recuperação das discussões sobre ações do terceiro trimestre de 2026 em um namespace de cliente específico:

{ "searchQuery": "portfolio rebalancing strategy", "topK": 10, "metadataFilters": [ { "left": {"metadataKey": "asset_class"}, "operator": "EQUALS_TO", "right": {"metadataValue": {"stringValue": "equities"}} }, { "left": {"metadataKey": "x-amz-agentcore-memory-createdAt"}, "operator": "AFTER", "right": {"metadataValue": {"dateTimeValue": "2026-07-01T00:00:00Z"}} }, { "left": {"metadataKey": "x-amz-agentcore-memory-createdAt"}, "operator": "BEFORE", "right": {"metadataValue": {"dateTimeValue": "2026-09-30T23:59:59Z"}} } ] }

Os valores do filtro para carimbos de data/hora devem estar em UTC (formato ISO 8601). O serviço normaliza todos os timestamps armazenados para UTC antes da comparação, portanto, sempre expresse os valores do filtro em UTC.

Etapa 5: evolua seu esquema de metadados

AgentCore A memória suporta a evolução do esquema para que você possa adaptar sua configuração de metadados à medida que suas necessidades mudam.

Adicionar chaves indexadas

Você pode adicionar novas chaves indexadas a uma memória a qualquer momento:

aws bedrock-agentcore-control update-memory \ --memory-id "<memory-id>" \ --add-indexed-keys '[ {"key": "customer_segment", "type": "STRING"} ]'

Novas chaves ficam imediatamente disponíveis para eventos recebidos e registros de memória. Os registros existentes não são preenchidos — somente registros novos ou atualizados contêm a nova chave. Você não pode remover uma chave indexada anteriormente, o que evita a perda acidental da capacidade de filtragem dos dados existentes.

Modificar o esquema de metadados de uma estratégia

Você pode adicionar, remover ou atualizar entradas livremente no esquema de metadados de uma estratégia. Isso controla quais metadados o LLM extrai das conversas futuras.

Por exemplo, para adicionar um novo resolution_type campo a uma estratégia existente:

aws bedrock-agentcore-control update-memory \ --memory-id "<memory-id>" \ --memory-strategies '{ "modifyMemoryStrategies": [ { "memoryStrategyId": "<strategy-id>", "memoryRecordSchema": { "metadataSchema": [ { "key": "resolution_type", "type": "STRING", "extractionConfig": { "llmExtractionConfig": { "definition": "How the customer support issue was resolved", "validation": { "stringValidation": { "allowedValues": ["refund", "replacement", "escalation", "self-resolved"] } } } } } ] } } ] }'

Você também pode remover uma chave do esquema de metadados de uma estratégia se não quiser mais que o LLM extraia esse campo. A remoção de uma entrada do esquema interrompe a extração de novos registros, mas não afeta os metadados que já estão nos registros existentes.

Os registros de memória existentes não recebem retroativamente novos LLM-extracted campos. No entanto, quando as memórias mais antigas são consolidadas com as mais novas durante o ciclo de vida normal da memória, o registro consolidado é extraído novamente usando o esquema atual e incluirá os novos campos de metadados.

Cotas

Recurso Limite

Chaves indexadas por memória

10

Chaves STRICTLY_CONSISTENT por estratégia

3

Entradas do esquema de metadados por estratégia

20

Entradas de metadados do registro de memória (fornecidas pelo usuário)

20

Filtros por consulta

5

allowedValuespor regra de validação

10

maxItemspara STRINGLIST validação

5

definition/llmExtractionInstructioncomprimento

1000 caracteres cada

Tamanho da chave de metadados

128 caracteres

stringValuecomprimento

256 caracteres

comprimento para STRINGLIST membros

64 caracteres

Práticas recomendadas

  • Comece com 3 a 5 dimensões de filtro que afetam diretamente a qualidade da recuperação. Cada campo indexado consome a capacidade da infraestrutura de armazenamento, e o limite de 10 teclas reflete isso. Comece com três a cinco chaves que afetam diretamente a qualidade da recuperação e acrescente mais à medida que surgirem necessidades concretas.

  • Escreva definition sequências claras e específicas. O definition descreve o que o campo representa. Em vez de “A prioridade do ticket”, escreva “Nível de prioridade do problema com base no impacto no cliente”. Os valores variam de críticos (mais graves) a baixos (menos graves).” Use llmExtractionInstruction para uma lógica de extração detalhada.

  • Restrinja a saída do LLM com. validation.allowedValues Sem validação, o LLM pode produzir "High""high", ou "HIGH" pelo mesmo conceito, quebrar a correspondência de filtros.

  • Escolha regras de resolução de conflitos que correspondam à semântica do domínio. LATEST_VALUEé um padrão seguro, mas para campos como agent_type em um fluxo de trabalho de escalonamento, uma instrução personalizada que retenha o valor mais importante é mais correta.

  • Prefira o caminho orientado por eventos para conteúdo conversacional. Deixe o LLM lidar com a extração e a resolução de conflitos. Reserve as APIs Batch para importações em massa nas quais você já conhece os valores corretos de metadados.

  • Planeje esquemas no nível da estratégia. Cada estratégia pode ter a sua própriametadataSchema, permitindo que diferentes estratégias extraiam e manipulem as mesmas chaves de forma diferente. Uma estratégia semântica pode usar instruções de extração personalizadas para classificar a prioridade do contexto da conversa, enquanto uma estratégia resumida pode usar uma definição diferente ajustada para metadados específicos da sumarização.

  • Seja intencional com nenhum registro memoryStrategyId criado em lote. Quando você incluimemoryStrategyId, o serviço filtra os metadados de entrada somente para as chaves no esquema dessa estratégia — todas as outras chaves são descartadas silenciosamente. Quando você a omite, todos os metadados na carga útil são armazenados como estão. Escolha com base no seu caso de uso: consistência imposta pelo esquema para registros que devem corresponder aos registros produzidos por extração ou controle total para importações em massa, nas quais você gerencia metadados externamente.

  • Use chaves de esquema não indexadas para enriquecimento de contexto. Nem toda chave de metadados precisa ser filtrável. As chaves de esquema que não são declaradas como chaves indexadas ainda são preenchidas nos registros extraídos e visíveis nas get/list respostas — elas simplesmente não podem ser usadas em expressões de filtro. Isso é útil para metadados como sentiment ou summary_notes que enriquecem o registro para consumo posterior sem consumir seu orçamento de chaves indexadas.

  • Use a extração determinística para valores que você já conhece. Algumas chaves representam atributos organizacionais fixosdepartment, comotenant_tier, oucompliance_scope. Se o aplicativo tiver esses valores no momento da criação do evento, configure-os comoSTRICTLY_CONSISTENT. Forneça o valor em cada evento. Isso garante valores exatos nos registros e remove representações inconsistentes (como "eng" vs."Engineering") que a extração do LLM pode introduzir. Reserve LLM_INFERRED para dimensões que devem ser inferidas do conteúdo da conversa, como sentimento ou tópico.

  • Planeje os slots de chave determinísticos com antecedência. Cada STRICTLY_CONSISTENT chave usa um dos 10 slots de chave indexada. As chaves indexadas não podem ser removidas depois de adicionadas. Reserve vagas se você planeja usar metadados determinísticos.

Anti-patterns para evitar

  • Não indexe campos de texto livre de alta cardinalidade, como descrições ou nomes completos. Eles sobrecarregam o índice sem fornecer limites de filtro úteis.

  • Não use metadados para valores que mudam em cada interação. Os metadados são mais eficazes para atributos estáveis ou que mudam lentamente.

  • Não confie apenas nos metadados para o isolamento do inquilino. Um campo de tenant_id metadados sem isolamento de namespace é um modelo de segurança por meio de convenções que falha em qualquer filtro perdido. Use namespaces para owho, e metadados para owhat, e. when how urgent

  • Não use a extração LLM para valores que devem ser exatos. Se uma chave precisar conter um valor específico e conhecido (como department outicket_id), use a STRICTLY_CONSISTENT extração ou forneça-a por meio das APIs Batch. A extração de LLM pode produzir variações do mesmo conceito.