Eléments à prendre en compte pour la sécurité

Portée : cet article traite des considérations de sécurité liées au kit SDK Python de mémoire d'agent. Elle s'applique aux applications qui utilisent les fonctionnalités de mémoire active du kit SDK ou la couche de stockage uniquement.

Pourquoi est-ce important ? La mémoire d'agent peut rendre persistants les enregistrements de contenu et de mémoire de thread dans Oracle AI Database et, lorsque les fonctionnalités soutenues par le LLM sont activées, envoyer du contenu aux adresses de modèle configurées pour l'agrégation, l'extraction de mémoire ou les incorporations. Le déploiement sécurisé dépend donc d'un traitement minutieux des données d'application, de la portée de l'extraction, de l'accès à la base de données, des adresses de modèle externe et des stratégies de conservation.

Remarques concernant le traitement de la mémoire sauvegardée par LLM

La mémoire de l'agent prend en charge des fonctions de mémoire active telles que la synthèse des threads et l'extraction automatique de la mémoire. Lorsque ces fonctionnalités sont activées, le kit SDK peut envoyer des messages récents, des récapitulatifs de threads, des mémoires extraites ou du texte de recherche au LLM configuré ou à l'adresse d'intégration.

Remarque : envoyez uniquement le contenu à la mémoire d'agent approprié à l'adresse de modèle configurée et aux stratégies de déploiement. Si la mémoire active est activée pour les données qui semblent inclure des clés secrètes, des informations d'identification ou des données confidentielles inutiles, réduisez ou occultez ce contenu avant que les messages n'entrent dans le pipeline de mémoire. Traitez les mémoires extraites, les résumés, les cartes de contexte et tout autre texte dérivé du modèle comme une sortie non fiable qui doit être examinée et gérée en toute sécurité par l'application d'intégration.

Avertissement : le texte dérivé d'un modèle peut devenir un état de mémoire persistant. Lorsque les fonctionnalités d'extraction automatique, d'agrégation ou de carte contextuelle sont activées, le kit SDK peut insérer un enregistrement récapitulatif, extrait ou extrait dans des invites ultérieures, telles que l'extraction de mémoire, l'agrégation, la carte contextuelle ou les invites d'agent, avant que l'application puisse vérifier cette valeur intermédiaire spécifique. Traitez cela comme un flux de données LLM non sécurisé normal : vérifiez et validez les sorties consommées par votre application, et ne laissez pas le contenu dérivé de la mémoire autoriser des actions privilégiées ou contourner la stratégie.

Suivez les recommandations suivantes lors de l'utilisation des fonctionnalités de mémoire active :

• Valider et réduire les données d'application : vérifiez les messages, métadonnées et ID que votre application envoie au kit SDK. Évitez de transmettre plus de données que le workflow de mémoire n'en a besoin.

• Utiliser des adresses de modèle sécurisé : configurez le LLM et intégrez des adresses qui répondent à vos exigences en matière de sécurité du transport, de résidence des données, de conservation et de surveillance opérationnelle.

• Traiter la mémoire générée en tant que données d'application et sortie non sécurisée : les mémoires extraites, les résumés et les cartes de contexte sont des sorties dérivées. Examinez comment votre application les utilise, en particulier avant qu'elles n'influencent les actions privilégiées, les appels d'outils externes ou les décisions visibles par le client.

• Compte pour l'injection d'invite persistante : le texte fourni par l'appelant, extrait ou dérivé du modèle stocké en mémoire peut être réexécuté dans des invites d'agrégation, d'extraction, de carte de contexte ou d'agent ultérieures. Les délimiteurs d'invite, les instructions d'échappement et d'extraction peuvent aider à structurer l'entrée du modèle, mais ils ne constituent pas une limite de sécurité. Passez en revue les mémoires extraites, les résumés, les cartes de contexte et tout autre texte intermédiaire persistant ou lié à une invite avant de compter sur elles. Si votre workflow nécessite une révision avant que le texte dérivé du modèle puisse influencer l'extraction future ou la construction du contexte, désactivez l'extraction automatique et utilisez des écritures de mémoire explicites ou une autre porte de révision contrôlée par l'application.

