安全性考量

範圍：本文件涵蓋與 Oracle AI Agent Memory Python SDK 相關的安全考量。它僅適用於使用 SDK 的主動記憶體功能或儲存層的應用程式。

重要性：Oracle AI Agent Memory 可以將繫線內容與記憶體記錄保留在 Oracle Database 中，並在啟用 LLM 備份功能時，將內容傳送至設定的模型端點以進行彙總、記憶體擷取或內嵌。因此，安全部署取決於對應用程式資料、擷取範圍、資料庫存取、外部模型端點和保留原則的謹慎處理。

LLM 備份記憶體處理的考量

Oracle AI Agent Memory 支援主動記憶體功能，例如執行緒彙總與自動擷取記憶體。啟用這些功能時，SDK 可能會將最新的訊息、繫線摘要、擷取的記憶體，或搜尋文字傳送至設定的 LLM 或內嵌端點。

重要事項：請只將內容傳送至適用於已設定模型端點和部署原則的 Oracle AI Agent Memory。如果對似乎包含加密密碼、證明資料或不必要的機密資料的資料啟用 active-memory，則在訊息進入記憶體管線之前，請將該內容最小化或隱匿。將擷取的記憶體、摘要、相關資訊環境卡和其他模型衍生文字視為不受信任的輸出，必須由整合應用程式安全複查及處理。

警告：模型衍生文字可能會變成永久記憶體狀態。啟用自動擷取、摘要或相關資訊環境卡功能時，SDK 可以將摘要、擷取的記憶體或擷取的記錄插入後續提示中，例如記憶體擷取、摘要、相關資訊環境卡或代理程式提示，然後應用程式才能複查特定的中間值。將此視為一般不受信任的 LLM 資料流程：複查並驗證應用程式使用的輸出，且不要讓記憶體衍生的內容授權授權授權授權動作或略過原則。

使用主動記憶體功能時，請遵循下列建議：

• 驗證應用程式資料並將其降到最低：複查應用程式傳送到 SDK 的訊息、描述資料以及 ID。避免傳遞比記憶體工作流程需求更多的資料。
• 使用受信任的模型端點：設定符合傳輸安全性、資料駐留、保留及作業監控需求的 LLM 和內嵌端點。
• 將產生的記憶體視為應用程式資料和不受信任的輸出：擷取的記憶體、摘要和相關資訊環境卡是衍生的輸出。特別是在應用程式影響授權動作、外部工具呼叫或客戶可見決策之前，複查應用程式的使用方式。
• 只有在可接受延遲衍生的寫入時，才選擇非同步擷取：在背景模式中，原始訊息寫入可以在寫入衍生的記憶體、摘要或相關程式實際執行狀態之前完成。如果工作流程在模型衍生狀態變為持久之前需要複查或更嚴格的確認界限，請使用內嵌擷取或停用該工作流程的自動擷取。
• 永久提示插入的帳戶：儲存在記憶體中的呼叫程式提供、擷取或模型衍生文字，可重新執行至後續摘要、擷取、相關資訊環境卡或代理程式提示中。提示分隔符號、遁離和擷取指示可協助建構模型輸入，但它們不是安全界限。請先複查擷取的記憶體、摘要、相關資訊環境卡和其他保存或提示輸入中間文字，再依賴這些文字。如果您的工作流程需要複查才能讓模型衍生的文字影響未來的擷取或內容建構，請停用自動擷取，並使用明確的記憶體寫入或其他由應用程式控制的複查閘道。
• 為其目標執行或遁離衍生文字：如果擷取的記憶體、摘要、相關資訊環境卡或其他模型衍生文字呈現為 HTML、Markdown、樣板、日誌或其他輸出曲面，則套用相關資訊環境適當的遁離或清除。在重複使用下游提示、工具輸入、命令或其他類似解譯器之相關資訊環境中的衍生文字之前，請務必謹慎。
• 選擇正確的操作模式：如果您的應用程式需要在模型衍生文字之前複查，可能會影響之後的擷取或內容建構，請考慮對不應執行自動擷取的工作流程使用明確的記憶體寫入、僅儲存整合或 memory_extraction_config=MemoryExtractionConfig(extract_memories=False)。

持續性與資料最小化的考量

Oracle AI Agent Memory 的設計是在使用資料庫備份存放區時，將訊息、記憶體、描述資料及內嵌項目保留在 Oracle Database 中。這可允許持久的擷取和跨階段作業記憶體，但也表示應用程式應規劃適合保留的資料。

