Considérations relatives à la sécurité

Portée : Cet article présente les considérations relatives à la sécurité concernant la trousse SDK Python pour mémoire d'agent. Il s'applique aux applications utilisant soit les fonctions de mémoire active du SDK, soit la couche de stockage uniquement.

Pourquoi cela est important : La mémoire de l'agent peut conserver le contenu de l'unité d'exécution et les enregistrements de mémoire dans Oracle AI Database et, lorsque les fonctions soutenues par le LLM sont activées, envoyer du contenu aux points d'extrémité de modèle configurés pour la récapitulation, l'extraction de mémoire ou les intégrations. Le déploiement sécurisé dépend donc d'une gestion minutieuse des données d'application, de la portée de l'extraction, de l'accès à la base de données, des points d'extrémité des modèles externes et des politiques de conservation.

Considérations relatives au traitement de la mémoire soutenue par le LLM

La mémoire de l'agent prend en charge les fonctions de mémoire active telles que la récapitulation des threads et l'extraction automatique de la mémoire. Lorsque ces fonctions sont activées, la trousse SDK peut envoyer des messages récents, des sommaires d'unité d'exécution, des mémoires récupérées ou rechercher du texte vers le LLM configuré ou le point d'extrémité d'intégration.

Note : Envoyez uniquement du contenu à la mémoire de l'agent approprié pour le point d'extrémité de modèle configuré et vos politiques de déploiement. Si la mémoire active est activée pour les données qui semblent inclure des clés secrètes, des données d'identification ou des données sensibles inutiles, réduisez ou expurgez 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 d'autres textes dérivés du modèle comme une sortie non sécurisée qui doit être examinée et gérée en toute sécurité par l'application d'intégration.

Avertissement : Le texte dérivé du modèle peut devenir un état de mémoire persistante. Lorsque les fonctions d'extraction automatique, de récapitulation ou de carte de contexte sont activées, un sommaire, une mémoire extraite ou un enregistrement extrait peut être inséré par la trousse SDK dans des invites ultérieures, telles que l'extraction de mémoire, la récapitulation, la carte de contexte 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 de LLM non approuvé 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 les actions privilégiées ou la politique de contournement.

Suivez ces recommandations lors de l'utilisation des fonctions de mémoire active :

• Valider et réduire les données d'application : Vérifiez les messages, les métadonnées et les ID envoyés par l'application dans la trousse SDK. Évitez de transmettre plus de données que ce dont le flux de travail de mémoire a besoin.

• Utiliser des points d'extrémité de modèle fiable : Configurez un LLM et des points d'extrémité d'intégration qui répondent à vos exigences en matière de sécurité du transport, d'emplacement des données, de conservation et de surveillance opérationnelle.

• Traiter la mémoire générée comme des données d'application et une sortie non sécurisée : Les mémoires extraites, les sommaires et les cartes de contexte sont des sorties dérivées. Vérifiez comment votre application les utilise, surtout 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é dans la mémoire peut être réexécuté dans des invites de récapitulation, 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 vous fier à eux. Si votre flux de travail 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 un autre point de contrôle contrôlé par l'application.

• Sanctionner ou échapper du texte dérivé pour sa destination : Si les mémoires extraites, les sommaires, les cartes de contexte ou tout autre texte dérivé du modèle sont rendus en HTML, Markdown, les modèles, les journaux ou d'autres surfaces de sortie, appliquez un échappement ou une désinfection adapté au contexte. Faites preuve de la même prudence 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éteur.

• Sélectionner le mode de fonctionnement approprié : Si votre application doit être révisé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 flux de travail qui ne doivent pas effectuer d'extraction automatique.

Considérations relatives à la persistance et à la réduction des données

La mémoire de l'agent est conçue pour conserver les messages, les mémoires, les métadonnées et les intégrations dans Oracle AI Database lorsque le magasin soutenu par la base de données est utilisé. Cela permet une récupération durable et une mémoire intersessions, mais cela signifie également que l'application doit planifier les données à conserver.

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

• Pour une utilisation en magasin uniquement, conservez uniquement les informations nécessaires : Concevez votre application de sorte que seul le contenu utile adapté à l'entreprise soit écrit dans le magasin de mémoire.

• Lorsque les fonctions de mémoire active sont activées, planifiez les enregistrements dérivés : En plus du contenu fourni par l'appelant, tel que les messages et les métadonnées, un flux de travail peut également conserver les mémoires extraites, les sommaires ou les intégrations.

