Los usuarios de una aplicación basada en conocimientos esperan que los recuerde, no solo que busque bien. Hacen preguntas de seguimiento que solo tienen sentido en el contexto de la conversación anterior. Esperan que una respuesta sobre una política o procedimiento refleje lo que le dijeron a la aplicación sobre sí mismos el mes pasado. Y todavía esperan que cada respuesta esté basada en los documentos que están autorizados a leer, con citas. Ya sea que la aplicación sea un asistente de soporte al cliente, un chat de documentos dentro de un producto SaaS o un asistente interno sobre políticas de la empresa, la expectativa es la misma.

Cumplir con esa expectativa es difícil, porque el contexto que agudizaría una búsqueda vive fuera de la base de conocimientos. La ubicación, el rol o el nivel de producto de un usuario a menudo se mencionaron en una conversación no relacionada hace semanas. Para utilizarlo, la aplicación tiene que almacenar cada conversación, extraer hechos duraderos de ella, decidir qué hechos son importantes para la pregunta actual y injectarlos en la solicitud. Cuando muchos usuarios comparten la aplicación, cada uno de esos pasos también tiene que estar aislado por usuario, y lo mismo sucede con cada documento.

Amazon Bedrock Managed Knowledge Base y Amazon Bedrock AgentCore memory, una capacidad de Amazon Bedrock AgentCore, ahora se encargan de esos pasos: almacenar cada conversación, extraer hechos de ella y traer los hechos relevantes a la búsqueda. Activas esto agregando un memoryConfiguration a la solicitud AgenticRetrieveStream, lo que hace que la memoria de AgentCore sea una fuente de recuperación junto con su base de conocimientos. Dentro de la misma llamada, el servicio restaura la conversación y el planificador decide por sí mismo cuándo un hecho sobre el usuario sería útil. Recupera ese hecho de la memoria a largo plazo y lo utiliza para componer las subconsultas que envía a la base de conocimientos. Después de generar la respuesta, el servicio guarda la conversación de nuevo en la memoria. La misma solicitud lleva un userContext, por lo que la base de conocimientos devuelve solo los documentos que las listas de control de acceso (ACL) del usuario permiten. La integración es opt-in y compatible con versiones anteriores. Su aplicación solo mantiene lo que genuinamente es suyo: autenticar al usuario y pasar quién es.

Esta publicación muestra cómo construir un asistente de este tipo para muchos usuarios que comparten una base de conocimientos y un recurso de memoria. Cada usuario solo ve los documentos que puede leer, y la memoria de cada usuario permanece privada. El ejemplo en ejecución es un asistente interno para empleados de AnyCompany, una empresa ficticia. Los empleados iniciaron sesión con Amazon Cognito y hacen preguntas sobre políticas de recursos humanos, guías de TI, libros de ingeniería y planes de ventas. Mostramos cómo leer la identidad del usuario desde el token de ID de Cognito, cómo pasarla a AgenticRetrieveStream para ACLs de documentos y para memoria, cómo diseñar espacios de nombres de memoria para muchos usuarios y cómo leer el registro para ver cuándo el planificador utilizó la memoria. Finalmente, hacemos que AWS Identity and Access Management (IAM) haga cumplir el aislamiento de memoria por usuario incluso cuando el código de la aplicación lo hace incorrectamente. Si implementó la aplicación desde Build multi-tenant agentic chat applications on enterprise data with Amazon Bedrock Managed Knowledge Base, esta publicación reemplaza su paso "persistir el historial de conversación usted mismo".

Visión general de la solución

AnyCompany mantiene sus documentos en Amazon Simple Storage Service (Amazon S3). Una base de conocimientos administrada sincroniza los documentos a través de una fuente de datos de Amazon S3 habilitada para ACL. Un archivo de ACL global en el mismo bucket indica qué empleados pueden leer cada carpeta: todos leen Recursos Humanos y TI, solo los ingenieros leen los libros de ingeniería y solo los vendedores leen el plan de comisiones. Un recurso de memoria de AgentCore es compartido por cada empleado. Amazon Cognito autentica a los empleados, y su token de ID suministra dos reclamaciones: el sub (ID de usuario) identifica la memoria del usuario, y el email verificado identifica al usuario al filtro de ACL de la base de conocimientos. Tres usuarios de prueba se conectan: dos ingenieros, Maya y Liam, y un vendedor, Sofia. Los extractos de registro en esta publicación se tomaron de una ejecución de la aplicación de ejemplo en el repositorio de GitHub.

Arquitectura del asistente de empleado con conciencia de memoria: aplicación, AgenticRetrieveStream, Managed Knowledge Base y memoria de AgentCore

