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. Validez et minimisez le contenu avant d'entrer dans le pipeline de mémoire, et évitez d'inclure des clés secrètes, des informations d'identification ou des données sensibles inutiles dans les messages ou les mémoires. 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.

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é. Traitez les mémoires dérivées d'un cycle automatique comme non fiables jusqu'à ce que votre application les ait examinées.
Sanitiser ou échapper du texte dérivé pour sa destination : Avant de rendre le contenu dérivé du modèle en HTML, Markdown, modèles, journaux ou 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 a besoin d'un contrôle total sur ce qui devient une mémoire durable, 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.
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 de niveau supérieur OracleAgentMemory.search() et search_async() nécessitent également une mise en correspondance d'utilisateur user_id concrète et exacte. Ils rejettent l'étendue d'utilisateur omise, user_id=None et exact_user_match=False, de sorte que l'API du client public ne recherche pas accidentellement plusieurs utilisateurs.

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 étendue d'utilisateur explicite à chaque recherche de client : Dérivez user_id du contexte de demande authentifiée et fournissez-le à chaque appel OracleAgentMemory.search() ou search_async() de niveau supérieur.
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.
Gérer le texte extrait en tant que contenu non approuvé 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. Validez, désinfectez ou échappez ce contenu selon les besoins de la destination avant de l'afficher, de le transformer 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. Il ne s'agit pas d'une limite de sécurité orientée utilisateur final, et il n'effectue pas d'authentification ou d'autorisation de l'utilisateur final seul. 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é : 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 à 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. Lorsque vous utilisez 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.
Créer des connexions et des groupes de bases de données chiffrés : 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 pour les invites et les messages : Configurez des valeurs telles que max_message_token_length et memory_extraction_token_limit en fonction des limites de charge de travail et de fournisseur.
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é.