• Traiter les chemins de mémoire activés pour l'écriture comme approuvés : Les données d'identification de base de données et les chemins de code dorsal qui peuvent écrire des messages, des sommaires, des mémoires, des métadonnées, des intégrations ou l'état d'exécution d'unité d'exécution peuvent avoir une incidence sur les invites futures et les résultats d'extraction. Les fonctions de mémoire active persistent intentionnellement à l'état dérivé du modèle. Si cela n'est pas approprié pour un flux de travail, désactivez l'extraction automatique ou utilisez une intégration de stockage uniquement/écriture manuelle avec des contrôles d'application plus stricts.

• Sélectionner la portée de suppression appropriée pour le travail de conservation : delete_message() supprime 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/fragment gérées, utilisez OracleAgentMemory.delete_thread().

• Définir les politiques de conservation et de suppression à l'avance : Si votre application offre 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 connexes créés par le flux de travail.

• Éviter de compter sur la mémoire comme source de vérité : Les mémoires stockées sont destinées à améliorer le contexte et l'extraction. Les demandes doivent continuer de s'appuyer sur des systèmes faisant autorité pour prendre des décisions importantes.

Considérations relatives à la portée de l'extraction et au contrôle d'accès

La mémoire de l'agent utilise les valeurs user_id, agent_id et thread_id fournies par l'appelant pour définir la portée de l'extraction. Il s'agit d'un modèle de filtrage puissant, mais il ne devrait pas être le seul contrôle sur lequel votre application s'appuie pour décider comment le contenu extrait est utilisé ou affiché.

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

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

• Mapper les règles d'application à la portée de la mémoire : Assurez-vous que les portées que votre application transmet à la trousse SDK correspondent aux règles de location, d'utilisateur et de partage de données.

• Transmettre une portée d'utilisateur explicite à chaque recherche de client : Dériver user_id à partir du contexte de demande authentifiée plutôt qu'à partir de la demande JSON ou d'une autre entrée contrôlée par l'appelant, et la fournir à chaque appel OracleAgentMemory.search() ou search_async() de niveau supérieur. Utilisez user_id=None uniquement pour les flux de travail intentionnellement limités aux enregistrements sans portée.

• Préférer la portée la plus étroite répondant au cas d'utilisation : Utilisez des filtres de mise en correspondance exacte et plus stricts pour les flux de travail qui traitent des données plus sensibles.

• Vérifier intentionnellement l'extraction interunité d'exécution : Une extraction plus étendue 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 recherche comme du contenu extrait, et non comme des décisions finales : Les mémoires retournées peuvent être pertinentes, mais l'application reste responsable de décider si et comment elles doivent être affichées ou traitées.

• Traiter 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 les mémoires récupérées ou tout autre texte retourné sont rendus en HTML, Markdown, modèles, journaux ou autres surfaces de sortie, appliquez un échappement ou une désinfection approprié 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 un autre code dorsal approuvé, et non directement par les utilisateurs finaux. Les API de mémoire brute ne sont pas une limite de sécurité orientée utilisateur final et n'effectuent pas d'authentification ou d'autorisation de l'utilisateur final par elles-mêmes. L'ensemble fait confiance à l'appelant pour fournir la portée user_id, agent_id, thread_id et l'extraction correctes pour chaque opération.

Note : L'application d'intégration est responsable de l'authentification de l'utilisateur final, de l'autorisation d'accès et de la détermination du user_id et de la portée corrects avant d'appeler les API de mémoire de l'agent. Un appelant fourni user_id est une valeur de portée, et non une preuve d'identité.

Utilisez les exercices suivants lors de l'intégration de la trousse SDK dans une application agéntique :

• Traiter user_id comme 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 d'un contexte authentifié, ce qui peut autoriser l'accès à la mémoire inter-utilisateur. Dérivez user_id du contexte d'application authentifié au lieu de permettre aux utilisateurs finaux de 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 de portée user_id, agent_id, thread_id et de recherche sont valides pour la demande courante et conserver les lectures et les écritures dans le périmètre de client et d'utilisateur prévu.

• Ne pas exposer les API de mémoire brute aux utilisateurs finaux : Les API d'ensemble telles que add_memory ou les outils d'aide à la recherche doivent être encapsulées dans une logique d'application qui valide l'appelant, applique une politique et contrôle les données pouvant être écrites ou retournées.

• Garder les privilèges de détection et d'énumération d'ID utilisateur : Si l'ensemble ajoute des outils d'aide pour lister ou énumérer des valeurs user_id, traitez-les comme des capacités administratives uniquement et ne les exposez jamais aux utilisateurs finaux au moyen de l'application d'intégration.

• Vérifier les remplacements de portée avec soin : Tout flux de travail qui étend la portée de l'unité d'exécution, désactive la mise en correspondance exacte ou abandonne les API de magasin de niveau inférieur doit être limité aux composants approuvés et révisé pour les effets interutilisateur ou interlocataire.