Figura 1: Arquitectura del asistente de empleado con conciencia de memoria. La aplicación autentica al usuario y construye la solicitud (pasos 1–4). Amazon Bedrock Managed Knowledge Base restaura la sesión, recupera información, devuelve una respuesta y guarda el intercambio en la memoria de AgentCore (pasos 5–8). Los eventos de corto plazo y los registros de largo plazo pertenecen al mismo recurso de memoria.

  1. El empleado inicia sesión con Cognito y recibe un token de ID, un token JSON Web (JWT) firmado por el grupo de usuarios.
  2. La API de la aplicación valida el token — un autorizador JWT de Amazon API Gateway en producción, un pequeño servicio FastAPI en la muestra. Las solicitudes no autenticadas no llegan al controlador.
  3. El controlador lee dos reclamaciones del token verificado: sub se convierte en la memoria actorId y espacio de nombres, y email se convierte en el userContext.userId. El cuerpo del cliente solo lleva { question, sessionId? }. Luego, el controlador asume el rol de IAM de la aplicación para este usuario, con la etiqueta de sesión userId=<sub>.
  4. El controlador llama a AgenticRetrieveStream con la base de conocimientos como recuperador, userContext, y un memoryConfiguration vinculado a este usuario.
  5. Managed Knowledge Base restaura el historial de conversación desde la memoria de corto plazo (STM) en la memoria de AgentCore para el actor y la sesión identificados por sessionBinding.
  6. Managed Knowledge Base recupera de la base de conocimientos con filtrado ACL basado en userContext. También puede recuperar la memoria de largo plazo configurada del usuario a través de recuperación especulativa o búsquedas de memoria seleccionadas por el planificador.
  7. Managed Knowledge Base transmite una respuesta citada y eventos de seguimiento de regreso al controlador. El controlador registra los seguimientos con un ID de correlación y reenvía la respuesta y la información de seguimiento a la UI.
  8. Con persistenceMode: DEFAULT, el servicio guarda la pregunta y la respuesta generada en la sesión. La memoria de AgentCore extrae los registros de largo plazo de forma asíncrona según las estrategias configuradas.

Un diagrama de secuencia que traza una pregunta desde Su Aplicación, a través del AgenticRetrieveSystem, la base de conocimientos administrada y la memoria de AgentCore, devolviendo fragmentos de respuesta de evento.

Figura 2: Un AgenticRetrieveStream turno con userContext y memoryConfiguration. Todo lo que está entre la primera y la última flecha es el trabajo del servicio.

La Base de Conocimientos Administrada es propietaria de la ingesta, el filtrado de ACL, el indexado, el ranking, la planificación, la recuperación y la generación. Con memoryConfiguration, también es propietaria de la restauración de sesión, la búsqueda de memoria y la persistencia. La memoria de AgentCore es propietaria del almacenamiento, la retención, el cifrado y la extracción. Su aplicación es propietaria de la autenticación, la interfaz de usuario y la lectura de la identidad del usuario desde el token. No hay una tabla de conversación: cuando la interfaz de usuario lista o vuelve a abrir una conversación, lee el mismo recurso de memoria.

Cómo la identidad se asigna a la solicitud

Cada valor se deriva de la aplicación desde el token de ID verificado. Ninguno proviene del cuerpo de la solicitud.

Campo de solicitud Derivado de Qué limita Asegurado por
userContext.userId Token de ID email (verificado, inmutable en el grupo) Qué documentos se pueden recuperar Filtrado de ACL de la base de conocimientos
memoryConfiguration.sessionBinding.actorId Token de ID sub De quién se restaura y escribe la memoria a corto plazo, y el {actorId} en espacios de nombres a largo plazo Clave de memoria de AgentCore, más una condición de IAM
memoryConfiguration.sessionBinding.sessionId Generado por la aplicación para una nueva conversación. Enumerado con ListSessions Qué conversación dentro de ese actor Clave bajo el actorId
memoryConfiguration.retrievalConfigs[0].namespacePath /anycompany/<sub> Qué registros a largo plazo puede buscar el planificador Condición de IAM

Dos reclamos diferentes realizan dos trabajos diferentes. La base de conocimiento identifica a los usuarios por correo electrónico, porque eso es lo que registra la fuente de datos conectada en sus ACL. La memoria necesita un actorId que nunca cambia y nunca se reutiliza. El sub de Cognito es ambos. Una dirección de correo electrónico se puede cambiar o reasignar a un nuevo empleado después de que alguien se vaya, y esa persona heredaría la memoria antigua. Puedes utilizar otro ID de usuario estable de tu propia tienda de usuarios como el actorId. Lo que importa es que nunca se mueve a una persona diferente.

Requisitos previos

  • documentación de recuperación de agentic, el recurso de memoria utilizado con esta integración debe estar en la misma cuenta de AWS que la base de conocimiento y en el estado ACTIVE.
  • Python 3.10 o posterior y Boto3 1.43.72 o posterior.
  • Permiso para crear un bucket de S3, una piscina de usuarios de Cognito, roles de IAM, una base de conocimiento y un recurso de memoria. El infra/setup.py de la muestra crea todos estos recursos de forma idempotente.

Guía de solución

Los siguientes pasos crean la base de conocimiento y su fuente de datos, configuran el recurso de memoria y Amazon Cognito, construyen la solicitud y leen la traza para confirmar el resultado.

Paso 1: Crear la base de conocimiento con una fuente de datos habilitada para ACL

Una base de conocimiento administrada no necesita un almacén de vectores:

Configura el rol de servicio para tu configuración siguiendo Crear un rol de servicio para bases de conocimiento administradas de Amazon Bedrock, y pasa su ARN en roleArn. Para los requisitos de acceso al modelo, también revisa los requisitos previos para modelos administrados y personalizados.

kb = agent.create_knowledge_base(
    name="anycompany-assistant-docs",
    description="AnyCompany internal documents: HR policies, IT guides, engineering runbooks, sales plans.",
    roleArn=kb_service_role_arn,
    knowledgeBaseConfiguration={
        "type": "MANAGED",
        "managedKnowledgeBaseConfiguration": {"embeddingModelType": "MANAGED"},
    },
)["knowledgeBase"]

Los documentos viven en el bucket bajo docs/<folder>/. Amazon S3 no tiene un sistema de permisos propio para rastrear, así que proporcionas las ACL en un archivo de ACL global en el mismo bucket. Cada entrada asigna un prefijo de S3 a los correos electrónicos que pueden leerlo:

[
  {"keyPrefix": "s3://BUCKET/docs/hr/",
   "aclEntries": [{"Name": "maya@example.com",  "Type": "USER", "Access": "ALLOW"},
                  {"Name": "liam@example.com",  "Type": "USER", "Access": "ALLOW"},
                  {"Name": "sofia@example.com", "Type": "USER", "Access": "ALLOW"}]},
  {"keyPrefix": "s3://BUCKET/docs/engineering/",
   "aclEntries": [{"Name": "maya@example.com",  "Type": "USER", "Access": "ALLOW"},
                  {"Name": "liam@example.com",  "Type": "USER", "Access": "ALLOW"}]},
  {"keyPrefix": "s3://BUCKET/docs/sales/",
   "aclEntries": [{"Name": "sofia@example.com", "Type": "USER", "Access": "ALLOW"}]}
]

El archivo de la muestra también da a todos docs/it/. Luego crea la fuente de datos. Para una base de conocimiento administrada, cada conector tiene el tipo MANAGED_KNOWLEDGE_BASE_CONNECTOR, y connectorParameters.type selecciona la fuente:

ds = agent.create_data_source(
    knowledgeBaseId=kb["knowledgeBaseId"],
    name="s3-docs-acl",
    dataSourceConfiguration={
        "type": "MANAGED_KNOWLEDGE_BASE_CONNECTOR",
        "managedKnowledgeBaseConnectorConfiguration": {
            "connectorParameters": {
                "type": "S3",
                "version": "1",
                "connectionConfiguration": {"bucketName": BUCKET, "bucketOwnerAccountId": ACCOUNT_ID},
                "filterConfiguration": {"inclusionPrefixes": ["docs/"]},
                "aclEnabled": True,
                "aclConfiguration": {"globalAccessControlListS3Uri": f"s3://{BUCKET}/acl/global-acl.json"},
            }
        },
    },
)["dataSource"]

aclEnabled no se puede cambiar después de que se crea la fuente de datos. CreateDataSource es asíncrono, así que espere el estado AVAILABLE. Luego llame a StartIngestionJob y espere COMPLETE. La sincronización lee los documentos y el archivo ACL e indexa cada documento con su ACL. En el ejemplo, se escanearon y indexaron los 11 documentos con 0 fallos. Un documento que no está cubierto por ninguna entrada de ACL no se ingesta, y un usuario cuyo correo electrónico no coincide con ninguna entrada no recibe resultados de esta fuente de datos.

El mismo modelo se aplica a los conectores que rastrean permisos desde el sistema de origen, como Microsoft SharePoint, Google Drive y Atlassian Confluence. Allí, los permisos provienen de la fuente, los grupos se resuelven desde la fuente y la base de conocimientos también verifica cada resultado contra la fuente en tiempo real. Su código de aplicación no cambia: todavía pasa el correo electrónico del usuario en userContext. Para ver la lista completa, consulte Habilitación de la conciencia de listas de control de acceso.

Paso 2: Crear el recurso de memoria y diseñar espacios de nombres

Un recurso de memoria sirve a todos los usuarios. La separación por usuario proviene de {actorId} en las plantillas de namespace, que AgentCore memoria resuelve desde cada evento en el momento de la extracción. Dos opciones importan.

Estrategias. Las dos estrategias extraen cosas diferentes. La estrategia de resumen resume cada conversación, por lo que captura hechos que un usuario menciona de pasada, como “Estoy en una Mac en la oficina de Frankfurt”. Esos hechos son lo que personalizan una respuesta posterior sobre, por ejemplo, PTO. La estrategia de preferencia del usuario extrae preferencias declaradas en registros estructurados (“Prefiere respuestas en puntos breves sin tablas”, “Siempre implementa en eu-central-1 primero”) y no trata las menciones incidentales como preferencias. Los resúmenes le dan “lo que discutimos”. Las preferencias le dan “cómo esta persona quiere ser respondida”. Utilice ambos.

Disposición. retrievalConfigs acepta una entrada, por lo que una sola namespacePath debe llegar a todo lo que el planificador debe ver para un usuario. Coloque {actorId} directamente debajo de la raíz: namespacePath: "/anycompany/<sub>" luego cubre el perfil y cada resumen de conversación. Una disposición como /anycompany/profile/{actorId} y /anycompany/summaries/{actorId} permitiría que una entrada llegue solo a uno de ellos.

memory = control.create_memory(
    name="anycompany_assistant_memory",
    eventExpiryDuration=30,          # days; raw conversation events expire after this
    # encryptionKeyArn=CMK_ARN,      # optional customer managed key
    memoryStrategies=[
        {"userPreferenceMemoryStrategy": {
            "name": "EmployeeProfile",
            "namespaces": ["/anycompany/{actorId}/profile"],
        }},
        {"summaryMemoryStrategy": {
            "name": "ConversationSummaries",
            "namespaces": ["/anycompany/{actorId}/summaries/{sessionId}"],
        }},
    ],
)["memory"]

Espere a que la memoria alcance ACTIVE. La creación de la memoria no requiere un usuario o actorId, por lo que el orden del Paso 2 y el Paso 3 no importa. Nada se provisiona por usuario: un nuevo usuario de Cognito se convierte en un nuevo actor la primera vez que hace una pregunta.

Paso 3: Configurar Cognito y otorgar permisos a la aplicación

