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. Valide y minimice el contenido antes de que entre en el pipeline de memoria y evite incluir secretos, credenciales o datos confidenciales innecesarios en mensajes o memorias. 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.

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. Trate las memorias derivadas de un ciclo automático como no confiables hasta que su aplicación las haya revisado.
Sanitize o escape de texto derivado para su destino: antes de representar el contenido derivado del modelo 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 su aplicación necesita control total sobre lo que se convierte en memoria duradera, 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 una 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.
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 necesitan una coincidencia de usuario exacta y user_id concreta. Rechazan el ámbito de usuario omitido, user_id=None y exact_user_match=False para que la API de cliente pública no busque accidentalmente entre varios usuarios.

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: obtenga el user_id del contexto de solicitud autenticada y proporciónelo en cada llamada de nivel superior OracleAgentMemory.search() o search_async().
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 como contenido no confiable en el límite de integración: los registros recuperados pueden incluir texto proporcionado por el emisor de llamada o derivado del modelo. Valide, desinfecte o escape ese contenido según corresponda para el destino antes de mostrarlo, transformarlo o transferirlo 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. 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.

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: obtenga 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 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 de 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.
Crear pools y conexiones de base de datos cifrados: 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 de mensajes y peticiones de datos prácticos: 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 de proveedor.
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.