下列指引有助於確保部署符合安全的資料處理實務：

• 對於僅儲存用途，僅保存所需的項目：設計應用程式，以便只將有用的、適合業務的內容寫入記憶體存放區。
• 啟用 Active-memory 功能時，請規劃衍生記錄：除了呼叫程式提供的內容 (例如訊息和描述資料) 之外，工作流程也可以保存擷取的記憶體、摘要或內嵌項目。
• 將可寫入的記憶體路徑視為信任：可寫入訊息、摘要、記憶體、描述資料、內嵌項目或繫線程式實際執行狀態的資料庫證明資料和後端程式碼路徑，可能會影響未來的提示和擷取結果。主動記憶體功能會刻意保存模型衍生狀態；如果不適用於工作流程，請停用自動擷取，或使用僅儲存 / 手動寫入整合與較窄的應用程式控制項。
• 為保留工作選擇正確的刪除範圍：delete_message() 只會移除原始訊息記錄。從該訊息建立的衍生記憶體或其他下游繫線作用領域使用者自建物件仍然可以搜尋，因為擷取的記憶體目前並未保存每個訊息的來源。當您需要執行緒範圍清除，同時移除相關聯的記憶體和受管理的擷取資料時，請使用 OracleAgentMemory.delete_thread()。
• 規劃背景工作的刪除和關閉界限：delete_thread()、delete_user(cascade=True) 和 delete_agent(cascade=True) 僅等待等待等待等待開始時該從屬端已知的先前接受背景擷取。它們不是其他控制碼、元件或程序的全域並行屏障，且不支援刪除期間進行並行寫入。當保留或關閉界限需要從目前從屬端擷取已接受的背景以先完成時，請先呼叫 wait_for_memory_extraction()，再進行處理作業關閉或相關的管理作業。
• 事先定義保留和刪除原則：如果您的應用程式提供刪除或保留確認，請確定它們涵蓋原始訊息、擷取的記憶體、描述資料，以及工作流程所建立的其他相關記錄。根據每筆記錄中預期的資訊類型、應用程式需要保留的原因，以及任何適用的保留承諾，選擇每筆記錄的 ttl_days 值和綱要 memory_retention_config。使用自動到期時，若記錄應依時效永久清除，並確認受管理 Oracle 永久清除工作是否存在於資料庫備份的部署中，特別是當綱要設定使用者沒有排程器工作權限時。
• 永久清除工作資料庫載入計畫：受管理 Oracle 永久清除工作會在排程上執行，並從 SDK 管理的表格中以批次方式刪除過期的資料列，而不是以大型刪除方式刪除。監控具有高寫入速率或大型到期批次之環境中的程式實際執行、重做 / 還原產生、略過執行歷史記錄及資料列磁碟區，以及調整保留設定值或作業推出計畫 (如果永久清除活動可能與延遲敏感的資料庫工作負載重疊)。受管理工作會設定一天 schedule_limit，因此可以略過執行延遲太長的時間，而不是任意延遲啟動。
• 避免將記憶體作為事實來源：預存記憶體旨在改善內容和擷取。應用程式應繼續仰賴授權系統做出重要決策。

擷取範圍和存取控制的考量

Oracle AI Agent Memory 使用呼叫程式提供的 user_id、agent_id 和 thread_id 值來擷取範圍。這是一個強大的篩選模型，但當決定如何使用或顯示擷取的內容時，不應該是應用程式唯一依賴的控制項。

依照預設，繫線範圍擷取會使用 user_id 和 agent_id 的完全相符項目，以及 thread_id 的更廣泛相符項目，因此相關結果可以跨相同使用者代理程式組的過去繫線。最上層 OracleAgentMemory.search() 和 search_async() 呼叫也需要明確的使用者範圍設定，以及完全符合的使用者。它們會拒絕省略的使用者範圍和 exact_user_match=False，因此公用從屬端 API 不會意外搜尋多個使用者。只允許在完全相符的使用者和目標只有未作用領域記錄時傳送 user_id=None。

設計擷取時，請運用下列課堂練習：