Crear un grupo de usuarios y un cliente de aplicación sin secreto de cliente. El correo electrónico decide qué documentos puede leer un usuario, así que asegúrese de que sea obligatorio, verificado y no modificable por el usuario:

pool_id = idp.create_user_pool(
    PoolName="anycompany-assistant-employees",
    AutoVerifiedAttributes=["email"],
    Schema=[{"Name": "email", "Required": True, "Mutable": False, "AttributeDataType": "String"}],
    AdminCreateUserConfig={"AllowAdminCreateUserOnly": True},
)["UserPool"]["Id"]

Mutable no se puede cambiar después de que se crea el grupo. Con un correo electrónico mutable, un usuario conectado podría cambiar su correo electrónico a la dirección de un colega. Si sus usuarios se federan desde Okta o Microsoft Entra ID, asigne el correo electrónico del IdP a este atributo para que coincida con el correo electrónico en las ACL de su fuente de datos.

La muestra habilita USER_PASSWORD_AUTH para que la interfaz de usuario local y las pruebas puedan iniciar sesión directamente. Las aplicaciones de producción suelen utilizar el inicio de sesión administrado por Cognito o AWS Amplify.

Configurar un rol de IAM para la aplicación. El backend asume uno por usuario, con la etiqueta de sesión userId=<sub>, y cada declaración de memoria está condicionada a esa etiqueta. Esta es la política completa con la que se ejecuta la muestra:

{
  "Version": "2012-10-17",
  "Statement": [
    { "Sid": "AgenticRetrieve", "Effect": "Allow",
      "Action": "bedrock:AgenticRetrieveStream", "Resource": "*" },
    { "Sid": "KnowledgeBaseRetrieval", "Effect": "Allow",
      "Action": ["bedrock:Retrieve", "bedrock:GetDocumentContent"],
      "Resource": "arn:aws:bedrock:us-west-2:111122223333:knowledge-base/KB_ID" },
    { "Sid": "PlannerAndGeneration", "Effect": "Allow",
      "Action": "bedrock:InvokeModelWithResponseStream", "Resource": "*" },
    { "Sid": "MemoryDescribe", "Effect": "Allow",
      "Action": "bedrock-agentcore:GetMemory",
      "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:memory/MEMORY_ID" },
    { "Sid": "MemorySessionsScopedToCaller", "Effect": "Allow",
      "Action": ["bedrock-agentcore:ListEvents", "bedrock-agentcore:CreateEvent",
                 "bedrock-agentcore:ListSessions"],
      "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:memory/MEMORY_ID",
      "Condition": {"StringEquals": {"bedrock-agentcore:actorId": "${aws:PrincipalTag/userId}"}} },
    { "Sid": "MemoryRecordsScopedToCaller", "Effect": "Allow",
      "Action": ["bedrock-agentcore:RetrieveMemoryRecords", "bedrock-agentcore:ListMemoryRecords"],
      "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:memory/MEMORY_ID",
      "Condition": {"StringLike": {"bedrock-agentcore:namespacePath": "/anycompany/${aws:PrincipalTag/userId}/*"}} }
  ]
}

ListEvents es obligatorio con sessionBinding, RetrieveMemoryRecords con retrievalConfigs, y CreateEvent cuando persistenceMode es DEFAULT. ListSessions y ListMemoryRecords son para las lecturas propias de la aplicación (lista de conversaciones y la vista "qué sabe la memoria sobre usted"), no para AgenticRetrieveStream. La política de confianza del rol permite sts:AssumeRole, sts:TagSession y sts:SetSourceIdentity desde la identidad propia del backend (un rol de ejecución de AWS Lambda o un rol de tarea de Amazon Elastic Container Service (Amazon ECS) en producción). Si la memoria utiliza una clave administrada por el cliente, agregue kms:Decrypt en esa clave.

Paso 4: Leer al usuario desde el token, luego construir la solicitud

Verificar el token de ID y leer las dos reclamaciones. Solo el token de ID lleva email. El token de acceso no:

@dataclasses.dataclass(frozen=True)
class Principal:
    sub: str     # -> memory actorId and namespace
    email: str   # -> userContext.userId (document ACLs)

    def namespace_path(self, root: str) -> str:
        return f"{root}/{self.sub}"       # resolved literal, e.g. /anycompany/a8e1b390-...


def verify(id_token: str) -> Principal:
    key = jwks.get_signing_key_from_jwt(id_token)   # public keys from {issuer}/.well-known/jwks.json
    claims = jwt.decode(id_token, key.key, algorithms=["RS256"], issuer=ISSUER, audience=CLIENT_ID)
    if claims.get("token_use") != "id" or claims.get("email_verified") is not True:
        raise PermissionError("a verified ID token is required")
    return Principal(sub=claims["sub"], email=claims["email"].lower())

jwt.decode verifica la firma, el emisor (su grupo de usuarios), la fecha de vencimiento y la audiencia (su cliente de aplicación). Para obtener detalles de las reclamaciones, consulte Comprender el token de identidad (ID). Con API Gateway, un autorizador JWT realiza las mismas comprobaciones y pasa las reclamaciones a su controlador.

A continuación, obtener las credenciales de AWS del usuario. El backend asume el rol de la aplicación para este usuario y almacena la sesión en caché hasta poco antes de que expire:

creds = sts.assume_role(
    RoleArn=APP_ROLE_ARN,
    RoleSessionName=f"user-{principal.sub}",
    SourceIdentity=principal.sub,
    Tags=[{"Key": "userId", "Value": principal.sub}],
)["Credentials"]

