Considerazioni sulla sicurezza

Ambito: questo articolo tratta le considerazioni sulla sicurezza relative all'SDK Python della memoria agente. Si applica solo alle applicazioni che utilizzano le funzioni di memoria attiva dell'SDK o del layer di memorizzazione.

Perché è importante: la memoria agente può rendere persistenti i record di contenuto e memoria dei thread in Oracle AI Database e, quando le funzioni supportate da LLM sono abilitate, inviare il contenuto agli endpoint del modello configurati per il riepilogo, l'estrazione della memoria o l'integrazione. La distribuzione sicura dipende quindi da un'attenta gestione dei dati delle applicazioni, dall'ambito di recupero, dall'accesso al database, dagli endpoint dei modelli esterni e dai criteri di conservazione.

Considerazioni sull'elaborazione della memoria supportata da LLM

Agent Memory supporta funzioni di memoria attiva come il riepilogo dei thread e l'estrazione automatica della memoria. Quando queste funzioni sono abilitate, l'SDK può inviare messaggi recenti, riepiloghi dei thread, memorie recuperate o testo di ricerca all'LLM configurato o all'endpoint di incorporamento.

Nota: inviare solo il contenuto alla memoria dell'agente appropriato per l'endpoint del modello configurato e i criteri di distribuzione. Convalidare e ridurre al minimo il contenuto prima di entrare nella pipeline di memoria ed evitare di includere segreti, credenziali o dati sensibili non necessari nei messaggi o nelle memorie. Tratta le memorie estratte, i riepiloghi, le schede di contesto e altri testi derivati dal modello come output non attendibile che deve essere rivisto e gestito in modo sicuro dall'applicazione di integrazione.

Osservare i suggerimenti riportati di seguito quando si utilizzano le funzioni di memoria attiva.

Convalidare e ridurre al minimo i dati dell'applicazione: esaminare i messaggi, i metadati e gli ID inviati dall'applicazione nell'SDK. Evitare di passare più dati di quelli necessari per il flusso di lavoro della memoria.
Usa endpoint di modelli affidabili: configura LLM e incorpora endpoint che soddisfano i requisiti per la sicurezza dei trasporti, la residenza dei dati, la conservazione e il monitoraggio operativo.
Tratta la memoria generata come dati dell'applicazione e output non attendibile: memorie estratte, riepiloghi e schede contesto sono output derivati. Esamina il modo in cui l'applicazione li utilizza, soprattutto prima che influenzino le azioni privilegiate, le chiamate agli strumenti esterni o le decisioni visibili ai clienti.
Account per l'iniezione persistente dei prompt: il testo fornito, recuperato o derivato dal modello dal chiamante memorizzato nella memoria può essere riprodotto in prompt di riepilogo, estrazione, scheda di contesto o agente successivi. I delimitatori prompt, le istruzioni di escape ed estrazione possono aiutare a strutturare l'input del modello, ma non sono un limite di sicurezza. Trattare i ricordi derivati da un ciclo automatico come non attendibili fino a quando l'applicazione non li ha rivisti.
Sanitare o eseguire l'escape del testo derivato per la destinazione: prima di eseguire il rendering del contenuto derivato dal modello in HTML, Markdown, modelli, log o altre superfici di output, applicare l'escape o l'igienizzazione appropriati al contesto. Utilizzare la stessa attenzione prima di riutilizzare il testo derivato in prompt a valle, input di strumenti, comandi o altri contesti simili a interpreti.
Scegli la modalità operativa giusta: se l'applicazione ha bisogno del pieno controllo su ciò che diventa memoria permanente, prendi in considerazione l'uso di scritture di memoria esplicite, integrazioni solo per l'area di memorizzazione o extract_memories=False per flussi di lavoro che non dovrebbero eseguire l'estrazione automatica.

Considerazioni sulla persistenza e sulla minimizzazione dei dati

La memoria agente è progettata per rendere persistenti messaggi, memorie, metadati e integrazioni in Oracle AI Database quando viene utilizzata l'area di memorizzazione supportata dal DB. Ciò consente il recupero duraturo e la memoria cross-session, ma significa anche che l'applicazione dovrebbe pianificare quali dati è appropriato conservare.

Le seguenti linee guida aiutano a mantenere le distribuzioni allineate alle pratiche di gestione dei dati sicure:

Per l'uso solo in negozio, rendere persistente solo ciò che è necessario: progettare l'applicazione in modo che nell'archivio di memoria vengano scritti solo contenuti utili e appropriati per l'azienda.
Quando le funzioni di memoria attiva sono abilitate, pianificare i record derivati: oltre al contenuto fornito dal chiamante, ad esempio messaggi e metadati, un flusso di lavoro può anche rendere persistenti le memorie estratte, i riepiloghi o le integrazioni.
Definisci i criteri di conservazione ed eliminazione in anticipo: se l'applicazione offre impegni di eliminazione o conservazione, assicurati che coprano messaggi non elaborati, memorie estratte, metadati e altri record correlati creati dal flusso di lavoro.
Evitare di fare affidamento sulla memoria come fonte di verità: le memorie memorizzate hanno lo scopo di migliorare il contesto e il recupero. Le domande dovrebbero continuare a fare affidamento su sistemi autorevoli per decisioni importanti.

