Consideraciones sobre la seguridad

Ámbito: en este documento se tratan las consideraciones de seguridad relacionadas con el SDK de Python de Oracle AI Agent Memory. Se aplica solo a las aplicaciones que utilizan las funciones de memoria activa del SDK o la capa de almacenamiento.

Por qué es importante: Oracle AI Agent Memory puede mantener el contenido del thread, las imágenes y los registros de memoria en Oracle AI Database y, cuando se activan las funciones respaldadas por LLM, enviar contenido a puntos finales de modelo configurados para la generación, el resumen, la extracción de memoria o las incrustaciones de descripciones de imágenes. Por lo tanto, el despliegue seguro depende del manejo cuidadoso de los datos de la aplicación, el ámbito de recuperación, el acceso a la base de datos, los puntos finales del modelo externo y las políticas de retención.

Consideraciones sobre el procesamiento de memoria respaldada por LLM

Oracle AI Agent Memory soporta funciones de memoria activa, como la generación de descripciones de imágenes, el resumen de threads y la extracción automática de memoria. Cuando estas funciones están activadas, el SDK puede enviar bytes de imagen, mensajes recientes, resúmenes de threads, memorias recuperadas o texto de búsqueda al LLM configurado o al punto final de embebido. Consulte Uso de imágenes y mensajes multimodales para conocer los modos de extracción y descripción de imágenes que determinan cuándo se envían los bytes de imágenes al LLM configurado.

Importante: solo envíe contenido a Oracle AI Agent Memory que sea adecuado para el punto final del modelo configurado y las políticas de despliegue. Si la memoria activa está activada para datos que parecen incluir secretos, credenciales o datos confidenciales innecesarios, minimice u oculte ese contenido antes de que los mensajes entren en el pipeline de memoria. Trate las memorias extraídas, los resúmenes, las tarjetas de contexto y otros textos derivados del modelo como una salida no confiable que debe ser revisada y manejada de manera segura por la aplicación de integración.

Advertencia: el texto derivado del modelo puede convertirse en estado de memoria persistente. Cuando las funciones de extracción automática, resumen o tarjeta de contexto están activadas, el SDK puede insertar un resumen, memoria extraída o registro recuperado en peticiones de datos posteriores, como extracción de memoria, resumen, tarjeta de contexto o peticiones de datos de agente, antes de que la aplicación pueda revisar ese valor intermedio específico. Trate esto como un flujo de datos normal de LLM que no es de confianza: revise y valide las salidas que consume la aplicación, y no permita que el contenido derivado de la memoria autorice acciones con privilegios ni omita la política.

Siga estas recomendaciones al utilizar las funciones de memoria activa:

Consideraciones sobre la persistencia y la minimización de datos

Oracle AI Agent Memory está diseñado para mantener mensajes, memorias, metadatos e incrustaciones en Oracle AI Database cuando se utiliza el almacén respaldado por base de datos. Esto permite la recuperación duradera y la memoria entre sesiones, pero también significa que la aplicación debe planificar qué datos es adecuado retener.

Las siguientes directrices ayudan a mantener los despliegues alineados con prácticas seguras de manejo de datos:

Consideraciones sobre el ámbito de recuperación y el control de acceso

Oracle AI Agent Memory utiliza los valores user_id, agent_id y thread_id proporcionados por el emisor de llamada para la recuperación del ámbito. Este es un potente modelo de filtrado, pero no debe ser el único control en el que se basa la aplicación a la hora de decidir cómo se utiliza o muestra el contenido recuperado.

Por defecto, la recuperación de ámbito de thread utiliza la coincidencia exacta para user_id y agent_id y una coincidencia más amplia para thread_id, de modo que los resultados relevantes pueden abarcar threads pasados para el mismo par usuario-agente. Las llamadas de nivel superior OracleAgentMemory.search() y search_async() también requieren un ámbito de usuario explícito y una coincidencia de usuario exacta. Rechazan el ámbito de usuario omitido y exact_user_match=False para que la API del cliente público no busque accidentalmente entre varios usuarios. Solo se permite transferir user_id=None con coincidencia exacta de usuarios y solo destinos con registros sin ámbito.

Utilice las siguientes prácticas al diseñar la recuperación:

Para la autorización de usuario final aplicada a la base de datos, Oracle Agent Memory también expone una integración con Oracle Deep Data Security. Se trata de una función de seguridad distinta basada en roles de datos de base de datos, permisos de datos y contextos de seguridad de usuario final. Revise la API de seguridad de datos profunda y la referencia de seguridad antes de otorgar políticas o utilizar un pool de conexiones de tiempo de ejecución compartido. Esta página también documenta la auditoría unificada y las diferentes horas efectivas para la revocación de políticas de base de datos y los cambios de pertenencia a grupos de OCI IAM.

Consideraciones sobre la integración de aplicaciones y la confianza de los emisores de llamadas

Oracle AI Agent Memory debe ser llamado por la aplicación de integración u otro código de backend de confianza, no directamente por los usuarios finales. No es un límite de seguridad orientado al usuario final, y no realiza la autenticación o autorización del usuario final por su cuenta. El paquete confía en que el emisor de llamada proporcione el ámbito de recuperación, user_id, agent_id, thread_id y correcto para cada operación.