Cada llamada para este usuario, incluyendo las llamadas de memoria que la recuperación agente hace en nombre del llamador, ahora se ejecuta como assumed-role/anycompany-assistant-app-role/user-<sub> y lleva la etiqueta que la política en el Paso 3 verifica.

Decida el sessionId. Para una nueva conversación, la aplicación genera uno, como "conv-" + uuid4().hex, y lo devuelve al cliente. Para continuar una conversación, el cliente lo envía de vuelta. Para mostrar al usuario sus conversaciones, llame a ListSessions con el actorId del usuario:

def list_conversations(principal):
    try:
        resp = memory.list_sessions(memoryId=MEMORY_ID, actorId=principal.sub, maxResults=50)
    except memory.exceptions.ResourceNotFoundException:
        return []   # the user has not asked anything yet, so there is no actor
    return [{"sessionId": s["sessionId"], "createdAt": s["createdAt"].isoformat()} for s in resp["sessionSummaries"]]

No necesita su propia tabla que mapee usuarios a sesiones. Aceptar un sessionId del cliente es seguro porque la memoria a corto plazo está claveada por (memoryId, actorId, sessionId), y el actorId proviene del token. Si Liam envía el sessionId de Maya, nombra una sesión dentro del propio espacio de Liam, que está vacío. La recuperación agente en sí no verifica que el actorId, sessionId o espacio de nombres que proporcione pertenezcan al usuario que está preguntando, por lo que nunca deben provenir del cliente. Mantenga su propia tabla de sesiones solo si necesita datos que la memoria no contenga, como títulos de conversación.

Luego, construya la solicitud:

def build_request(principal, question, session_id):
    return {
        # With sessionBinding, messages carries ONLY the current question.
        "messages": [{"role": "user", "content": {"text": question}}],
        "retrievers": [{"configuration": {"knowledgeBase": {"knowledgeBaseId": KB_ID}},
                        "description": KB_DESCRIPTION}],
        # Document ACLs: only documents this email may read are retrieved.
        "userContext": {"userId": principal.email},
        "agenticRetrieveConfiguration": {
            "foundationModelType": "MANAGED",
            "rerankingModelType": "MANAGED",
            "maxAgentIteration": 3,
        },
        "generateResponse": True,
        "memoryConfiguration": {
            "memoryId": MEMORY_ID,
            "sessionBinding": {"actorId": principal.sub, "sessionId": session_id},
            "persistenceMode": "DEFAULT",
            "retrievalConfigs": [{"namespacePath": principal.namespace_path("/anycompany")}],
        },
    }

Sin userContext, un origen de datos habilitado para ACL no devuelve resultados en absoluto. Compare la solicitud con el controlador sin estado que reemplaza:

history = history_table.query(KeyConditionExpression=Key("sessionId").eq(session_id))
messages = [*replay(history), {"role": "user", "content": {"text": question}}]
response = runtime.agentic_retrieve_stream(messages=messages, retrievers=..., agenticRetrieveConfiguration=...)
history_table.put_item(Item={"sessionId": session_id, "q": question, "a": consume(response)})

La consulta antes de la llamada y la escritura después de ella han desaparecido, y messages tiene un elemento. Tres reglas vienen con sessionBinding, y cada una se aplica con un ValidationException específico. Primero, messages solo lleva la pregunta actual, por lo que elige una fuente de historial por solicitud. Segundo, persistenceMode: DEFAULT (el predeterminado) escribe la pregunta y la respuesta generada como un solo evento, por lo que requiere generateResponse: true. Tercero, memoryId solo es inválido. persistenceMode: NONE restaura el historial y no escribe nada, para vistas de auditoría o reproducción.

Paso 5: Actualice el contrato del cliente y renderice el historial

El cliente envía { question, sessionId? }. En una nueva conversación, la aplicación genera un sessionId y lo devuelve como el primer marco transmitido. El cliente lo repite en giros posteriores y lo omite para empezar de nuevo.

Como el recurso de memoria es suyo, la aplicación lo lee directamente para renderizar una conversación:

def conversation_history(principal, session_id):
    resp = memory.list_events(memoryId=MEMORY_ID, actorId=principal.sub, sessionId=session_id,
                              includePayloads=True, maxResults=100)
    return [{"role": p["conversational"]["role"].lower(), "text": p["conversational"]["content"]["text"]}
            for ev in sorted(resp["events"], key=lambda e: e["eventTimestamp"])
            for p in ev["payload"] if "conversational" in p]

Cada turno persistente es exactamente un evento con dos cargas útiles: la pregunta del usuario y la respuesta final. Por lo tanto, el historial se renderiza como una transcripción limpia y sigue siendo utilizable por otros clientes de memoria de AgentCore.

Paso 6: Verifique desde la traza

La traza le dice, por turno, qué hicieron la base de conocimiento y la memoria:

Evento de seguimiento Cuándo aparece Qué examinar
SessionHistoryLoad Primer evento, siempre que sessionBinding esté establecido _memory_event_count y _memory_message_count, ambos 0 en una nueva sesión
SpeculativeRetrieval Antes de la planificación En una nueva sesión, retrievalMetadata también enumera BedrockAgentCoreMemory. Los elementos de memoria llevan metadatos _memory_* y no texto. Los elementos de la base de conocimiento llevan _source_uri
Planning Cada iteración actions[].memoryRetrieve significa que el planificador eligió buscar en la memoria, con una consulta que compuso
Retrieval con retrievalType: BedrockAgentCoreMemory Por acción de memoria planificada _memory_record_count. Un recuento de 0 es un resultado normal
Un evento de memoria con status: FAILED Memoria no disponible o acceso denegado failures[].message. La memoria es de mejor esfuerzo: la solicitud continúa y la respuesta se genera desde la base de conocimiento

