Consideraciones sobre la seguridad

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

Por qué es importante: la memoria del agente de Oracle AI puede mantener el contenido del thread y los registros de memoria en Oracle Database y, cuando las funciones respaldadas por LLM están activadas, enviar contenido a puntos finales de modelo configurados para resumir, extraer memoria o embeber. 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

La memoria del agente de Oracle AI soporta funciones de memoria activa, como el resumen de threads y la extracción automática de memoria. Cuando estas funciones están activadas, el SDK puede enviar mensajes recientes, resúmenes de threads, memorias recuperadas o texto de búsqueda al LLM configurado o al punto final de embebido.

Importante: solo envíe contenido a la memoria del agente de Oracle AI que sea adecuada 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:

• Validar y minimizar los datos de la aplicación: revise los mensajes, metadatos e identificadores que la aplicación envía al SDK. Evite transferir más datos de los que necesita el flujo de trabajo de memoria.
• Utiliza puntos finales de modelos de confianza: configura el LLM e integra puntos finales que cumplan tus requisitos de seguridad de transporte, residencia de datos, retención y supervisión operativa.
• Tratar la memoria generada como datos de aplicación y salida no confiable: las memorias extraídas, los resúmenes y las tarjetas de contexto son salidas derivadas. Revise cómo la aplicación los utiliza, especialmente antes de que influyan en acciones con privilegios, llamadas a herramientas externas o decisiones visibles para el cliente.
• Seleccionar extracción asíncrona solo cuando las escrituras derivadas retrasadas son aceptables: en el modo en segundo plano, las escrituras de mensajes raw se pueden completar antes de que se escriban memorias derivadas, resúmenes o estados de tiempo de ejecución relacionados. Si un flujo de trabajo requiere revisión o un límite de confirmación más estricto antes de que el estado derivado del modelo sea duradero, utilice la extracción en línea o desactive la extracción automática para ese flujo de trabajo.
• Cuenta para inyección de petición de datos persistente: el texto proporcionado por el emisor de llamada, recuperado o derivado del modelo almacenado en la memoria se puede reproducir en peticiones de datos de agente, extracción, tarjeta de contexto o resumen posteriores. Los delimitadores de petición de datos, las instrucciones de escape y extracción pueden ayudar a estructurar la entrada del modelo, pero no son un límite de seguridad. Revise las memorias extraídas, los resúmenes, las tarjetas de contexto y otros textos intermedios persistentes o vinculados a mensajes antes de confiar en ellos. Si el flujo de trabajo requiere revisión antes de que el texto derivado del modelo pueda influir en la futura extracción o construcción del contexto, desactive la extracción automática y utilice escrituras de memoria explícitas u otra puerta de revisión controlada por la aplicación.
• Sanitize o escape de texto derivado para su destino: si las memorias, resúmenes, tarjetas de contexto u otro texto derivado del modelo extraídos se presentan en HTML, Markdown, plantillas, logs u otras superficies de salida, aplique el escape o la sanitización adecuados al contexto. Utilice el mismo cuidado antes de reutilizar el texto derivado en peticiones de datos descendentes, entradas de herramientas, comandos u otros contextos similares a los de un intérprete.
• Seleccione el modo operativo correcto: si la aplicación necesita revisión antes de que el texto derivado del modelo pueda influir en la extracción posterior o la construcción del contexto, considere el uso de escrituras de memoria explícitas, integraciones de solo almacenamiento o memory_extraction_config=MemoryExtractionConfig(extract_memories=False) para flujos de trabajo que no deben realizar la extracción automática.

Consideraciones sobre la persistencia y la minimización de datos

La memoria del agente de Oracle AI está diseñada para mantener mensajes, memorias, metadatos e incrustaciones en Oracle 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:

