Consideraciones de seguridad

Ámbito: en este artículo se tratan las consideraciones de seguridad relacionadas con el SDK de Python de memoria de agente. 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 puede mantener el contenido del thread y los registros de memoria en Oracle AI Database y, cuando se activan las funciones respaldadas por LLM, enviar contenido a los puntos finales del modelo configurado para su resumen, extracción de memoria o incrustaciones. 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 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.

Nota: Solo envíe contenido a la memoria del agente 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 de LLM normal 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 ID 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.
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 enlazados 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 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 está diseñada 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:

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 vector/fragmento gestionados, utilice OracleAgentMemory.delete_thread().
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 abarcan mensajes raw, memorias extraídas, metadatos y otros registros relacionados creados por el flujo de trabajo.
Evite 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 basándose en sistemas autorizados para tomar decisiones importantes.

Consideraciones sobre Alcance de Recuperación y Control de Acceso

La memoria del agente 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 deben activarla solo cuando ese enfoque 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, registrarlo o pasarlo a sistemas descendentes.

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

La memoria del agente debe ser llamada por la aplicación de integración u otro código de backend de confianza, no directamente por los usuarios finales. Las API de memoria raw no son un límite de seguridad orientado al usuario final y no realizan 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.

Nota: 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. 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 agentic:

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 encapsularse en la lógica de aplicación que valida el emisor de llamada, aplica la política y controla qué datos 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 del 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 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. Si la aplicación de integración activa el registro DEBUG para el SDK, los logs de depuración pueden incluir detalles de solución de problemas adicionales. Mantenga los 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.

Consideraciones sobre Acceso a Bases de Datos, Gestión de Esquemas y Secretos

La memoria del agente 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 llamada.

Nota:

Para despliegues de producción, cree la conexión o el pool de Oracle AI Database con el transporte cifrado activado antes de transferirlo a la memoria del agente. 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.
Nunca embeba claves de API, contraseñas u otros secretos directamente en el código de la 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 suprimir flujos de trabajo cuando sea práctico: si la aplicación necesita eliminar registros, prefiera una conexión o un pool dedicados para esas rutas de acceso y otorgue DELETE en las tablas de memoria de agente 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 AI Database rechaza la sentencia.
Creación de conexiones y pools de bases de datos cifradas: el código de producción debe transferir una conexión o un pool de Oracle AI Database activado para TLS al SDK. La memoria del agente utiliza la conexión o el pool exactamente como lo proporciona el emisor de llamada. Para python-oracledb, prefiera conexiones activadas para TLS, como protocol="tcps" o un DSN de TCPS equivalente, configure la cartera o el material de CA necesarios y mantenga 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 de la aplicación estándar.
Restringir modos de configuración destructivos: SchemaPolicy.RECREATE está diseñado para flujos de trabajo de configuración, prueba o administración y no debe utilizarse en rutas de producción estándar.
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 los modos Thin y Thick admiten TLS, y 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 en red y los puntos finales externos

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

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 los 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.