Las siguientes ejecuciones muestran el comportamiento. Los extractos son textuales, recortados para longitud.

ACLs de documento: Maya y Sofia, misma pregunta. “¿Cuál es la asignación semanal de llamada?” La guía de llamada está en docs/engineering/. La recuperación de Maya incluyó docs/engineering/oncall.md, y la respuesta fue “500 USD o 450 EUR por semana”. La recuperación especulativa de Sofia y la subconsulta de seguimiento del planificador solo devolvieron fragmentos de RRHH y ventas:

Planning/SUCCEEDED   actions: retrieve("on-call stipend compensation policy")
Retrieval/SUCCEEDED  [BedrockKnowledgeBase]  9 items   # docs/hr/*, docs/sales/commission-plan.md

Su respuesta dijo que no hay asignación de llamada documentada en las fuentes a las que puede acceder. La aplicación no tomó ninguna decisión de acceso. Pasó userContext.userId: "sofia@example.com", y la base de conocimiento hizo el filtrado. Lo contrario es válido para el plan de comisiones: Sofia obtiene el acelerador del 12% y la recuperación de Maya no contiene docs/sales/.

Torneo 1: Maya, conversación nueva. “¿Cómo configuro la VPN en mi laptop? Estoy en una Mac en la oficina de Frankfurt”.

SessionHistoryLoad/SUCCEEDED    "Restored 0 short-term memory event(s)"
SpeculativeRetrieval/SUCCEEDED  [BedrockAgentCoreMemory, BedrockKnowledgeBase]  10 items
Planning/SUCCEEDED

La respuesta da la puerta de enlace de Frankfurt (vpn-fra.anycompany.example) y los pasos de macOS. Después, ListEvents en la sesión muestra un evento con dos cargas.

Torneo 2: Maya, misma conversación. “Se desconecta cada pocos minutos. ¿Qué debo intentar?” La solicitud solo llevaba esa oración:

{"step": "SessionHistoryLoad", "status": "SUCCEEDED",
 "message": "Restored 1 short-term memory event(s)",
 "retrievalResponse": [{"metadata": {"_memory_session_id": "conv-d25dccca6cbf47a6af893621e546905d",
                                     "_memory_event_count": 1, "_memory_message_count": 2}}]}

El planificador envió retrieve("VPN disconnects every few minutes troubleshooting") y retrieve("Cisco Secure Client macOS frequent disconnect fix"). La respuesta resolvió “eso” y señaló iCloud Private Relay, la causa específica de macOS en la guía. En una sesión continuada, SpeculativeRetrieval solo consulta la base de conocimientos. La búsqueda de memoria a largo plazo en ese paso ocurre en nuevas sesiones.

Turno 3: Maya, una nueva conversación, más tarde. “¿Cuántos días de PTO obtengo por año y se llevan los días no utilizados?” Su oficina decide la respuesta, y ella nunca la mencionó en esta conversación. La recuperación especulativa buscó en la memoria a largo plazo con la pregunta cruda y encontró un registro:

{"step": "SpeculativeRetrieval",
 "retrievalMetadata": [{"identifier": "JQUFTMTNZV", "retrievalType": "BedrockKnowledgeBase"},
                       {"identifier": "anycompany_assistant_memory-5llXYu8f2i", "retrievalType": "BedrockAgentCoreMemory"}],
 "retrievalResponse": [
   {"content": {"mimeType": "text/plain", "text": "# AnyCompany Paid Time Off (PTO) Policy ..."},
    "metadata": {"_document_title": "pto-policy.md", "_data_source_type": "S3",
                 "_source_uri": "https://.../docs/hr/pto-policy.md"},
    "sourceRetriever": {"identifier": "JQUFTMTNZV"}},
   {"content": {"mimeType": "text/plain"},
    "metadata": {"_memory_strategy_id": "ConversationSummaries-JFDHQVB4VU",
                 "_memory_query": "How many days of PTO do I get per year, and do unused days carry over?",
                 "_memory_namespace_path": "/anycompany/a8e1b390-10f1-70d9-ee85-b68b610ee0c4",
                 "_memory_record_count": 1},
    "sourceRetriever": {"identifier": "anycompany_assistant_memory-5llXYu8f2i"}}]}

Los elementos de la base de conocimientos y la memoria comparten un retrievalResponse. Distinguirlos por sourceRetriever.identifier o por las claves _memory_*. El registro fue el resumen de su conversación sobre VPN. Eso fue suficiente: el planificador fue directamente a la respuesta, que decía “Dado que su memoria indica que está basado en la oficina de Frankfurt... obtiene 30 días de PTO por año, otorgados en su totalidad el 1 de enero, y los días no utilizados deben usarse antes del 31 de marzo del año siguiente”. Un hecho de una conversación de IT personalizó una respuesta de RRHH.

Turno 4: Liam, nueva conversación, pregunta idéntica. Same handler, misma recurso de memoria, un token diferente. La recuperación especulativa no encontró nada sobre él, así que el planificador decidió buscar en la memoria con su propia consulta:

{"step": "Planning", "status": "SUCCEEDED",
 "actions": [{"memoryRetrieve": {"inputQuery": {"text": "employee office location"},
                                 "memoryId": "anycompany_assistant_memory-5llXYu8f2i"}}]}
{"step": "Retrieval", "status": "SUCCEEDED",
 "message": "Retrieved 0 long-term memory record(s)",
 "retrievalMetadata": [{"identifier": "anycompany_assistant_memory-5llXYu8f2i", "retrievalType": "BedrockAgentCoreMemory"}],
 "retrievalResponse": []}