• Sanitize ou texte dérivé d'échappement pour sa destination : si les mémoires extraites, les résumés, les cartes de contexte ou tout autre texte dérivé d'un modèle sont affichés au format HTML, Markdown, les modèles, les journaux ou d'autres surfaces de sortie, appliquez une évacuation ou un nettoyage adapté au contexte. Faites attention avant de réutiliser du texte dérivé dans des invites en aval, des entrées d'outil, des commandes ou d'autres contextes de type interprète.

• Choisir le bon mode de fonctionnement : si votre application doit être vérifiée avant que le texte dérivé du modèle puisse influencer l'extraction ultérieure ou la construction du contexte, envisagez d'utiliser des écritures de mémoire explicites, des intégrations en magasin uniquement ou extract_memories=False pour les workflows qui ne doivent pas effectuer d'extraction automatique.

Considérations concernant la persistance et la minimisation des données

La mémoire d'agent est conçue pour rendre persistants les messages, les mémoires, les métadonnées et les incorporations dans Oracle AI Database lorsque l'emplacement de stockage sauvegardé par la base de données est utilisé. Cela permet une extraction durable et une mémoire intersession, mais cela signifie également que l'application doit planifier les données à conserver.

Les conseils suivants vous aident à aligner les déploiements sur les pratiques de gestion des données sécurisées :

• Pour une utilisation en mode "store-only", ne conserver que ce qui est nécessaire : concevez votre application de sorte que seul le contenu utile et adapté à l'entreprise soit écrit dans la banque de mémoire.

• Lorsque les fonctions de mémoire active sont activées, planifier les enregistrements dérivés : outre le contenu fourni par l'appelant, tel que les messages et les métadonnées, un workflow peut également rendre persistantes les mémoires extraites, les récapitulatifs ou les incorporations.

• Traiter les chemins de mémoire pouvant faire l'objet d'une écriture comme sécurisés : les informations d'identification de base de données et les chemins de code back-end qui peuvent écrire des messages, des récapitulatifs, des mémoires, des métadonnées, des intégrations ou l'état d'exécution des threads peuvent avoir une incidence sur les invites futures et les résultats d'extraction. Les fonctionnalités de mémoire active conservent intentionnellement l'état dérivé du modèle. Si cela n'est pas approprié pour un workflow, désactivez l'extraction automatique ou utilisez une intégration de stockage uniquement/écriture manuelle avec des contrôles d'application plus étroits.

• Choisir la portée de suppression appropriée pour le travail de conservation : delete_message() enlève uniquement l'enregistrement de message brut. Les mémoires dérivées ou d'autres artefacts de portée thread en aval créés à partir de ce message peuvent rester consultables car les mémoires extraites ne persistent pas actuellement par provenance de message. Lorsque vous avez besoin d'un nettoyage de portée thread qui supprime également les mémoires associées et les données vectorielles/de bloc gérées, utilisez OracleAgentMemory.delete_thread().

• Définir les stratégies de conservation et de suppression à l'avance : si votre application propose des engagements de suppression ou de conservation, assurez-vous qu'ils couvrent les messages bruts, les mémoires extraites, les métadonnées et les autres enregistrements associés créés par le workflow.

• Evitez de compter sur la mémoire comme source d'informations fiables : les mémoires stockées sont destinées à améliorer le contexte et l'extraction. Les applications devraient continuer à s'appuyer sur des systèmes faisant autorité pour prendre des décisions importantes.

Remarques concernant la portée de l'extraction et le contrôle d'accès

La mémoire d'agent utilise les valeurs user_id, agent_id et thread_id fournies par l'appelant pour l'extraction de la portée. Il s'agit d'un modèle de filtrage puissant, mais il ne doit pas être le seul contrôle sur lequel repose votre application lorsque vous décidez de la façon dont le contenu extrait est utilisé ou affiché.

