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. Se la memoria attiva è abilitata per i dati che sembrano includere segreti, credenziali o dati riservati non necessari, ridurre o proteggere tale contenuto prima che i messaggi entrino nella pipeline di memoria. 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.

Avvertenza: il testo derivato dal modello può diventare stato di memoria persistente. Quando le funzioni di estrazione, riepilogo o scheda di contesto automatiche sono abilitate, un record di riepilogo, di memoria estratta o recuperata può essere inserito dall'SDK in prompt successivi, ad esempio prompt di estrazione della memoria, riepilogo, scheda di contesto o agente, prima che l'applicazione possa esaminare tale valore intermedio specifico. Considera questo come un normale flusso di dati LLM non attendibile: rivedi e convalida gli output consumati dall'applicazione e non lasciare che i contenuti derivati dalla memoria autorizzino azioni privilegiate o ignorino i criteri.

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. Rivedi le memorie estratte, i riepiloghi, le schede di contesto e altri testi intermedi persistenti o vincolati al prompt prima di fare affidamento su di esse. Se il flusso di lavoro richiede una revisione prima che il testo derivato dal modello possa influenzare l'estrazione futura o la costruzione del contesto, disabilitare l'estrazione automatica e utilizzare scritture di memoria esplicite o un altro controllo di revisione controllato dall'applicazione.
Sanificare o eseguire l'escape del testo derivato per la destinazione: se le memorie estratte, i riepiloghi, le schede di contesto o altro testo derivato dal modello vengono visualizzati in HTML, Markdown, modelli, log o altre superfici di output, applicare l'escape o la sanificazione appropriate 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.
Scegliere la modalità operativa corretta: se l'applicazione deve essere esaminata prima che il testo derivato dal modello possa influenzare l'estrazione o la costruzione del contesto successiva, prendere in considerazione l'utilizzo di scritture di memoria esplicite, integrazioni solo per il negozio 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.
Tratta i percorsi di memoria con capacità di scrittura come sicuri: le credenziali del database e i percorsi di codice backend in grado di scrivere messaggi, riepiloghi, memorie, metadati, incorporamenti o stato di runtime dei thread possono influire sui prompt futuri e sui risultati del recupero. Le funzioni Active-memory persistono intenzionalmente nello stato derivato dal modello; se non è appropriato per un flusso di lavoro, disabilitare l'estrazione automatica o utilizzare un'integrazione store-only/manual-write con controlli applicativi più ristretti.
Scegliere l'ambito di eliminazione corretto per il lavoro di conservazione: delete_message() rimuove solo il record del messaggio raw. Le memorie derivate o altri artefatti con ambito thread a valle creati da quel messaggio possono rimanere ricercabili perché le memorie estratte attualmente non persistono per provenienza messaggio. Quando è necessaria una pulizia con ambito thread che rimuove anche le memorie associate e i dati vettoriali/chunk gestiti, utilizzare OracleAgentMemory.delete_thread().
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. Anche le chiamate OracleAgentMemory.search() e search_async() di livello superiore richiedono un ambito utente esplicito e una corrispondenza utente esatta. Rifiutano l'ambito utente omesso e exact_user_match=False in modo che l'API client pubblica non esegua ricerche accidentali tra più utenti. Il passaggio di user_id=None è consentito solo con la corrispondenza utente esatta e interessa solo i record con ambito non definito.

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.
Supera un ambito utente esplicito in ogni ricerca client: ricava il file user_id dal contesto della richiesta autenticata anziché dal file JSON della richiesta o da un altro input controllato dal chiamante e lo fornisce in ogni chiamata OracleAgentMemory.search() o search_async() di livello superiore. Utilizzare user_id=None solo per i flussi di lavoro intenzionalmente limitati a record con ambito non definito.
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 sicura del testo recuperato nel limite di integrazione: i record recuperati possono includere testo fornito dal chiamante o derivato dal modello. Se le memorie recuperate o altro testo restituito vengono visualizzati in HTML, Markdown, modelli, log o altre superfici di output, applicare escape o sanificazione appropriate al contesto prima di visualizzarlo, trasformarlo, registrarlo 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. Le API di memoria raw non sono un limite di sicurezza rivolto all'utente finale e non eseguono l'autenticazione o l'autorizzazione dell'utente finale da sole. Il pacchetto si affida al chiamante per fornire l'ambito corretto user_id, agent_id, thread_id e 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: se l'applicazione di integrazione deriva user_id dalla richiesta JSON o da un altro input controllato dal chiamante anziché dal contesto autenticato, ciò può consentire l'accesso alla memoria tra utenti. Derivare user_id dal contesto dell'applicazione autenticata anziché 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 relative a log e diagnostica

La memoria agente utilizza il log Python standard e non configura i gestori di log dell'applicazione o i livelli di log per l'applicazione di integrazione. Se l'applicazione di integrazione abilita la registrazione DEBUG per l'SDK, i log di debug potrebbero includere ulteriori dettagli sulla risoluzione dei problemi. Mantenere le distribuzioni di produzione a un livello non DEBUG; il log DEBUG è destinato solo alla diagnostica di sviluppo o supporto controllata e non è adatto alla raccolta dei log di produzione.

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 Cifratura 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.
Utilizzare un utente di database separato per i flussi di lavoro di eliminazione, ove pratico: se l'applicazione deve rimuovere i record, preferire una connessione o un pool dedicato per tali percorsi e concedere DELETE nelle tabelle di memoria agente gestite solo a tale utente di database. Mantenere la connessione runtime principale limitata ai privilegi non di eliminazione richiesti per le sue normali operazioni in modo che le eliminazioni accidentali o indesiderate abbiano un raggio di esplosione più stretto. Se un chiamante richiama delete() tramite una connessione che non dispone dell'autorizzazione DELETE, Oracle AI Database rifiuta l'istruzione.
Crea connessioni e pool di database cifrati: il codice di produzione deve passare una connessione o un pool Oracle AI Database abilitato per TLS nell'SDK. 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 limiti pratici di prompt e messaggi: configurare valori quali max_message_token_length e memory_extraction_token_limit per soddisfare i limiti del carico di lavoro e del provider. max_message_token_length limita la copia del tempo di prompt utilizzata dai flussi di lavoro di estrazione; i messaggi memorizzati rimangono invariati.
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à.