• 將應用程式規則對應至記憶體範圍：確定您的應用程式傳送至 SDK 的範圍符合您的租用戶、使用者及資料共用規則。
• 傳送每個從屬端搜尋的明確使用者範圍：從已認證的要求相關資訊環境衍生 user_id，而不是從要求 JSON 或其他呼叫者控制的輸入衍生，並在每個最上層 OracleAgentMemory.search() 或 search_async() 呼叫提供。user_id=None 僅適用於非作用領域記錄的故意限制工作流程。
• 偏好符合使用案例的最窄範圍：針對處理更機密資料的工作流程，使用完全相符且更嚴格的篩選條件。
• 刻意複查跨繫線擷取：中介擷取可改善階段作業的連續性，但應用程式應該只在適當的行為時才啟用。
• 將搜尋結果視為擷取的內容，而不是最終決定：傳回的記憶可能與之相關，但應用程式仍需負責決定是否顯示或採取動作。
• 安全地在整合界限處理擷取的文字：擷取的記錄可包含來電者提供或模型衍生的文字。如果擷取的記憶體或其他傳回的文字是轉譯成 HTML、Markdown、樣板、日誌或其他輸出曲面，請先套用相關資訊環境適當的遁離或清除，然後再顯示、轉換或傳送到下游系統。

應用程式整合與呼叫者信任的考量

整合應用程式或其他受信任的後端程式碼 (而非一般使用者直接呼叫) Oracle AI Agent Memory。它不是一般使用者方面的安全界限，而且不會自行執行一般使用者認證或授權。套裝軟體信任呼叫程式為每個作業提供正確的 user_id、agent_id、thread_id 以及擷取範圍。

重要事項：整合應用程式負責驗證一般使用者、授權存取，以及在呼叫 Oracle AI Agent Memory API 之前衍生正確的 user_id 和範圍。呼叫者提供的 user_id 為範圍值，而非識別證明。

將 SDK 整合至代理應用程式時，請使用下列實務：

• 將 user_id 視為安全敏感的應用程式輸入：如果整合應用程式從要求 JSON 或其他呼叫者控制的輸入衍生 user_id，而非經過認證的相關資訊環境，則允許跨使用者記憶體存取。從已認證的應用程式相關資訊環境衍生 user_id，而不是讓一般使用者選擇任意值。
• 在每次記憶體呼叫前套用應用程式授權：整合應用程式必須決定對目前要求有效的 user_id、agent_id、thread_id 以及搜尋範圍值，並將讀取和寫入保留在預期的用戶和使用者界限內。
• 不向一般使用者公開原始記憶體 API ：套裝程式 API (例如 add_memory 或搜尋協助程式) 應包裝在可驗證呼叫程式、強制實行原則及控制可寫入或傳回之資料的應用程式邏輯中。
• 具備使用者 ID 尋找和列舉權限：如果套裝程式新增用於列出或列舉 user_id 值的協助程式，請只將它們視為管理功能，而且絕不會透過整合應用程式向一般使用者顯示這些功能。
• 仔細複查範圍覆寫：任何延伸繫線範圍、停用完全相符或捨棄至較低層次存放區 API 的工作流程，都應該限制為信任的元件，並針對跨使用者或跨租用戶的效果進行複查。

記錄與診斷的考量

Oracle AI Agent Memory 使用標準的 Python 記錄日誌，而且不會設定整合應用程式的應用程式日誌處理程式或日誌層次。應用程式可以啟用 oracleagentmemory 日誌記錄器，並透過現有的日誌記錄組態遞送 SDK 日誌。

使用 SDK 日誌時，請使用下列課堂練習：

• 將生產部署保留在非 DEBUG 層級：DEBUG 記錄僅供受控制的開發或支援診斷使用，不適合用於收集生產日誌。
• 限制存取診斷日誌：使用適當的存取控制、保留和共用原則，將日誌儲存在受保護的接收器中。請先複查支援組合，再將日誌傳送至作業環境之外。
• 避免在應用程式記錄日誌包裝程式中新增機密相關資訊環境：請勿使用提示、記憶體內容、證明資料、原始描述資料、資料庫資料列值或呼叫程式控制的 ID 來強化 SDK 日誌記錄。
• 將日誌文字視為診斷輸出，而不是稽核介面：日誌訊息可協助疑難排解 SDK 行為，但應用程式應該使用自己的明確稽核事件來進行安全性和規範工作流程。

資料庫存取、綱要管理以及加密密碼的考量

Oracle AI Agent Memory 使用由呼叫者提供的 Oracle Database 連線或集區。套裝程式不會建立或管理資料庫證明資料本身。它也不會代表呼叫程式建立、交涉或升級資料庫網路加密。

重要事項：生產代碼應將已啟用 TLS 的 Oracle Database 連線或集區傳送至 Oracle AI Agent Memory。SDK 會依現狀使用呼叫程式提供的連線或集區，且不會升級純文字 DSN。請勿在不受信任、共用或外部網路之間使用純文字資料庫連線。使用 python-oracledb 時，請依照 Securely Encrypting Network Traffic to Oracle Database 官方小節進行設定，並在建立連線或集區時設定 TLS 或其他核准的加密傳輸。