Par défaut, l'extraction de niveau thread utilise la correspondance exacte pour user_id et agent_id, ainsi qu'une correspondance plus large pour thread_id afin que les résultats pertinents puissent couvrir les threads passés pour la même paire utilisateur-agent. Les appels de niveau supérieur OracleAgentMemory.search() et search_async() nécessitent également une portée explicite des utilisateurs et une mise en correspondance exacte des utilisateurs. Ils rejettent la portée utilisateur omise et exact_user_match=False afin que l'API client publique ne recherche pas accidentellement sur plusieurs utilisateurs. La transmission de user_id=None est autorisée uniquement avec une correspondance utilisateur exacte et cible uniquement les enregistrements non ciblés.

Utilisez les exercices suivants lors de la conception de l'extraction :

• Mettre en correspondance les règles d'application avec la portée de mémoire : assurez-vous que les portées transmises à l'application au kit SDK correspondent aux règles de locataire, d'utilisateur et de partage de données.

• Transmettre une portée utilisateur explicite à chaque recherche de client : dériver le paramètre user_id du contexte de demande authentifiée plutôt que de la demande JSON ou d'une autre entrée contrôlée par l'appelant, et le fournir sur chaque appel de niveau supérieur OracleAgentMemory.search() ou search_async(). Utilisez user_id=None uniquement pour les workflows intentionnellement limités aux enregistrements non ciblés.

• Préférer la portée la plus étroite qui satisfait le cas d'emploi : utilisez des filtres de correspondance et de resserrement exacts pour les workflows qui gèrent des données plus sensibles.

• Vérifier l'extraction interthread intentionnellement : l'extraction plus large peut améliorer la continuité entre les sessions, mais les applications ne doivent l'activer que lorsque cette approche est appropriée.

• Traiter les résultats de la recherche en fonction du contenu extrait, et non des décisions finales : les mémoires renvoyées peuvent être pertinentes, mais l'application reste responsable de décider si et comment elles doivent être affichées ou traitées.

• Gérer le texte extrait en toute sécurité au niveau de la limite d'intégration : les enregistrements extraits peuvent inclure du texte fourni par l'appelant ou dérivé du modèle. Si des mémoires récupérées ou d'autres textes renvoyés sont affichés en HTML, Markdown, des modèles, des journaux ou d'autres surfaces de sortie, appliquez une évacuation ou une désinfection appropriée au contexte avant de l'afficher, de le transformer, de le consigner ou de le transmettre aux systèmes en aval.

Considérations relatives à l'intégration des applications et à la confiance des appelants

La mémoire d'agent est destinée à être appelée par l'application d'intégration ou par un autre code back-end sécurisé, et non directement par les utilisateurs finaux. Les API de mémoire brute ne sont pas une limite de sécurité destinée à l'utilisateur final, et elles n'effectuent pas d'authentification ou d'autorisation de l'utilisateur final par elles-mêmes. Le package fait confiance à l'appelant pour fournir la portée d'extraction user_id, agent_id, thread_id et la portée d'extraction correcte pour chaque opération.

Remarque : l'application d'intégration est responsable de l'authentification de l'utilisateur final, de l'autorisation de l'accès et de la dérivation du paramètre user_id et de la portée appropriés avant d'appeler les API de mémoire d'agent. Une valeur user_id fournie par l'appelant est une valeur de portée et non une preuve d'identité.

Utilisez les exercices suivants lors de l'intégration du kit SDK dans une application agénétique :

• Traiter user_id en tant qu'entrée d'application sensible à la sécurité : si l'application d'intégration dérive user_id de la demande JSON ou d'une autre entrée contrôlée par l'appelant au lieu du contexte authentifié, cela peut autoriser l'accès à la mémoire inter-utilisateur. Dérivez user_id de votre contexte d'application authentifié au lieu de laisser les utilisateurs finaux choisir des valeurs arbitraires.