Considérations relatives à la journalisation et aux diagnostics

La mémoire de l'agent utilise la journalisation Python standard et ne configure pas les programmes de traitement ou les niveaux de journal des applications pour l'application d'intégration. Si l'application d'intégration active la journalisation DEBUG pour la trousse SDK, les journaux de débogage peuvent inclure des détails de dépannage supplémentaires. Conserver les déploiements de production à un niveau autre que DEBUG; la journalisation DEBUG est destinée uniquement aux diagnostics de développement ou de soutien contrôlés et ne convient pas à la collecte des journaux de production.

Considérations relatives à l'accès aux bases de données, à la gestion des schémas et aux clés secrètes

La mémoire de l'agent utilise une connexion ou une réserve Oracle AI Database fournie par l'appelant. L'ensemble ne crée ni ne gère lui-même les données d'identification de la base de données. Il ne crée pas, ne négocie pas ou ne met pas à niveau le chiffrement du réseau de base de données au nom de l'appelant.

Note :

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

• 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 archivée ou les artefacts exportés. Utilisez toujours des mécanismes d'injection sécurisés et suivez le principe du moindre privilège pour l'accès aux données 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 : Accordez uniquement ce qui est nécessaire pour le modèle de déploiement et la politique de schéma sélectionnés.

• Utiliser un utilisateur de base de données distinct pour les flux de travail de suppression lorsque c'est pratique : Si votre application doit supprimer des enregistrements, préférez une connexion ou une réserve dédiée pour ces chemins et accordez DELETE sur les tables de mémoire de l'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'incidence plus étroit. Si un appelant appelle delete() au moyen d'une connexion qui n'a pas l'autorisation DELETE, Oracle AI Database rejette l'énoncé.

• Créer des connexions et des groupes de base de données chiffrés : Le code de production doit transmettre une connexion ou une réserve Oracle AI Database activée pour TLS à la trousse SDK. La mémoire de l'agent utilise la connexion ou la réserve exactement comme indiqué par l'appelant. Pour python-oracledb, préférez les connexions compatibles TLS telles que protocol="tcps" ou un nom de source de données TCPS équivalent, configurez le portefeuille ou le matériel de l'autorité de certification requis et conservez la validation du certificat du serveur activée.

• Conserver la politique 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 la création, la modification ou la suppression d'objets de schéma lors du démarrage standard de l'application.

• Restreindre les modes de configuration destructeurs : SchemaPolicy.RECREATE est destiné aux flux de travail 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 l'ensemble 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 de liaison et les noms d'objet géré sont dérivés de préfixes validés.

• Protéger les données d'identification de connexion et de fournisseur : Stockez la base de données, le GML et intégrez les données d'identification dans un gestionnaire de clés secrètes tel que OCI Vault, et effectuez une rotation régulière.

• Préférer le protocole TLS validé en mode mince et en mode épais : Les documents officiels sur python-oracledb indiquent que les modes mince et épais prennent en charge le protocole TLS, et le mode épais peut également utiliser le chiffrement réseau natif Oracle là où c'est votre norme approuvée.

• Utiliser le transport sécurisé vers la base de données : La sécurité du réseau de 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.

Considérations relatives à la communication réseau et aux points d'extrémité 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. La trousse SDK transmet les invites et les paramètres de demande au moyen du chemin du client configuré, mais l'application et le déploiement environnants restent responsables de la sécurité de ces connexions.

Nous recommandons ce qui suit :

• Utilisez HTTPS pour les points d'extrémité de modèle et préférez les chemins de réseau privés ou restreints lorsqu'ils sont disponibles.

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

• Sélectionnez des fournisseurs correspondant à vos besoins en matière de conformité et de résidence avant d'activer les fonctions de mémoire active dans les flux de travail réglementés ou sensibles.

Considérations relatives aux vecteurs d'épuisement des ressources

Les flux de travail de mémoire peuvent augmenter l'utilisation de la base de données, l'intégration du trafic et la consommation des 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 ces contrôles dans le cadre de votre durcissement de production :

• Définir des limites pratiques d'invite et de message : Configurez des valeurs telles que max_message_token_length et memory_extraction_token_limit pour s'adapter aux limites de votre charge de travail et de votre fournisseur. max_message_token_length limite la copie d'invite utilisée par les flux de travail d'extraction. Les messages stockés restent inchangés.

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

• Appliquer les limites d'infrastructure en dehors de la trousse SDK : Utilisez des quotas de base de données, des limites de connexion, des contrôles de réseau, des temporisations de point d'extrémité et une limitation de débit dans le déploiement environnant.

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