Metadatos estructurados para memorias a largo plazo
El filtrado de metadatos de Amazon Bedrock AgentCore Memory le permite añadir atributos estructurados a los registros de memoria a largo plazo. Puede usar esos atributos para restringir los registros que se devuelven durante la recuperación. Los espacios de nombres ya aíslan las memorias por entidad principal (usuario, inquilino, paciente, cliente). Sin embargo, dentro de un único espacio de nombres, una búsqueda semántica amplia devuelve todo lo que tenga un significado parecido. Con el filtrado de metadatos, solo puedes recuperar los resultados que coincidan con valores de atributos específicos. Por ejemplo, puede recuperar solo los registros de alta prioridad, solo los registros de un departamento en particular o solo los registros creados dentro de un intervalo de tiempo determinado.
Con el filtrado de metadatos, puede:
-
La recuperación del alcance por dimensiones empresariales (prioridad, departamento, canal, intervalo de tiempo) dentro de un espacio de nombres
-
Adjunte metadatos estructurados a los eventos y los registros de memoria en el momento de la creación
-
Haga que el modelo de lenguaje grande (LLM) extraiga automáticamente los metadatos del contenido conversacional durante la ingesta de memoria
-
Restrinja los LLM-extracted valores a valores específicos para un filtrado coherente
-
Combine hasta 5 filtros por consulta (activa
RetrieveMemoryRecordsoListMemoryRecordsaplicada conANDlógica) -
Filtre las marcas de tiempo generadas por el sistema (
x-amz-agentcore-memory-createdAt,x-amz-agentcore-memory-updatedAt) sin declarar claves indexadas adicionales
Introducción
La configuración del filtrado de metadatos consta de cinco pasos:
-
Cree su memoria con claves indexadas y un esquema de metadatos:
-
Claves indexadas: utilice
CreateMemory(oUpdateMemory) para declarar las claves de metadatos por las que desea filtrar (por ejemplo,,prioritychannel,tags). Puede declarar hasta 10 claves indexadas por memoria. Las claves indexadas definen qué atributos se pueden consultar en las expresiones de filtro. Una vez que se añade una clave indexada, no se puede eliminar. -
Esquema de metadatos: defina una estrategia para controlar la forma
metadataSchemaen que el LLM extrae los valores de las conversaciones. El esquema especifica qué claves extraer, cómo resolver los conflictos entre eventos y qué restricciones de validación se deben aplicar. Un esquema de metadatos es opcional; las estrategias que no lo tienen no permiten extraer los metadatos.
-
-
Compruebe la configuración: utilícelo
GetMemorypara confirmar que las claves indexadas y los esquemas de metadatos de la estrategia están configurados correctamente. -
Ingiera datos con metadatos: envíe eventos mediante
CreateEventmetadatos opcionales o suministre los metadatos directamente en los registros mediante.BatchCreateMemoryRecordsPara la ingesta basada en eventos, el LLM extrae y rellena automáticamente los metadatos de los registros de memoria resultantes. Esta extracción se basa en el esquema de metadatos de la estrategia y en el contenido de la conversación, incluso cuando no hay metadatos adjuntos a los eventos. -
Consulta con filtros de metadatos:
metadataFiltersutilízala activadaRetrieveMemoryRecords(búsqueda semántica con prefiltrado) oListMemoryRecords(filtrado solo de metadatos) para evaluar los resultados. -
Haga evolucionar su esquema con el tiempo: añada nuevas claves indexadas o modifique los esquemas de metadatos de las estrategias a medida que aumenten sus necesidades de filtrado.
En las secciones siguientes se explica cada paso en detalle.
Conceptos clave
Claves de metadatos indexadas
Las claves indexadas se declaran a nivel de recursos de memoria CreateMemory (o se añaden posteriormente medianteUpdateMemory). Las claves indexadas se almacenan en un formato optimizado para un filtrado rápido de consultas. Solo las claves indexadas se pueden consultar de una sola vez. metadataFilters ListMemoryRecords RetrieveMemoryRecords
El siguiente ejemplo declara dos claves indexadas:
{ "indexedKeys": [ { "key": "priority", "type": "STRING" }, { "key": "tags", "type": "STRINGLIST" } ] }
typeValores admitidos:STRING,STRINGLIST,NUMBER.
Las claves deben coincidir ^[a-zA-Z0-9\s._:/=+@-]*$ (máximo 128 caracteres).
Añadir una clave indexada no rellena los registros existentes. Solo los registros creados o actualizados después de declarar la clave se indexan para esa clave. Para obtener más información sobre la evolución del esquema a lo largo del tiempo, consultePaso 5: evolucione su esquema de metadatos.
Esquema de metadatos (por estrategia)
La estrategia de memoria puede tener opcionalmente un esquema de metadatos declarado enmemoryRecordSchema.metadataSchema. El esquema de metadatos indica al LLM qué metadatos debe extraer del contenido conversacional al generar registros de memoria. Durante la extracción basada en eventos, solo las claves definidas en el esquema de metadatos de la estrategia se rellenan en los registros de memoria resultantes.
Cada entrada del esquema define:
-
key— El nombre de la clave de metadatos. Si esta clave también se declara como clave indexada, el valor extraído se puede filtrar. Si no es una clave indexada, el valor se sigue rellenando en el registro y es visible en lasListMemoryRecordsrespuestasGetMemoryRecordy, sin embargo, no se puede usar en las expresiones de filtro. -
type— El tipo de valor (STRING,STRINGLIST,NUMBER). -
definition(obligatorio): descripción en lenguaje natural de lo que representa el campo. Sea específico: en lugar de «La prioridad», escriba «El nivel de prioridad de la emisión en función del impacto en el cliente». Los valores van desde críticos (más graves) hasta bajos (menos graves)». -
llmExtractionInstruction(opcional): orientación adicional sobre cómo el LLM debe extraer o resolver los valores. Puede utilizar la versión integradaLATEST_VALUE(conserva el valor más reciente) o proporcionar instrucciones personalizadas en lenguaje natural, como «Clasifique en función del impacto en el negocio: utilícelocriticalpara las interrupciones del servicio que afecten a la producción,highpara reducir el rendimiento, para solicitar funciones,mediumpara problemas de documentación o delowestética». -
validation(opcional): restringe la salida del LLM a un conjunto controlado de valores. Sin validación, el LLM puede producir"High", o"HIGH"por el mismo concepto"high", interrumpir la coincidencia de filtros.
El siguiente ejemplo muestra una entrada de esquema de metadatos con validación:
{ "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"] } } } } } ] }
Opciones de validación por tipo:
| Tipo | Validación | Description (Descripción) |
|---|---|---|
|
|
|
Restringir a un conjunto fijo (máximo de 10 valores, cada uno de 256 caracteres como máximo, coincidentes |
|
|
|
Restrinja los miembros de la lista a un conjunto fijo (máximo de 10 valores, cada uno con un máximo de 256 caracteres, coincidentes) |
|
|
|
Número máximo de elementos de la lista (de 1 a 5) |
|
|
|
Valor mínimo permitido |
|
|
|
Valor máximo permitido |
Metadatos deterministas (tipo de extracción STRICTLY_CONSISTENT)
Las claves de metadatos deterministas contienen valores que la aplicación ya conoce al crear un evento. Estos valores se copian exactamente en los registros de memoria resultantes sin modificarlos. El LLM no agent_id debe inferir clasificadores organizacionales como departmentcompliance_level, o no. La inferencia LLM introduce variabilidad. Por ejemplo, la misma conversación puede producirse "eng" en un registro y "Engineering" en otro.
Para estas claves, extractionType establézcalas STRICTLY_CONSISTENT en la entrada del esquema de metadatos. El valor proporcionado en el evento se propaga sin cambios mediante la extracción y la consolidación. No se consulta el LLM para esa clave.
El siguiente JSON muestra un esquema de metadatos con ambos tipos STRICTLY_CONSISTENT de LLM_INFERRED extracción:
{ "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" } } } ] }
Cuando se omiteextractionType, el valor predeterminado esLLM_INFERRED.
Extracción y consolidación: aislamiento
STRICTLY_CONSISTENTlas claves hacen más que omitir la inferencia LLM. Agrupan los eventos por sus valores deterministas durante la extracción. Los eventos con valores diferentes se procesan por separado. La consolidación sigue la misma regla. Los registros de un grupo de valores nunca se combinan con los registros de otro grupo.
El siguiente ejemplo de Python muestra una sesión de soporte con dos claves deterministas (departmentypriority):
# 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"} } )
El sistema agrupa los eventos por la combinación exacta de todos los valores clave deterministas:
-
Los eventos 1 y 2 se comparten
department=billing, priority=high. Se extraen juntos. -
El evento 3 difiere en
department. Se extrae por separado, a pesar de compartirlopriority=high. -
El evento 4 difiere en
priority. Se extrae por separado, a pesar de compartirlodepartment=billing.
Todos los valores clave deterministas deben coincidir para poder agrupar los eventos. Una consulta con department=billing AND priority=high devuelve solo los datos de los cargos duplicados urgentes. Los demás eventos están en particiones separadas. Los registros de diferentes combinaciones de valores nunca se fusionan durante la consolidación.
Restricciones
| Restricción | Detalle |
|---|---|
|
Número máximo de claves deterministas por estrategia |
3 |
|
Tipo de clave |
Debe ser |
|
Debe estar indexado |
La clave también debe declararse en la memoria |
|
No |
|
|
Estrategias compatibles |
Estrategias semánticas, de preferencias del usuario y episódicas (incluidas las anulaciones personalizadas). No se admite en las estrategias de resumen. |
|
Valores faltantes |
Si un evento llega sin un valor para una clave determinista, la clave se omite de la agrupación de ese evento y no aparece en el registro resultante. |
importante
Al cambiar las claves que están configuradas, se STRICTLY_CONSISTENT cambia la agrupación utilizada para la extracción y la consolidación. Los registros creados con la configuración anterior se aíslan de los registros creados con la nueva configuración. Planifique la configuración de claves deterministas antes de ingerir eventos.
Cómo interactúan las claves indexadas y las claves de esquema
La relación entre las claves indexadas y las claves de esquema determina el comportamiento de los metadatos:
-
Indexada con el signo + en el esquema: el LLM rellena la clave en los registros extraídos y se puede filtrar en las expresiones de consulta. Esta es la configuración más común para las claves que se desean extraer y filtrar.
-
Indexada o no en el esquema: la clave no se rellena en los registros durante la extracción basada en eventos. Los filtros de esta clave no devuelven resultados para los registros extraídos. Para rellenar estas claves, utilice las API de Batch (
BatchCreateMemoryRecordsoBatchUpdateMemoryRecords). -
En el esquema +, no indexado: el LLM extrae y rellena el valor de los registros y es visible en las respuestas.
GetMemoryRecordListMemoryRecordsSin embargo, no se puede usar en expresiones de filtro. Esto resulta útil para enriquecer el contexto, como los metadatossentimentosummary_notespara enriquecer el registro de consumo posterior sin consumir el presupuesto clave indexado.
Cómo fluyen los metadatos de los eventos a los registros de memoria
Los metadatos de los eventos solo aceptan stringValue entradas. Soporte stringValue y numberValue tipos de registros de memoria: rellenados por el LLM durante la extracción o suministrados directamente a través de las API Batch. stringListValue El dateTimeValue tipo está reservado para los campos generados por el sistema (x-amz-agentcore-memory-createdAty). x-amz-agentcore-memory-updatedAt En los registros extraídos solo se metadataSchema rellenan las claves definidas en la estrategia; se ignoran las claves de metadatos de eventos que no estén en el esquema. Para conocer los límites de entrada, consulteCuotas.
System-generated metadatos
Cada registro de memoria contiene estos campos del sistema, que se pueden consultar con los mismos operadores de filtro:
| Campo | Tipo | Description (Descripción) |
|---|---|---|
|
|
|
El tipo de registro de memoria |
|
|
|
Marca de tiempo de creación del registro |
|
|
|
Registre la marca de tiempo de la última actualización |
No es necesario declararlas como claves indexadas, ya que siempre están disponibles para filtrarlas. Estos dateTimeValue campos generados por el sistema admiten BEFORE y AFTER operan, lo que permite realizar consultas por intervalos de tiempo sin necesidad de declarar las claves indexadas de fecha y hora.
Requisitos previos
Antes de configurar el filtrado de metadatos, compruebe que cuenta con lo siguiente:
-
Una AWS cuenta con permisos para llamar
CreateMemoryUpdateMemory,CreateEventListMemoryRecords,RetrieveMemoryRecords,BatchCreateMemoryRecords, yBatchUpdateMemoryRecords -
Acceso a Amazon Bedrock AgentCore
-
Una visión clara de las 3 a 5 dimensiones de filtro que más necesita su agente (departamento, prioridad, región, proyecto, etc.)
Paso 1: Cree una memoria con claves indexadas y un esquema de metadatos
A continuación, se crea una memoria de asistencia al cliente con cinco claves indexadas y un esquema de metadatos. priorityagent_type, y sentiment se definen en el esquema de metadatos de la estrategia: el LLM extrae sus valores del contenido de la conversación. Tenga en cuenta que sentiment está en el esquema pero no se declara como una clave indexada: el LLM obtiene su valor de las conversaciones y lo rellena en los registros, pero no se puede usar en las expresiones de filtro. tags(STRINGLIST), channel (STRING) y ticket_id (STRING) se declaran como claves indexadas, pero no están en el esquema; no se rellenan durante la extracción basada en eventos, pero se pueden proporcionar a través de las API de 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"] } } } } } ] } } } ]'
Paso 2: Verificar la configuración
GetMemoryUtilícelo para confirmar que se aceptaron las claves indexadas y el esquema de metadatos:
aws bedrock-agentcore-control get-memory --memory-id "<memory-id>"
Paso 3: Ingiera datos con metadatos
Existen dos vías para introducir los metadatos en los registros de memoria.
Event-driven ingestión
Adjunta stringValue metadatos a los eventos en el momento de su creación. El LLM utiliza el esquema de metadatos de la estrategia para extraer y rellenar los metadatos de los registros de memoria resultantes. En los registros resultantes solo se metadataSchema rellenan las claves definidas en la estrategia; las claves de metadatos de eventos que no están en el esquema se ignoran durante la extracción.
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."}}} ]'
En este ejemplo, priority está en la estrategiametadataSchema, por lo que su valor se propaga al registro de memoria. channely no ticket_id están en el esquema, por lo que se ignoran durante la extracción. El LLM también deduce agent_type (probablemente en "specialist" función de la escalada) y sentiment (probablemente"frustrated") del contenido de la conversación: estas claves de esquema se rellenan aunque no se hayan proporcionado como metadatos del evento.
Extracción implícita de metadatos del contenido de la conversación
Los metadatos de los eventos no son necesarios para que las claves del esquema generen valores. Cuando una clave de esquema no tiene metadatos coincidentes con los eventos de origen, el LLM obtiene el valor completamente del contenido de la conversación. Utiliza las claves definition y llmExtractionInstruction para determinar el valor. Esto resulta útil para las dimensiones que solo existen en la propia conversación, sin necesidad de que las personas que llaman las proporcionen al momento de crear el evento.
Al utilizar la misma memoria de atención al cliente del paso 1, el siguiente evento no contiene metadatos en absoluto:
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."}}} ]'
El LLM analiza el contenido de la conversación y rellena las tres claves de esquema del registro de memoria extraído (priorityagent_type, ysentiment) aunque no se haya proporcionado ninguna como metadatos del 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"} } }
Se siguen aplicando las reglas de validación: la salida del LLM se limita a los valores permitidos especificados, independientemente de si el valor proviene de los metadatos del evento o de una inferencia de contenido.
Cómo resuelve el LLM los conflictos entre eventos
Cuando varios eventos de una sesión contienen valores diferentes para la misma clave de metadatos, el LLM utiliza la. llmExtractionInstruction Esto determina qué valor se debe conservar en el registro de memoria resultante.
Por ejemplo, pensemos en una sesión de asistencia en la que se produce el primer evento priority: "low" y luego se intensifica un evento posterior. priority: "critical" El LLM resuelve este problema basándose en las siguientes instrucciones:
-
LATEST_VALUE(integrado): el LLM mantiene el valor más reciente. En este caso, el registro de memoria se obtienepriority: "critical". -
Instrucciones personalizadas: puede expresar la lógica específica del dominio. Por ejemplo, «mantener la máxima gravedad notificada durante la sesión» también tendría consecuencias
"critical", pero por otro motivo: se trata de la gravedad más alta, no solo de la más reciente.
Otro ejemplo: agent_type con la instrucción «Prefiera el tipo de agente más especializado». Jerarquía: especialista > nivel 3 > nivel 2 > nivel 1 > bot», si una sesión comienza con un bot y pasa a ser un agente de nivel 2, el registro de memoria se queda. agent_type: "tier2"
Ingesta determinista de metadatos
Las claves configuradas como tal STRICTLY_CONSISTENT siguen una ruta de ingesta diferente. El valor que proporciones en el evento es el valor que aparece en el registro resultante. No hay inferencia LLM ni resolución de conflictos.
AgentCore La memoria agrupa los eventos por sus valores clave deterministas antes de la extracción. Por ejemplo, los eventos etiquetados department: "engineering" se procesan por separado de los eventos etiquetadosdepartment: "finance".
La consolidación opera dentro de estos grupos. Un registro que no se fusiona compliance_level: "hipaa" nunca con un registro etiquetadocompliance_level: "standard". Esto hace que las claves deterministas sean ideales para:
-
Aislamiento del cumplimiento: los registros con diferentes niveles de cumplimiento nunca se mezclan.
-
Enrutamiento organizacional: Department-scoped recuperación sin contaminación cruzada.
-
Multi-tenant subfiltrado: los Tenant-specific atributos se conservan exactamente como se suministraron.
Si un evento no tiene ningún valor para una clave determinista, la clave no aparece en el registro resultante.
Las rutas de escritura directa (BatchCreateMemoryRecordsyBatchUpdateMemoryRecords) omiten la extracción. El tipo de STRICTLY_CONSISTENT extracción no les afecta. Proporcione los metadatos directamente como ya lo hace para esas API.
Creación directa de registros con las API de Batch
Para las importaciones de bases de conocimientos, las estrategias autogestionadas o el contenido preprocesado, utilice BatchCreateMemoryRecords (oBatchUpdateMemoryRecords) suministre metadatos de forma explícita. Esto evita por completo la extracción de LLM: la persona que llama controla los valores de los metadatos.
La forma en que se gestionan los metadatos en los registros creados por lotes depende de si se proporciona: memoryStrategyId
-
Con
memoryStrategyId: el servicio filtra los metadatos de entrada comparándolos con los de esa estrategia.memoryRecordSchemaSolo las claves definidas en el esquema se almacenan en el registro. Todas las demás claves, incluidas las claves indexadas que no están en el esquema, se eliminan de forma silenciosa. Esto le proporciona una coherencia impuesta por el esquema, lo que garantiza que los registros creados por lotes tengan la misma forma de metadatos que los registros generados mediante la extracción basada en eventos. -
Sin
memoryStrategyId: el servicio almacena todas las claves de metadatos de la carga útil tal como están en el registro. Esto incluye las claves que están indexadas, las claves que están en un esquema de estrategia y las claves que no lo están. Sin embargo, solo se pueden filtrar las claves indexadas; si se intenta filtrar por una clave no indexada, se obtiene un.ValidationExceptionNon-indexed las claves siguen siendo visibles en y las respuestas.GetMemoryRecordListMemoryRecords
El siguiente ejemplo crea un registro sin memoryStrategyId almacenar todos los metadatos proporcionados:
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 garantizar la coherencia del esquema, incluya elmemoryStrategyId. En este caso, solo se conservan las claves presentes en esa estrategia: memoryRecordSchema
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"} } }]'
En el segundo ejemplo, si el esquema de la estrategia solo define y priority agent_typesentiment, luego, channel se elimina silenciosamente del registro almacenado.
Actualizar los registros con BatchUpdateMemoryRecords
BatchUpdateMemoryRecordssigue el mismo comportamiento de filtrado de memoryStrategyId metadatos queBatchCreateMemoryRecords. El siguiente ejemplo actualiza el contenido y los metadatos de un 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"} } }]'
Paso 4: Realizar consultas con filtros de metadatos
Los filtros de metadatos se aplican antes de ejecutar la búsqueda de similitud vectorial (prefiltrado). Esto reduce primero el conjunto de candidatos. Como resultado, la búsqueda de K-nearest vecinos (KNN) opera en un subconjunto más pequeño y relevante.
Estructura Filter
Cada filtro es una { left, operator, right } expresión:
{ "left": { "metadataKey": "priority" }, "operator": "EQUALS_TO", "right": { "metadataValue": { "stringValue": "high" } } }
Se pueden combinar hasta 5 filtros por consulta. Se aplican varios filtros con AND lógica.
Operadores admitidos
| Operador | Se requiere el valor correcto | Funciona con | Description (Descripción) |
|---|---|---|---|
|
|
Sí |
CADENA, NÚMERO |
Coincidencia exacta. |
|
|
Sí |
LISTA DE CADENAS |
Devuelve los registros en los que cualquier elemento de la STRINGLIST contiene la cadena dada como una coincidencia exacta. |
|
|
No |
Todos los tipos |
Key está presente en el registro |
|
|
No |
Todos los tipos |
La clave no aparece en el registro |
|
|
Sí ( |
NUMBER |
Número superior al de la comparación |
|
|
Sí ( |
NUMBER |
Comparación numérica mayor o igual |
|
|
Sí ( |
NUMBER |
Comparación numérica inferior a |
|
|
Sí ( |
NUMBER |
Comparación numérica inferior o igual |
|
|
Sí ( |
fecha TimeValue |
La marca de tiempo es anterior al valor dado |
|
|
Sí ( |
fecha TimeValue |
La marca de tiempo es posterior al valor dado |
Nota: Los filtros de metadatos de eventos solo son ListEvents compatiblesEXISTS, y NOT_EXISTSEQUALS_TO, y únicamente. stringValue
Recupera con filtros de metadatos (búsqueda semántica y prefiltro)
ActivadoRetrieveMemoryRecords, metadataFilters está anidado en su interior. searchCriteria El siguiente ejemplo limita los resultados a los registros de alta prioridad del año en curso antes de que la búsqueda semántica coincida con los «problemas de facturación»:
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"}} } ] }'
Al combinar un filtro de metadatos personalizado con una marca de tiempo generada por el sistema, el conjunto candidato se compacta en dos dimensiones (prioridad empresarial y actualidad) antes de ejecutar la búsqueda de similitudes.
Lista con filtros de metadatos (sin búsqueda semántica)
ListMemoryRecordsproporciona filtrado de metadatos sin búsqueda semántica. Esto resulta útil cuando necesita enumerar los registros que coinciden con criterios de metadatos específicos, por ejemplo, enumerar todos los registros de alta prioridad de un cliente o extraer todos los registros creados después de una fecha específica.
ActivadoListMemoryRecords, metadataFilters es un parámetro de nivel 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"}} } ]'
Combinar varios filtros
Esta consulta abarca las discusiones sobre acciones del tercer trimestre de 2026 dentro de un espacio de nombres 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"}} } ] }
Los valores de filtro para las marcas horarias deben estar en UTC (formato ISO 8601). El servicio normaliza todas las marcas de tiempo almacenadas a UTC antes de compararlas, por lo que siempre exprese los valores del filtro en UTC.
Paso 5: evolucione su esquema de metadatos
AgentCore La memoria admite la evolución del esquema para que pueda adaptar la configuración de sus metadatos a medida que cambien sus necesidades.
Añada claves indexadas
Puede añadir nuevas claves indexadas a una memoria en cualquier momento:
aws bedrock-agentcore-control update-memory \ --memory-id "<memory-id>" \ --add-indexed-keys '[ {"key": "customer_segment", "type": "STRING"} ]'
Las nuevas claves están disponibles inmediatamente para los eventos entrantes y los registros de memoria. Los registros existentes no se rellenan; solo los registros nuevos o actualizados contienen la nueva clave. No se puede eliminar una clave previamente indexada, lo que evita la pérdida accidental de la capacidad de filtrado de los datos existentes.
Modifique el esquema de metadatos de una estrategia
Puede añadir, eliminar o actualizar libremente las entradas del esquema de metadatos de una estrategia. Esto controla los metadatos que el LLM extrae de las conversaciones futuras.
Por ejemplo, para añadir un resolution_type campo nuevo a una estrategia 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"] } } } } } ] } } ] }'
También puedes eliminar una clave del esquema de metadatos de una estrategia si ya no quieres que el LLM extraiga ese campo. La eliminación de una entrada del esquema detiene la extracción de nuevos registros, pero no afecta a los metadatos que ya están en los registros existentes.
Los registros de memoria existentes no reciben LLM-extracted campos nuevos de forma retroactiva. Sin embargo, cuando las memorias antiguas se consolidan con las más nuevas durante el ciclo de vida normal de la memoria, el registro consolidado se vuelve a extraer utilizando el esquema actual e incluirá los nuevos campos de metadatos.
Cuotas
| Recurso | Límite |
|---|---|
|
Claves indexadas por memoria |
10 |
|
Claves STRICTLY_CONSISTENT por estrategia |
3 |
|
Entradas del esquema de metadatos por estrategia |
20 |
|
Entradas de metadatos del registro de memoria (proporcionadas por el usuario) |
20 |
|
Filtros por consulta |
5 |
|
|
10 |
|
|
5 |
|
|
1000 caracteres cada uno |
|
Longitud de la clave de metadatos |
128 caracteres |
|
|
256 caracteres |
|
longitud para |
64 caracteres |
Prácticas recomendadas
-
Comience con 3 a 5 dimensiones de filtro que afecten directamente a la calidad de la recuperación. Cada campo indexado consume la capacidad de la infraestructura de almacenamiento, y el límite de 10 claves lo refleja. Comience con tres o cinco claves que afecten directamente a la calidad de la recuperación y añada más a medida que surjan necesidades concretas.
-
Escribe
definitioncadenas claras y específicas.definitionDescribe lo que representa el campo. En lugar de «La prioridad del ticket», escribe «El nivel de prioridad de la emisión se basa en el impacto en el cliente». Los valores van desde críticos (más graves) hasta bajos (menos graves)». ÚselollmExtractionInstructionpara una lógica de extracción detallada. -
Restrinja la salida de LLM con.
validation.allowedValuesSin validación, el LLM puede producir"High", o"HIGH"por el mismo concepto"high", romper la coincidencia de filtros. -
Elija reglas de resolución de conflictos que coincidan con la semántica del dominio.
LATEST_VALUEes un valor predeterminado seguro, pero para campos comoagent_typelos de un flujo de trabajo de escalamiento, es más correcto usar una instrucción personalizada que conserve el valor más importante. -
Prefiera la vía basada en eventos para el contenido conversacional. Deje que el LLM se encargue de la extracción y la resolución de conflictos. Reserve las API de Batch para las importaciones masivas en las que ya conozca los valores correctos de los metadatos.
-
Planifique los esquemas a nivel de estrategia. Cada estrategia puede tener la suya propia
metadataSchema, lo que permite que diferentes estrategias extraigan y manejen las mismas claves de forma diferente. Una estrategia semántica puede usar instrucciones de extracción personalizadas para clasificar la prioridad del contexto de la conversación, mientras que una estrategia de resumen puede usar una definición diferente ajustada a los metadatos específicos del resumen. -
Sea intencional con
memoryStrategyIdlos registros creados por lotes. Si los incluyesmemoryStrategyId, el servicio filtra los metadatos de entrada para incluirlos únicamente en las claves del esquema de esa estrategia; todas las demás claves se eliminan silenciosamente. Si lo omites, todos los metadatos de la carga útil se almacenan tal cual. Elija en función de su caso de uso: coherencia impuesta por un esquema para los registros que deben coincidir con los registros producidos mediante la extracción, o control total para las importaciones masivas, en las que se administran los metadatos de forma externa. -
Utilice claves de esquema no indexadas para enriquecer el contexto. No todas las claves de metadatos tienen que poder filtrarse. Las claves de esquema que no se declaran como claves indexadas siguen rellenándose en los registros extraídos y son visibles en get/list las respuestas; simplemente, no se pueden usar en las expresiones de filtro. Esto resulta útil para metadatos como
sentimentlossummary_notesque enriquecen el registro de consumo posterior sin consumir el presupuesto clave indexado. -
Utilice la extracción determinista para los valores que ya conoce. Algunas claves representan atributos organizacionales fijos
department, comotenant_tier, ocompliance_scope. Si la aplicación tiene estos valores en el momento de la creación del evento, configúrelos comoSTRICTLY_CONSISTENT. Proporcione el valor en cada evento. Esto garantiza valores exactos en los registros y elimina las representaciones incoherentes (por ejemplo,"eng"frente a"Engineering") que puede introducir la extracción mediante LLM.LLM_INFERREDResérvalo para las dimensiones que deban deducirse del contenido de la conversación, como el sentimiento o el tema. -
Planifica con antelación los espacios clave deterministas. Cada
STRICTLY_CONSISTENTclave utiliza una de las 10 ranuras para claves indexadas. Las claves indexadas no se pueden eliminar una vez agregadas. Reserve espacios si planea usar metadatos deterministas.
Anti-patterns para evitar
-
No indexe campos de texto libre de alta cardinalidad, como las descripciones o los nombres completos, ya que sobrecargan el índice sin proporcionar límites de filtro útiles.
-
No utilices metadatos para valores que cambian en cada interacción; los metadatos son más eficaces para los atributos estables o que cambian lentamente.
-
No confíe únicamente en los metadatos para aislar a los inquilinos. Un campo de
tenant_idmetadatos sin aislamiento del espacio de nombres es un modelo de seguridad basado en convenciones que elimina cualquier filtro omitido. Utilice espacios de nombres para y metadatos parawho, y.whatwhenhow urgent -
No utilice la extracción LLM para valores que deben ser exactos. Si una clave debe contener un valor específico y conocido (como
departmentoticket_id), utilice laSTRICTLY_CONSISTENTextracción o envíelo a través de las API de Batch. La extracción mediante LLM puede producir variaciones del mismo concepto.