• Para el uso de solo almacenamiento, mantenga solo lo necesario: diseñe la aplicación para que solo se escriba contenido útil y adecuado para el negocio en el almacén de memoria.
• Cuando las funciones de memoria activa están activadas, planifique los registros derivados: además del contenido proporcionado por el emisor de llamada, como mensajes y metadatos, un flujo de trabajo también puede mantener las memorias extraídas, los resúmenes o las incrustaciones.
• Tratar las rutas de memoria con capacidad de escritura como de confianza: las credenciales de base de datos y las rutas de código de backend que pueden escribir mensajes, resúmenes, memorias, metadatos, incrustaciones o estado de tiempo de ejecución de thread pueden afectar a futuras peticiones de datos y resultados de recuperación. Las funciones de memoria activa mantienen intencionadamente el estado derivado del modelo; si eso no es adecuado para un flujo de trabajo, desactive la extracción automática o utilice una integración de solo almacenamiento/escritura manual con controles de aplicación más estrechos.
• Seleccione el ámbito de supresión correcto para el trabajo de retención: delete_message() solo elimina el registro de mensaje sin formato. Las memorias derivadas u otros artefactos de ámbito de thread descendente creados a partir de ese mensaje pueden seguir siendo buscables porque las memorias extraídas no persisten actualmente por procedencia de mensaje. Cuando necesite una limpieza de ámbito de thread que también elimine las memorias asociadas y los datos de recuperación gestionados, utilice OracleAgentMemory.delete_thread().
• Planifique el límite de supresión y cierre para el trabajo en segundo plano: delete_thread(), delete_user(cascade=True) y delete_agent(cascade=True) esperan solo la extracción en segundo plano aceptada anteriormente que ya conoce ese cliente cuando se inicia la espera. No son una barrera de simultaneidad global en otros identificadores, componentes o procesos, y las escrituras simultáneas durante la supresión no se admiten. Cuando un límite de retención o cierre requiere una extracción en segundo plano ya aceptada del cliente actual para terminar primero, llame a wait_for_memory_extraction() antes de cerrar el proceso o realizar operaciones administrativas relacionadas.
• Definir políticas de retención y supresión por adelantado: si la aplicación ofrece compromisos de supresión o retención, asegúrese de que cubren mensajes sin procesar, memorias extraídas, metadatos y otros registros relacionados creados por el flujo de trabajo. Seleccione los valores ttl_days por registro y el esquema memory_retention_config en función del tipo de información esperado en cada registro, el motivo por el que la aplicación debe conservarla y cualquier compromiso de retención aplicable. Utilice la caducidad automática cuando los registros se deban depurar por antigüedad y verifique que el trabajo de depuración de Oracle gestionado esté presente en despliegues respaldados por base de datos, especialmente cuando el usuario de configuración del esquema no tenga privilegios de trabajo del programador.
• Plan para la carga de la base de datos de trabajo de depuración: el trabajo de depuración gestionado de Oracle se ejecuta en un programa y suprime las filas caducadas de las tablas gestionadas por SDK en lotes en lugar de como una supresión grande. Supervise el tiempo de ejecución, la generación de redo/deshacer, el historial de ejecuciones omitidas y el volumen de filas en entornos con altas tasas de escritura o grandes lotes de caducidad, y ajuste la configuración de retención o los planes de implementación operativos si la actividad de depuración se puede solapar con cargas de trabajo de base de datos sensibles a la latencia. El trabajo gestionado define un schedule_limit de un día, por lo que las ejecuciones con retraso demasiado largo se pueden omitir en lugar de iniciarse de forma arbitraria con retraso.
• Evitar confiar en la memoria como fuente de datos: las memorias almacenadas están destinadas a mejorar el contexto y la recuperación. Las aplicaciones deben seguir dependiendo de sistemas autorizados para tomar decisiones importantes.

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

La memoria del agente de Oracle AI 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:

• Asignación de reglas de aplicación al ámbito de memoria: asegúrese de que los ámbitos que la aplicación transfiere al SDK coinciden con las reglas de inquilino, usuario y uso compartido de datos.
• Transferir un ámbito de usuario explícito en cada búsqueda de cliente: derive user_id del contexto de solicitud autenticada en lugar de la solicitud de JSON u otra entrada controlada por el emisor de llamada y proporciónela en cada llamada de nivel superior OracleAgentMemory.search() o search_async(). Utilice user_id=None solo para flujos de trabajo restringidos intencionalmente a registros sin ámbito.
• Preferir el ámbito más estrecho que satisfaga el caso de uso: utilice filtros de coincidencia exacta y más estrictos para los flujos de trabajo que gestionan datos más confidenciales.
• Revisar la recuperación de threads cruzados de forma intencionada: una recuperación más amplia puede mejorar la continuidad entre sesiones, pero las aplicaciones solo deben activarla cuando ese comportamiento sea adecuado.
• Tratar los resultados de búsqueda como contenido recuperado, no como decisiones finales: las memorias devueltas pueden ser relevantes, pero la aplicación sigue siendo responsable de decidir si se deben mostrar o en qué medida se deben actuar.
• Manejar el texto recuperado de forma segura en el límite de integración: los registros recuperados pueden incluir texto proporcionado por el emisor de llamada o derivado del modelo. Si las memorias recuperadas u otro texto devuelto se presentan en HTML, Markdown, plantillas, logs u otras superficies de salida, aplique el escape o la desinfección apropiados para el contexto antes de mostrarlo, transformarlo o pasarlo a sistemas descendentes.

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

La memoria del agente de Oracle AI debe ser llamada 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 memoria del agente de Oracle AI. 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:

• Tratar user_id como entrada de aplicación sensible a la seguridad: si la aplicación de integración deriva user_id de la solicitud JSON u otra entrada controlada por el emisor de llamada en lugar de contexto autenticado, eso puede permitir el acceso a la memoria entre usuarios. Derive user_id del contexto de la aplicación autenticada en lugar de permitir que los usuarios finales elijan valores arbitrarios.
• Aplicar autorización de aplicación antes de cada llamada de memoria: la aplicación de integración debe decidir qué valores de ámbito de búsqueda, user_id, agent_id y thread_id son válidos para la solicitud actual y mantener las lecturas y escrituras dentro del límite de usuario y inquilino previsto.
• No exponer las API de memoria raw a los usuarios finales: las API de paquete como add_memory o los ayudantes de búsqueda deben ajustarse a la lógica de aplicación que valida el emisor de llamada, aplica la política y controla los datos que se pueden escribir o devolver.
• Mantener la detección y enumeración de ID de usuario con privilegios: si el paquete agrega ayudantes para mostrar o enumerar valores user_id, trátelos solo como capacidades administrativas y nunca los exponga a los usuarios finales mediante la aplicación de integración.
• Revisar cuidadosamente las sustituciones de ámbito: cualquier flujo de trabajo que amplíe el ámbito de thread, desactive la coincidencia exacta o se desplace a API de almacén de nivel inferior debe restringirse a componentes de confianza y revisarse para detectar efectos entre usuarios o entre inquilinos.

Consideraciones sobre el registro y el diagnóstico

La memoria del agente de Oracle AI 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:

• Mantener despliegues de producción en un nivel que no sea DEBUG: el registro DEBUG solo está diseñado para el desarrollo controlado o el diagnóstico de soporte y no es adecuado para la recopilación de logs de producción.
• Limitar el acceso a los logs de diagnóstico: almacene los logs en los fregaderos protegidos con las políticas adecuadas de control de acceso, retención y uso compartido. Revise los paquetes de soporte antes de enviar logs fuera del entorno operativo.
• Evitar agregar contexto confidencial en los envoltorios de registro de aplicaciones: no enriquezca los registros de log del SDK con peticiones de datos, contenido de memoria, credenciales, metadatos raw, valores de fila de base de datos ni identificadores controlados por el emisor de llamada.
• Tratar el texto del log como salida de diagnóstico, no como una interfaz de auditoría: los mensajes de log pueden ayudar a solucionar problemas del comportamiento del SDK, pero las aplicaciones deben utilizar sus propios eventos de auditoría explícitos para los flujos de trabajo de seguridad y conformidad.

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

La memoria del agente de Oracle AI utiliza una conexión o un pool de Oracle Database proporcionado 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 Database activado para TLS a la memoria del agente de Oracle AI. 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 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:

• Usar usuarios de base de datos con solo los privilegios necesarios: otorgue solo lo necesario para el modelo de despliegue y la política de esquema seleccionados.
• Utilice un usuario de base de datos independiente para los flujos de trabajo de supresión cuando sea práctico: si la aplicación necesita eliminar registros, prefiera una conexión o un pool dedicados para esas rutas y otorgue DELETE en las tablas de memoria del agente de Oracle AI gestionadas solo a ese usuario de base de datos. Mantenga la conexión principal en tiempo de ejecución limitada a los privilegios de no supresión necesarios para sus operaciones normales, de modo que las supresiones accidentales o no deseadas tengan un radio de influencia más estrecho. Si un emisor de llamada llama a delete() a través de una conexión que no tiene permiso DELETE, Oracle Database rechaza la sentencia.
• Crear pools y conexiones de base de datos cifrados: el código de producción debe transferir una conexión o un pool de Oracle Database activado para TLS al SDK. La memoria del agente de Oracle AI utiliza la conexión o el pool proporcionados por el emisor de llamada exactamente como se indica, por lo que para python-oracledb se prefieren las conexiones activadas para TLS, como protocol="tcps" o un DSN de TCPS equivalente, se configura la cartera o el material de CA necesarios y se mantiene activada la validación del certificado del servidor.
• Mantener la política de esquema por defecto a menos que necesite explícitamente cambios de DDL: SchemaPolicy.REQUIRE_EXISTING es el valor por defecto y evita la creación, modificación o borrado de objetos de esquema durante el inicio normal de la aplicación.
• Restricción de los modos de configuración destructivos: SchemaPolicy.RECREATE está diseñado para flujos de trabajo de configuración, prueba o administración y no se debe utilizar en rutas de producción normales.
• Confíe en rutas SQL gestionadas por paquetes, no en el ensamblaje SQL dinámico en el código de aplicación: en las rutas de base de datos gestionadas, los valores de registro y los filtros de búsqueda se envían con variables de enlace y los nombres de objetos gestionados se derivan de prefijos validados.
• Proteger la conexión y las credenciales del proveedor: almacene la base de datos, el LLM y embeba credenciales en un gestor de secretos como OCI Vault, y rotelas regularmente.
• Prefiera TLS validado en modo Thin y Thick: los documentos oficiales de python-oracledb indican que tanto los modos Thin como Thick admiten TLS, y que el modo Thick también puede utilizar el cifrado de red nativa de Oracle, donde ese es el estándar aprobado.
• Utilizar el transporte seguro a la base de datos: la seguridad de red de la base de datos, la configuración de TLS y el método de autenticación están determinados por la conexión proporcionada por el emisor de llamada y deben seguir los estándares de la organización.

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

La memoria del agente de Oracle AI se puede comunicar con servicios externos cuando el despliegue configura el LLM remoto o incrusta 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:

• Utilice HTTPS para puntos finales de modelo y prefiera rutas de red privadas o restringidas cuando estén disponibles.
• Supervise el tráfico saliente y el uso del proveedor para destinos inesperados, volúmenes de solicitud inusuales o consumo de token anómalo.
• Elige proveedores que se ajusten a tus necesidades de cumplimiento y residencia antes de habilitar funciones de memoria activa en flujos de trabajo regulados o confidenciales.

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:

• Definir límites prácticos de mensajes y peticiones de datos: configure valores como max_message_token_length y memory_extraction_token_limit para que se ajusten a los límites de carga de trabajo y proveedor. max_message_token_length limita la copia de tiempo de petición de datos utilizada por los flujos de trabajo de extracción; los mensajes almacenados no se modifican.
• Tamaños de recuperación de enlaces: utilice valores max_results razonables y filtros de tipo de registro para las búsquedas de aplicaciones.
• Aplicar límites de infraestructura fuera del SDK: utilice cuotas de base de datos, límites de conexión, controles de red, timeouts de punto final y limitación de frecuencia en el despliegue que lo rodea.
• Supervise el crecimiento a lo largo del tiempo: realice un seguimiento del volumen de mensajes almacenados, el crecimiento duradero de la memoria, el uso del proveedor y la latencia de las consultas para que se puedan realizar cambios de retención o ajuste antes de que afecten a la fiabilidad.