Considerazioni relative all'ambito di recupero e al controllo dell'accesso

La memoria agente utilizza i valori user_id, agent_id e thread_id forniti dal chiamante per il recupero dell'ambito. Questo è un potente modello di filtraggio, ma non dovrebbe essere l'unico controllo su cui si basa l'applicazione quando si decide come viene utilizzato o visualizzato il contenuto recuperato.

Per impostazione predefinita, il recupero con ambito thread utilizza la corrispondenza esatta per user_id e agent_id e una corrispondenza più ampia per thread_id in modo che i risultati pertinenti possano estendersi su thread passati per la stessa coppia utente-agente. Le chiamate OracleAgentMemory.search() e search_async() di livello superiore richiedono anche un user_id concreto e una corrispondenza esatta degli utenti. Rifiutano l'ambito utente omesso, user_id=None e exact_user_match=False in modo che l'API client pubblica non esegua ricerche accidentali tra più utenti.

Durante la progettazione del recupero, attenersi alle procedure indicate di seguito.

Eseguire il mapping delle regole dell'applicazione all'ambito di memoria: assicurarsi che gli ambiti passati dall'applicazione all'SDK corrispondano alle regole di condivisione dei dati, utente e tenant.
Passare un ambito utente esplicito in ogni ricerca client: derivare l'ID utente dal contesto della richiesta autenticata e fornirlo in ogni chiamata OracleAgentMemory.search() o search_async() di livello superiore.
Preferire l'ambito più ristretto che soddisfa il caso d'uso: utilizzare filtri di corrispondenza esatta e più rigorosi per i flussi di lavoro che gestiscono dati più riservati.
Esaminare intenzionalmente il recupero cross-thread: il recupero più ampio può migliorare la continuità tra le sessioni, ma le applicazioni dovrebbero abilitarlo solo se tale approccio è appropriato.
Tratta i risultati della ricerca come contenuto recuperato, non come decisioni finali: le memorie restituite possono essere rilevanti, ma l'applicazione rimane responsabile di decidere se e come mostrare o agire.
Gestione del testo recuperato come contenuto non attendibile al limite di integrazione: i record recuperati possono includere testo fornito dal chiamante o derivato dal modello. Convalidare, ripulire o eliminare il contenuto in modo appropriato per la destinazione prima di visualizzarlo, trasformarlo o passarlo a sistemi a valle.

Considerazioni sull'integrazione delle applicazioni e sulla fiducia dei chiamanti

La memoria agente deve essere chiamata dall'applicazione di integrazione o da altro codice backend sicuro, non direttamente dagli utenti finali. Non è un limite di sicurezza rivolto all'utente finale e non esegue l'autenticazione o l'autorizzazione dell'utente finale da solo. Il pacchetto si affida al chiamante per fornire i valori corretti per user_id, agent_id, thread_id e l'ambito di recupero per ogni operazione.

Nota: l'applicazione di integrazione è responsabile dell'autenticazione dell'utente finale, dell'autorizzazione dell'accesso e della derivazione del user_id e dell'ambito corretti prima che chiami le API di memoria dell'agente. Un valore user_id fornito dal chiamante è un valore di ambito, non una prova dell'identità.

Utilizzare le procedure riportate di seguito quando si integra l'SDK in un'applicazione identica.

Tratta ''user_id'' come input dell'applicazione sensibile alla sicurezza: ricava user_id dal contesto dell'applicazione autenticata invece di consentire agli utenti finali di scegliere valori arbitrari.
Applicare l'autorizzazione dell'applicazione prima di ogni chiamata di memoria: l'applicazione di integrazione deve decidere quali valori user_id, agent_id, thread_id e dell'ambito di ricerca sono validi per la richiesta corrente e mantenere le letture e le scritture all'interno del limite utente e tenant previsto.
Non esporre le API di memoria raw agli utenti finali: le API del package, ad esempio add_memory o le guide di ricerca, devono essere sottoposte a wrapping nella logica dell'applicazione che convalida il chiamante, applica i criteri e controlla i dati che possono essere scritti o restituiti.
Mantenere privilegiati per la ricerca automatica e l'enumerazione degli ID utente: se il pacchetto aggiunge elementi di supporto per l'elenco o l'enumerazione dei valori user_id, considerarli solo come funzionalità amministrative e non esporli mai agli utenti finali tramite l'applicazione di integrazione.
Esaminare con attenzione le sostituzioni dell'ambito: qualsiasi flusso di lavoro che amplia l'ambito del thread, disabilita la corrispondenza esatta o passa alle API dell'area di memorizzazione di livello inferiore deve essere limitato a componenti affidabili e rivisto per gli effetti cross-user o cross-tenant.

Considerazioni sull'accesso al database, sulla gestione dello schema e sui segreti

