Considerazioni sulla sicurezza

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

Perché è importante: la memoria dell'agente Oracle AI può rendere persistenti i record di contenuto e memoria dei thread in Oracle 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

La memoria dell'agente Oracle AI 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.

Importante: invia solo contenuto alla memoria dell'agente Oracle AI 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.
• Scegliere l'estrazione asincrona solo quando le scritture derivate ritardate sono accettabili: in modalità in background, le scritture dei messaggi raw possono essere completate prima che vengano scritti i ricordi derivati, i riepiloghi o lo stato di runtime correlato. Se un flusso di lavoro richiede una revisione o un limite di commit più stretto prima che lo stato derivato dal modello diventi durevole, utilizzare l'estrazione in linea o disabilitare l'estrazione automatica per tale flusso di lavoro.
• 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 memory_extraction_config=MemoryExtractionConfig(extract_memories=False) per flussi di lavoro che non dovrebbero eseguire l'estrazione automatica.

Considerazioni relative alla persistenza e alla minimizzazione dei dati

La memoria dell'agente Oracle AI è progettata per rendere persistenti messaggi, memorie, metadati e integrazioni in Oracle 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 è necessario eseguire il cleanup con ambito thread che rimuove anche le memorie associate e i dati di recupero gestiti, utilizzare OracleAgentMemory.delete_thread().
• Pianificare il limite di eliminazione e chiusura per il lavoro in background: delete_thread(), delete_user(cascade=True) e delete_agent(cascade=True) attendono solo l'estrazione in background accettata in precedenza già nota a tale client all'avvio dell'attesa. Non costituiscono una barriera di concorrenza globale tra altri handle, componenti o processi e le scritture concorrenti durante l'eliminazione non sono supportate. Quando un limite di conservazione o di arresto richiede prima l'estrazione in background già accettata dal client corrente, chiamare wait_for_memory_extraction() prima dell'arresto del processo o delle operazioni amministrative correlate.
• 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. Scegliere i valori ttl_days per record e lo schema memory_retention_config in base al tipo di informazioni previsto in ciascun record, al motivo per cui l'applicazione deve conservarlo e agli eventuali impegni di conservazione applicabili. Utilizzare la scadenza automatica quando i record devono essere rimossi in base allo scadenzario e verificare che il job di rimozione Oracle gestito sia presente nelle distribuzioni supportate dal database, soprattutto quando l'utente di impostazione dello schema non dispone dei privilegi scheduler-job.
• Piano per il caricamento del database dei processi di rimozione: il job di rimozione gestito da Oracle viene eseguito in base a una pianificazione ed elimina le righe scadute dalle tabelle gestite da SDK in batch anziché come un'unica eliminazione di grandi dimensioni. Monitora il runtime, la generazione di redo/undo, la cronologia di esecuzione saltata e il volume di righe in ambienti con tassi di scrittura elevati o batch di scadenza di grandi dimensioni e regola le impostazioni di conservazione o i piani di rollout operativi se l'attività di rimozione potrebbe sovrapporsi ai carichi di lavoro del database sensibili alla latenza. Il job gestito imposta un valore schedule_limit di un giorno in modo che le esecuzioni ritardate troppo lunghe possano essere saltate invece di iniziare arbitrariamente in ritardo.
• 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 del recupero e al controllo dell'accesso

Oracle AI Agent Memory 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.
• Passa 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.
• Rivedere intenzionalmente il recupero cross-thread: il recupero più ampio può migliorare la continuità tra le sessioni, ma le applicazioni dovrebbero abilitarlo solo se tale comportamento è 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 o passarlo ai sistemi a valle.

Considerazioni sull'integrazione delle applicazioni e sulla fiducia dei chiamanti

La memoria dell'agente Oracle AI 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.

Importante: 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 Oracle AI. 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 sulla registrazione e la diagnostica

La memoria dell'agente Oracle AI utilizza il log Python standard e non configura i gestori di log dell'applicazione o i livelli di log per l'applicazione di integrazione. Le applicazioni possono abilitare il logger oracleagentmemory e instradare i log SDK tramite la configurazione di log esistente.

Quando si utilizzano i log SDK, attenersi alle procedure riportate di seguito.

• Mantenere le distribuzioni di produzione a un livello non DEBUG: il log DEBUG è destinato solo alla diagnostica di sviluppo controllato o di supporto e non è adatto per la raccolta dei log di produzione.
• Limita l'accesso ai log di diagnostica: memorizza i log in sink protetti con criteri appropriati di controllo dell'accesso, conservazione e condivisione. Prima di inviare i log all'esterno dell'ambiente operativo, esaminare i bundle di supporto.
• Evitare l'aggiunta di un contesto riservato nei wrapper di log dell'applicazione: non arricchire i record di log SDK con prompt, contenuti di memoria, credenziali, metadati raw, valori di riga del database o identificativi controllati dal chiamante.
• Tratta il testo del log come output di diagnostica, non come interfaccia di audit: i messaggi di log possono aiutare a risolvere i problemi relativi al funzionamento dell'SDK, ma le applicazioni devono utilizzare i propri eventi di audit espliciti per i flussi di lavoro di sicurezza e conformità.

Considerazioni sull'accesso al database, sulla gestione degli schemi e sui segreti

La memoria dell'agente Oracle AI utilizza una connessione o un pool Oracle 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.

Importante: il codice di produzione deve passare una connessione o un pool Oracle Database abilitato per TLS nella memoria dell'agente Oracle AI. L'SDK utilizza la connessione fornita dal chiamante o il pool così com'è e non aggiorna un DSN in testo normale. 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 Database e configurare TLS o un altro trasporto cifrato approvato come parte della creazione della connessione o del pool.

Importante: non incorporare mai chiavi API, password o altri segreti direttamente nel codice dell'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 gestite dell'agente Oracle AI 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 Database rifiuta l'istruzione.
• Crea connessioni e pool di database cifrati: il codice di produzione deve passare una connessione o un pool Oracle Database abilitato per TLS nell'SDK. La memoria dell'agente Oracle AI utilizza la connessione o il pool fornito dal chiamante esattamente come specificato, quindi 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 del 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 degli oggetti dello schema durante il normale avvio dell'applicazione.
• Limitazione delle modalità di impostazione distruttiva: SchemaPolicy.RECREATE è destinato ai flussi di lavoro di impostazione, test o amministrazione e non deve essere utilizzato nei normali percorsi di produzione.
• 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 sugli endpoint esterni

La memoria dell'agente Oracle AI può comunicare con i servizi esterni quando la distribuzione configura l'LLM remoto o i provider di integrazione. 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 richiesta 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à.