• Appliquer l'autorisation de l'application avant chaque appel de mémoire : l'application d'intégration doit décider quelles valeurs user_id, agent_id, thread_id et portée de recherche sont valides pour la demande en cours et conserver les lectures et écritures dans les limites du locataire et de l'utilisateur prévus.

• Ne pas exposer les API de mémoire brute aux utilisateurs finals : les API de package telles que add_memory ou les aides à la recherche doivent être encapsulées dans une logique d'application qui valide l'appelant, applique la stratégie et contrôle les données pouvant être écrites ou renvoyées.

• Conserver le repérage et l'énumération des ID utilisateur privilégiés : si le package ajoute des assistants pour répertorier ou énumérer les valeurs user_id, traitez-les uniquement en tant que fonctionnalités d'administration et ne les exposez jamais aux utilisateurs finaux via l'application d'intégration.

• Examinez attentivement les remplacements de portée : tout workflow qui élargit la portée des threads, désactive la mise en correspondance exacte ou abandonne les API de stockage de niveau inférieur doit être limité aux composants sécurisés et vérifié pour les effets inter-utilisateurs ou colocatifs.

Remarques concernant la journalisation et les diagnostics

La mémoire de l'agent utilise la journalisation Python standard et ne configure pas de gestionnaires de journaux d'application ni de niveaux de journaux pour l'application d'intégration. Si l'application d'intégration active la journalisation DEBUG pour le kit SDK, les journaux de débogage peuvent inclure des détails de dépannage supplémentaires. Conservez les déploiements de production à un niveau autre que DEBUG ; la journalisation DEBUG est uniquement destinée au développement contrôlé ou aux diagnostics de prise en charge et ne convient pas à la collecte de journaux de production.

Remarques concernant l'accès à la base de données, la gestion des schémas et les clés secrètes

La mémoire de l'agent utilise une connexion ou un pool Oracle AI Database fourni par l'appelant. Le package ne crée ni ne gère les informations d'identification et de connexion à la base de données. Il ne crée, ne négocie ni ne met à niveau le cryptage réseau de base de données pour le compte de l'appelant.

Remarque :

• Pour les déploiements de production, créez la connexion ou le pool Oracle AI Database avec le transport crypté activé avant de le transmettre à la mémoire de l'agent. N'utilisez pas de connexions de base de données en texte clair sur des réseaux non sécurisés, partagés ou externes. Lorsque vous utilisez python-oracledb, suivez la section officielle Cryptage sécurisé du trafic réseau vers Oracle AI Database et configurez TLS ou un autre transport crypté approuvé dans le cadre de la création de connexions ou de pools.

• N'intégrez jamais de clés d'API, de mots de passe ou d'autres clés secrètes directement dans le code d'application, la configuration réinsérée ou les artefacts exportés. Utilisez toujours des mécanismes d'injection sécurisés et respectez le principe du moindre privilège pour l'accès aux informations d'identification.

Les pratiques de déploiement suivantes sont recommandées :

• Utiliser les utilisateurs de base de données avec uniquement les privilèges requis : octroyez uniquement ce qui est nécessaire pour le modèle de déploiement et la stratégie de schéma sélectionnés.

• Utilisez un utilisateur de base de données distinct pour les workflows de suppression lorsque cela est possible : si votre application doit enlever des enregistrements, préférez une connexion ou un pool dédié pour ces chemins et accordez DELETE aux tables de mémoire d'agent géré uniquement à cet utilisateur de base de données. Conservez la connexion d'exécution principale limitée aux privilèges de non-suppression requis pour ses opérations normales afin que les suppressions accidentelles ou indésirables aient un rayon d'impact plus étroit. Si un appelant appelle delete() via une connexion qui ne dispose pas du droit d'accès DELETE, Oracle AI Database rejette l'instruction.

• Créer des pools et des connexions de base de données cryptées : le code de production doit transmettre au kit SDK une connexion ou un pool Oracle AI Database compatible TLS. La mémoire de l'agent utilise la connexion ou le pool exactement comme indiqué par l'appelant. Pour python-oracledb, préférez les connexions compatibles TLS telles que protocol="tcps" ou un DSN TCPS équivalent, configurez le portefeuille ou le matériel d'autorité de certification requis et maintenez la validation du certificat de serveur activée.