Liam recibió la tabla de las tres oficinas y una solicitud para decir a cuál pertenece. La aplicación elige dónde el planificador puede buscar. El planificador decide si buscar y qué preguntar: una acción memoryRetrieve aparece solo cuando el planificador decide que otra búsqueda de memoria ayudaría. Leer la sessionId de Maya a través del endpoint de historia con el token de Liam devolvió una lista vacía.

Respuesta del asistente de Maya con un acierto de memoria, dando una respuesta de VPN específica de Frankfurt Respuesta del asistente de Liam con cero registros de memoria, mostrando la tabla genérica de tres oficinas

Figura 3: La misma pregunta de dos usuarios. La traza de Maya muestra un acierto de memoria y una respuesta específica de Frankfurt. La traza de Liam muestra cero registros de memoria y la tabla genérica.

La extracción a largo plazo es asíncrona y se ejecuta después de que se persista el turno. En nuestra ejecución, el primer registro apareció 81 segundos después del turno 2, pero el tiempo no es un compromiso. Diseñe para la disponibilidad eventual. Un hecho establecido en esta conversación no está garantizado para ser recuperable en la siguiente de inmediato. La muestra de sondeos ListMemoryRecords antes de ejecutar el turno 3.

Seguridad y aislamiento multiusuario

En este recorrido, la aplicación autentica. La base de conocimientos filtra. La recuperación consciente de ACL es filtrado, no autorización. Tome el correo electrónico solo de un token de ID verificado con email_verified: true, hágalo inmutable en el grupo y maneje el reuso de correo electrónico: si una dirección se reasigna a una persona diferente, esa persona obtiene el acceso al documento del antiguo propietario. La base de conocimientos falla cerrada: un documento sin ACL, o un error de ACL, significa menos resultados, no más. Si faltan resultados, verifique que el correo electrónico coincida con la entrada de ACL.

La identidad proviene del token (Paso 4) para la memoria también: actorId y el espacio de nombres provienen del token de sub verificado, nunca del cliente.

Claves de condición de IAM, como defensa en profundidad. La memoria de AgentCore expone bedrock-agentcore:actorId en ListEvents, CreateEvent y ListSessions, y bedrock-agentcore:namespacePath en RetrieveMemoryRecords y ListMemoryRecords. Las llamadas a memoria que realiza la recuperación agente durante una solicitud están autorizadas contra la identidad de llamada. Es por eso que la política del llamador debe conceder esas acciones, y por eso las condiciones en el Paso 3 se aplican a ellas. Con la sesión asumida para Maya, una solicitud vinculada a la actorId de Maya procede con normalidad. Una solicitud que vincula la actorId de Liam es el error que esta política protege contra, y es denegada en cada operación de memoria:

SessionHistoryLoad/FAILED      failures: ["AccessDeniedException"]
SpeculativeRetrieval/SUCCEEDED failures: ["AccessDeniedException"]   # memory leg denied, KB leg answered

Nada se escribió en la memoria de Liam: su recuento de sesión se mantuvo en 0. La respuesta todavía se generó a partir de la base de conocimientos. Debido a que cada usuario tiene su propia sesión de rol, AWS también ve a qué usuario se dirige cada llamada: el llamador es assumed-role/anycompany-assistant-app-role/user-<sub> con SourceIdentity=<sub>, que el titular de la sesión no puede cambiar.

Dos puntos adicionales. La memoria es un recurso propiedad del cliente que otros sistemas en su cuenta también pueden escribir. Trate su contenido como entrada y adjunte una barrera de guardia de Amazon Bedrock a la solicitud a través de policyConfiguration. Y planifique el ciclo de vida de los datos. Los eventos sin procesar caducan según eventExpiryDuration, pero los registros extraídos no. Un flujo de trabajo de eliminación de usuario cubre por lo tanto DeleteEvent para las sesiones del actor y DeleteMemoryRecord bajo el espacio de nombres del actor.

Observabilidad y comportamiento de falla

Registre la traza completa con un ID de correlación por turno. Las subconsultas del planificador son tan dignas de auditoría como sus resultados finales. AWS/Bedrock/KnowledgeBases informa Invocations, ClientErrors, y TotalIterationCount para Operation=AgenticRetrieveStream. AWS/Bedrock-AgentCore informa Invocations, Latency, Errors, y UserErrors por operación de memoria, y InputTokenUsage/OutputTokenUsage por estrategia de extracción. Con Amazon CloudWatch Transaction Search habilitado, AgentCore Observability, una capacidad de Amazon Bedrock AgentCore, muestra las trazas de un turno de principio a fin.

Las operaciones de memoria son de mejor esfuerzo por diseño. Si una llamada a memoria falla o es denegada, la solicitud no falla. La traza lleva un evento de memoria FAILED con el mensaje de falla, y el turno continúa sin esa memoria. La respuesta se genera desde la base de conocimiento. Decida si su UI muestra ese estado degradado.