Importante: La aplicación de integración es responsable de autenticar al usuario final, autorizar el acceso y derivar el ámbito y el user_id correctos antes de llamar a las API de Oracle AI Agent Memory. Un user_id proporcionado por el emisor de llamada es un valor de ámbito, no una prueba de identidad.

Utilice las siguientes prácticas al integrar el SDK en una aplicación Ágentic:

Consideraciones sobre el registro y el diagnóstico

Oracle AI Agent Memory utiliza el registro de Python estándar y no configura los manejadores de logs de la aplicación ni los niveles de log para la aplicación de integración. Las aplicaciones pueden activar el registrador oracleagentmemory y direccionar los logs del SDK a través de su configuración de registro existente.

Utilice las siguientes prácticas al consumir logs de SDK:

Consideraciones sobre el acceso a la base de datos, la gestión de esquemas y secretos

Oracle AI Agent Memory utiliza una conexión o un pool de Oracle AI Database proporcionados por el emisor de llamada. El paquete no crea ni gestiona las credenciales de base de datos en sí. Tampoco crea, negocia ni actualiza el cifrado de red de la base de datos en nombre del emisor de la llamada.

Importante: El código de producción debe transferir una conexión o un pool de Oracle AI Database activado para TLS a Oracle AI Agent Memory. El SDK utiliza la conexión o el pool proporcionados por el emisor de llamada tal cual y no actualiza un DSN de texto sin formato. No utilice conexiones de base de datos de texto sin formato en redes externas, compartidas o no de confianza. Al utilizar python-oracledb, siga la sección oficial Cifrado seguro del tráfico de red a Oracle AI Database y configure TLS u otro transporte cifrado aprobado como parte de la creación de conexiones o pools.

Importante: nunca embeba claves de API, contraseñas u otros secretos directamente en el código de aplicación, la configuración protegida o los artefactos exportados. Utilice siempre mecanismos de inyección seguros y siga el principio de privilegio mínimo para el acceso a credenciales.

Se recomiendan las siguientes prácticas de despliegue:

Consideraciones sobre la comunicación de red y los puntos finales externos

Oracle AI Agent Memory se puede comunicar con servicios externos cuando el despliegue configura el LLM remoto o embebebe proveedores. El SDK reenvía peticiones de datos y parámetros de solicitud a través de la ruta de cliente configurada, pero la aplicación y el despliegue que lo rodea siguen siendo responsables de proteger estas conexiones.

Se recomienda lo siguiente:

Consideraciones sobre vectores de agotamiento de recursos

Los flujos de trabajo de memoria pueden aumentar el uso de la base de datos, incrustar tráfico y el consumo de tokens LLM a lo largo del tiempo. Esto es cierto tanto para el uso excesivo malicioso como para errores de implantación inocentes, como mensajes de gran tamaño o patrones de recuperación demasiado amplios.

Utilice estos controles como parte de su endurecimiento de producción:

Despliegue recomendado de Oracle Deep Data Security

Oracle Deep Data Security (profundidad) puede aplicar restricciones de columna y fila de memoria de agente en la base de datos, como permitir a los usuarios finales leer y escribir solo filas que contengan su propio user_id. La política UserOwnRowsDeepDataSecurityPolicy también impide que los usuarios finales actualicen las columnas de propiedad e identidad después de la inserción; consulte Seguridad de datos profunda para obtener los permisos exactos por tabla.

Para utilizar esta funcionalidad de seguridad en la mayor medida posible, se recomienda utilizar un usuario de base de datos independiente para cada responsabilidad de seguridad, de modo que la aplicación no tenga ninguna reserva con privilegios cuando no exista un contexto de usuario final.

Recomendamos la siguiente separación de cuentas en producción:

Para cada solicitud de usuario final, autentique el usuario fuera del sdk de OAM, adquiera una conexión de agrupación de aplicaciones, asocie el contexto de seguridad de usuario final de ese usuario y realice la operación de memoria del agente a través de esa conexión. Borre el contexto antes de liberar la conexión a un pool. Un contexto pertenece a una sesión de base de datos física; no se debe volver a utilizar para otro usuario. En la documentación del ciclo de vida del contexto de seguridad del Usuario Final de Seguridad Profunda de Oracle se describe el comportamiento correspondiente de los adjuntos, el reemplazo y la versión.

No transfiera un pool de aplicaciones general directamente a una instancia de memoria del agente a menos que el controlador de base de datos esté configurado para asociar el contexto de usuario final de la solicitud actual en cada conexión adquirida. De lo contrario, una operación SDK puede tomar prestada una sesión sin contexto o con el contexto de solicitud incorrecto. En su lugar, adquiera y configure la conexión en la aplicación y, a continuación, transfiera esa conexión que soporta el contexto al componente de memoria de agente de ámbito de solicitud.

El trabajo en segundo plano o diferido que lee o escribe registros propiedad del usuario necesita la misma protección. Mantenga la conexión autorizada y su contexto de usuario final válidos hasta que finalice el trabajo o organice que el trabajador adquiera una nueva conexión y asocie el contexto del usuario autenticado correcto. Nunca ejecute este trabajo a través del propietario del esquema simplemente para omitir un contexto de usuario final que falta.