重要事項：請勿將 API 金鑰、密碼或其他加密密碼直接內嵌至應用程式程式碼、存入組態或匯出的使用者自建物件中。請一律使用安全注入機制，並遵循最低權限原則以進行證明資料存取。

建議使用下列部署實務：

• 僅使用具備必要權限的資料庫使用者：僅授予所選部署模型和綱要原則所需的項目。
• 在切實可行的情況下使用個別的資料庫使用者來刪除工作流程：如果您的應用程式需要移除記錄，請偏好這些路徑的專用連線或集區，並將受管理 Oracle AI 代理程式記憶體表格上的 DELETE 授予該資料庫使用者。將主要程式實際執行連線限制為正常作業所需的非刪除權限，因此意外刪除或不想要的刪除具有較窄的群發半徑。如果呼叫程式透過沒有 DELETE 權限的連線呼叫 delete()，則 Oracle Database 會拒絕敘述句。
• 建立加密的資料庫連線和集區：生產代碼應將啟用 TLS 的 Oracle Database 連線或集區傳送至 SDK。Oracle AI Agent Memory 會完全使用由呼叫者提供的連線或集區，因此對於 python-oracledb，偏好啟用 TLS 的連線 (例如 protocol="tcps" 或同等的 TCPS DSN)、設定必要的公事包或 CA 資料，以及啟用伺服器憑證驗證。
• 除非您明確需要變更 DDL，否則保留預設綱要原則：預設為 SchemaPolicy.REQUIRE_EXISTING，避免在一般應用程式啟動期間建立、修改或刪除綱要物件。
• 限制破壞性設定模式：SchemaPolicy.RECREATE 適用於設定、測試或管理工作流程，不應用於一般生產路徑。
• 依賴套裝程式管理的 SQL 路徑，而非應用程式程式碼中的動態 SQL 組件：在受管理資料庫路徑中，會使用連結變數傳送記錄值和搜尋篩選，受管理物件名稱則衍生自驗證的前置碼。
• 保護連線和提供者證明資料：將資料庫、LLM 儲存並在加密密碼管理程式 (例如 OCI 保存庫) 中內嵌證明資料，然後定期輪換這些證明資料。
• 在 Thin 和 Thick 模式中偏好經過驗證的 TLS ：官方 python-oracledb 文件注意，Thin 和 Thick 模式都支援 TLS，而 Thick 模式也可以使用 Oracle Native Network Encryption，這是您的核准標準。
• 使用安全傳輸至資料庫：資料庫網路安全、TLS 組態及認證方法是由呼叫程式提供的連線所決定，且應符合您組織的標準。

網路通訊和外部端點的考量

部署設定遠端 LLM 或內嵌提供者時，Oracle AI Agent Memory 可以與外部服務通訊。SDK 會透過設定的從屬端路徑轉寄提示和要求參數，但周圍的應用程式和部署仍需負責保護這些連線。

我們建議您：

• 在模型端點使用 HTTPS ，並偏好使用專用或受限的網路路徑 (若有的話)。
• 監督外送流量和提供者使用狀況，瞭解未預期的目的地、異常要求磁碟區或異常權杖使用狀況。
• 在受規範或敏感的工作流程上啟用主動記憶體功能之前，請選擇符合法規遵循和駐留需求的提供者。

關於資源耗盡向量的考量

記憶體工作流程可以隨著時間增加資料庫使用量、嵌入流量和 LLM 權杖使用量。這既適用於惡意過度使用，也適用於無辜的實作錯誤，例如過大訊息或過度廣泛的擷取模式。

使用這些控制項作為生產強化的一部分：

• 設定實際提示和訊息界限：設定 max_message_token_length 和 memory_extraction_token_limit 等值以符合您的工作負載和提供者限制。max_message_token_length 會限制擷取工作流程所使用的提示時間複本；儲存的訊息則維持不變。
• 連結擷取大小：使用合理的 max_results 值和記錄類型篩選進行應用程式搜尋。
• 在 SDK 外部套用基礎架構限制：在周圍部署中使用資料庫配額、連線限制、網路控制、端點逾時和速率限制。
• 監控一段時間的成長：追蹤儲存的訊息量、持久的記憶體成長、提供者使用狀況和查詢延遲，以便在變更影響可靠性之前進行保留或調整。