Consideraciones

  • Utilice un sessionId estable durante la vida de una conversación. La API acepta un ID fresco por solicitud, pero un ID fresco rompe silenciosamente la continuidad y produce un registro de resumen por turno.
  • Utilice namespacePath para acceder a todos los registros a largo plazo de un usuario. retrievalConfigs acepta una entrada con hasta cinco metadataFilters. namespace coincide por prefijo y namespacePath coincide por jerarquía, por lo que namespacePath se ajusta a los IDs por usuario bajo la raíz. Proporcione espacios de nombres completamente resueltos, porque una plantilla como /anycompany/{actorId} es rechazada.
  • Espere que solo se restauren los eventos de conversación USER y ASSISTANT. Los eventos con el rol TOOL o OTHER que otros sistemas escriben se omiten.
  • Continúe enviando messages en lugar de sessionBinding cuando su aplicación necesite controlar exactamente qué historia lleva cada solicitud. Por ejemplo, su tienda de historia existente puede ser el sistema de registro para conversaciones, o puede editar o tachar la historia antes de enviarla. Con sessionBinding, el servicio restaura y persiste la conversación por usted. No puede combinar los dos en una solicitud.
  • Una solicitud puede llevar hasta cinco bases de conocimiento. Con más de un recuperador, el planificador enruta cada subconsulta según la base de conocimiento description, así que escríbala con cuidado.
  • Planee la latencia y el costo. La restauración de la sesión agrega del orden de 200 milisegundos. En nuestras ejecuciones, un turno completo con una base de conocimiento, ACL y memoria tomó 4-10 segundos con el modelo administrado. Las iteraciones de planificación impulsan ese tiempo, no la memoria. Estas son cifras observadas, no compromisos de servicio. La recuperación agente se factura por llamada más recuperaciones subyacentes, y las operaciones de memoria realizadas durante la llamada se facturan como uso de memoria de AgentCore. Para obtener más detalles, consulte precios de Amazon Bedrock y precios de Amazon Bedrock AgentCore.

Limpieza

Ejecute python infra/teardown.py en la muestra para eliminar la base de conocimiento, el bucket de S3 y sus objetos, el recurso de memoria (incluida la historia de conversación y los registros a largo plazo), la piscina de usuarios de Cognito y los roles de IAM.

Conclusión

Amazon Bedrock Managed Knowledge Base ya le dio la pila de recuperación como servicio. Esa pila cubre la ingesta, los ACL de documento, el indexado, el ranking y el bucle de planificación en AgenticRetrieveStream que convierte una pregunta difícil en una respuesta citada. Con memoryConfiguration, la misma llamada ahora lleva la conversación y el historial del usuario. Para una aplicación multiusuario, eso eliminó la tienda de conversación, la reproducción de historial y la pipeline de extracción. Lo que quedó fue una breve lista de responsabilidades. Autenticar al usuario y leer dos reclamaciones del token de ID: pasar el correo electrónico verificado como userContext para que la base de conocimientos filtre los documentos, y usar el sub como el actorId para un recurso de memoria con espacios de nombres con raíz {actorId}. Usar claves de condición de IAM en una sesión de rol por usuario como segunda línea de defensa que se mantiene a lo largo del camino agente.

Para empezar, implemente el ejemplo del repositorio de GitHub. Luego lea la referencia de la API AgenticRetrieveStream, habilitación de la conciencia de las listas de control de acceso, y Uso de la memoria de AgentCore con recuperación agente. Para el bucle de recuperación en sí, consulte Recuperación agente para Amazon Bedrock Managed Knowledge Base. Para conceptos de memoria, consulte Memoria de Amazon Bedrock AgentCore: Creación de agentes conscientes del contexto.

 


Acerca de los autores

Peng Yang

Peng Yang

Peng es un ingeniero de software senior en el equipo de Amazon Bedrock Managed Knowledge Base. Su trabajo en los últimos años abarca sistemas de recuperación y generación de inteligencia artificial en Amazon Kendra, Amazon Q Business, AWS Quick y Amazon Bedrock Managed Knowledge Base.

Renya Kujirada

Renya Kujirada

Renya es un especialista en soluciones de arquitectura de AI en Amazon Web Services Japan. Es el líder técnico de Amazon Bedrock AgentCore en Japón y trabaja con clientes de diversas industrias para desarrollar agentes, diseñar plataformas de agentes y ajustar LLMs. Antes de unirse a AWS, trabajó como científico de datos, desarrollando modelos de aprendizaje profundo y construyendo soluciones impulsadas por agentes. Fue seleccionado como ingeniero principal de AWS en Japón en 2025 y como constructor de la comunidad de AWS.

Jason Sheng

Jason Sheng

Jason es un ingeniero de software senior en Amazon Bedrock Knowledge Bases. Se especializa en construir servicios de aprendizaje automático y AI generativa, y en los últimos seis años ha contribuido a Amazon Q, Bedrock Knowledge Bases, Amazon Kendra y Amazon Translate.

Siddhant Sahu

Siddhant Sahu

Siddhant es un gerente de producto senior en AWS y el propietario único de Amazon Bedrock Managed Knowledge Base, el líder de producto responsable de su estrategia, hoja de ruta y lanzamiento. Concibió y lanzó su recuperación agente y conectores de aplicaciones, lo que permite a los agentes de AI habilitar consultas de búsqueda complejas en datos empresariales a través de aplicaciones comerciales cruciales como SharePoint, Confluence, S3, etc. Desde su lanzamiento en junio de 2026, el servicio ha sido adoptado por OpenAI, Syngenta, MRH Trowe, Sony y otras empresas que construyen agentes de AI en datos empresariales.

¿Tiene un proyecto de software o plataforma SaaS en mente?

Hable directamente con nuestros arquitectos de software en SoftAndino. Le brindamos asesoría técnica y cotización inmediata sin compromiso.