La memoria agente utilizza una connessione o un pool Oracle AI Database fornito dal chiamante. Il package non crea né gestisce le credenziali del database. Inoltre, non crea, negozia o aggiorna la crittografia di rete del database per conto del chiamante.

Nota:

Per le distribuzioni di produzione, creare la connessione o il pool Oracle AI Database con il trasporto cifrato abilitato prima di passarlo alla memoria dell'agente. Non utilizzare connessioni al database in testo non codificato in reti non attendibili, condivise o esterne. Quando si utilizza python-oracledb, seguire la sezione ufficiale Crittografia sicura del traffico di rete in Oracle AI Database e configurare TLS o un altro trasporto cifrato approvato come parte della creazione della connessione o del pool.
Non incorporare mai chiavi API, password o altri segreti direttamente nel codice applicazione, nella configurazione di cui è stato eseguito il check-in o negli artifact esportati. Utilizzare sempre meccanismi di iniezione sicuri e attenersi al principio del privilegio minimo per l'accesso alle credenziali.

Si consigliano le procedure di distribuzione riportate di seguito.

Utilizzare gli utenti del database con solo i privilegi necessari: concedere solo gli elementi necessari per il modello di distribuzione e il criterio dello schema selezionati.
Crea connessioni e pool di database cifrati: la memoria agente utilizza la connessione o il pool esattamente come fornito dal chiamante. Per python-oracledb, preferire le connessioni abilitate per TLS come protocol=\"tcps\" o un DSN TCPS equivalente, configurare il wallet o il materiale CA richiesto e mantenere abilitata la convalida del certificato server.
Mantenere il criterio dello schema predefinito a meno che non siano necessarie modifiche DDL in modo esplicito: SchemaPolicy.REQUIRE_EXISTING è l'impostazione predefinita ed evita la creazione, la modifica o l'eliminazione di oggetti dello schema durante l'avvio dell'applicazione standard.
Limitare le modalità di impostazione distruttiva: SchemaPolicy.RECREATE è destinato ai flussi di lavoro di impostazione, test o amministrazione e non deve essere utilizzato nei percorsi di produzione standard.
Affidarsi a percorsi SQL gestiti da package, non a un assembly SQL dinamico nel codice dell'applicazione: nei percorsi DB gestiti, i valori dei record e i filtri di ricerca vengono inviati con bind variable e i nomi degli oggetti gestiti derivano da prefissi convalidati.
Proteggi le credenziali di connessione e provider: memorizza il database, l'LLM e incorpora le credenziali in un gestore di segreti come OCI Vault e ruotale regolarmente.
Prefer validate TLS in modalità Sottile e Spessa: i documenti ufficiali di python-oracledb sottolineano che sia la modalità Sottile che quella Spessa supportano TLS e la modalità Spessa possono anche utilizzare la cifratura di rete nativa Oracle, dove questo è lo standard approvato.
Usa trasporto sicuro nel database: la sicurezza della rete del database, la configurazione TLS e il metodo di autenticazione sono determinati dalla connessione fornita dal chiamante e devono seguire gli standard dell'organizzazione.

Considerazioni sulla comunicazione di rete e gli endpoint esterni

La memoria agente può comunicare con i servizi esterni quando la distribuzione configura l'LLM remoto o i provider di incorporamento. L'SDK inoltra prompt e richiede parametri tramite il percorso client configurato, ma l'applicazione e la distribuzione circostanti rimangono responsabili della protezione di queste connessioni.

Si consiglia quanto segue:

Utilizzare HTTPS per gli endpoint del modello e preferire i percorsi di rete privati o limitati, se disponibili.
Monitorare il traffico in uscita e l'uso del provider per le destinazioni impreviste, il volume di richieste insolito o il consumo anomalo di token.
Scegli i provider che soddisfano le tue esigenze di compliance e residenza prima di abilitare le funzioni di memoria attiva su flussi di lavoro regolamentati o riservati.

Considerazioni sui vettori di esaurimento delle risorse

I flussi di lavoro di memoria possono aumentare l'uso del database, l'integrazione del traffico e il consumo di token LLM nel tempo. Questo è vero sia per un uso eccessivo dannoso che per errori di implementazione innocenti come messaggi sovradimensionati o modelli di recupero troppo ampi.

Utilizzare questi controlli come parte della tempra di produzione:

Impostare prompt pratici e limiti di messaggi: configurare valori quali max_message_token_length e memory_extraction_token_limit per soddisfare i limiti del carico di lavoro e del provider.
Dimensioni recupero limite: utilizzare valori max_results ragionevoli e filtri di tipo record per le ricerche dell'applicazione.
Applicare i limiti dell'infrastruttura al di fuori dell'SDK: utilizzare le quote del database, i limiti di connessione, i controlli di rete, i timeout degli endpoint e la limitazione di frequenza nella distribuzione circostante.
Monitora la crescita nel tempo: monitora il volume dei messaggi memorizzati, la crescita duratura della memoria, l'uso del provider e la latenza delle query in modo da poter apportare modifiche alla conservazione o all'ottimizzazione prima che influiscano sull'affidabilità.