• Conservez la stratégie de schéma par défaut, sauf si vous avez explicitement besoin de modifications LDD : SchemaPolicy.REQUIRE_EXISTING est la valeur par défaut et évite de créer, de modifier ou de supprimer des objets de schéma lors du démarrage de l'application standard.

• Limiter les modes de configuration destructifs : SchemaPolicy.RECREATE est destiné aux workflows de configuration, de test ou d'administration et ne doit pas être utilisé dans les chemins de production standard.

• S'appuyer sur des chemins SQL gérés par package et non sur un assemblage SQL dynamique dans le code d'application : dans les chemins de base de données gérés, les valeurs d'enregistrement et les filtres de recherche sont envoyés avec des variables attachées et les noms d'objet géré sont dérivés de préfixes validés.

• Protéger les informations d'identification de connexion et de fournisseur : stockez la base de données, le LLM et l'intégration des informations d'identification dans un gestionnaire de clés secrètes tel qu'OCI Vault, et effectuez une rotation régulière.

• Préférer le protocole TLS validé en mode léger et épais : la documentation python-oracledb officielle indique que les modes léger et épais prennent en charge le protocole TLS, et que le mode épais peut également utiliser le cryptage réseau natif Oracle, où il s'agit de votre norme approuvée.

• Utiliser le transport sécurisé vers la base de données : la sécurité réseau de la base de données, la configuration TLS et la méthode d'authentification sont déterminées par la connexion fournie par l'appelant et doivent respecter les normes de votre organisation.

Remarques concernant la communication réseau et les adresses externes

La mémoire de l'agent peut communiquer avec des services externes lorsque le déploiement configure un LLM distant ou des fournisseurs d'intégration. Le kit SDK transmet les invites et les paramètres de demande via le chemin du client configuré, mais l'application et le déploiement environnants restent responsables de la sécurisation de ces connexions.

Nous recommandons de suivre les points suivants :

• Utilisez HTTPS pour les adresses de modèle et préférez les chemins réseau privés ou restreints, le cas échéant.

• Surveillez le trafic sortant et l'utilisation du fournisseur pour les destinations inattendues, le volume de demandes inhabituel ou la consommation de jetons anormale.

• Choisissez les fournisseurs qui répondent à vos besoins en matière de conformité et de résidence avant d'activer les fonctionnalités de mémoire active sur les workflows réglementés ou sensibles.

Considérations concernant les vecteurs d'épuisement des ressources

Les workflows de mémoire peuvent augmenter l'utilisation de la base de données, l'intégration du trafic et la consommation de jetons LLM au fil du temps. Cela est vrai à la fois pour une utilisation excessive malveillante et pour des erreurs de mise en œuvre innocentes telles que des messages surdimensionnés ou des modèles de récupération trop larges.

Utilisez les commandes suivantes dans le cadre de votre durcissement de production :

• Définir des limites d'invite et de message pratiques : configurez des valeurs telles que max_message_token_length et memory_extraction_token_limit pour qu'elles correspondent aux limites de charge globale et de fournisseur. max_message_token_length limite la copie d'invite utilisée par les workflows d'extraction ; les messages stockés restent inchangés.

• Tailles d'extraction liées : utilisez des valeurs max_results et des filtres de type d'enregistrement raisonnables pour les recherches d'application.

• Appliquer les limites d'infrastructure en dehors du kit SDK : utilisez les quotas de base de données, les limites de connexion, les contrôles réseau, les délais d'expiration des adresses et la limitation de débit dans le déploiement environnant.

• Surveiller la croissance au fil du temps : suivez le volume de messages stocké, la croissance durable de la mémoire, l'utilisation des fournisseurs et la latence des requêtes afin que les modifications de conservation ou de réglage puissent être apportées avant qu'elles n'affectent la fiabilité.