安全性考量

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

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

LLM 備份記憶體處理的考量

Oracle AI Agent Memory 支援主動記憶體功能，例如產生影像描述、執行緒摘要及自動擷取記憶體。啟用這些功能時，SDK 可以將影像位元組、最近的訊息、繫線摘要、擷取的記憶體，或搜尋文字傳送至設定的 LLM 或內嵌端點。請參閱使用影像和多重模型訊息，瞭解決定何時將影像位元組傳送至已設定的 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 AI Database 中。這可允許持久的擷取和跨階段作業記憶體，但也表示應用程式應規劃適合保留的資料。

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

• 對於僅儲存用途，僅保存所需的項目：設計應用程式，以便只將有用的、適合業務的內容寫入記憶體存放區。
• 啟用 Active-memory 功能時，請規劃衍生記錄：除了呼叫程式提供的內容 (例如訊息、影像和中繼資料) 之外，工作流程也可以保存產生的影像描述、擷取的記憶體、摘要或內嵌項目。
• 將可寫入的記憶體路徑視為信任：可寫入訊息、摘要、記憶體、描述資料、內嵌項目或繫線程式實際執行狀態的資料庫證明資料和後端程式碼路徑，可能會影響未來的提示和擷取結果。主動記憶體功能會刻意保存模型衍生狀態；如果不適用於工作流程，請停用自動擷取，或使用僅儲存 / 手動寫入整合與較窄的應用程式控制項。
• 為保留工作選取正確的刪除範圍：delete_message() 只會移除原始訊息記錄。從該訊息建立的衍生記憶體或其他下游繫線作用領域使用者自建物件仍然可以搜尋，因為擷取的記憶體目前並未保存每個訊息的來源。當您需要執行緒範圍清除，同時移除相關聯的記憶體和受管理的擷取資料時，請使用 OracleAgentMemory.delete_thread()。
• 規劃背景工作的刪除和關閉界限：從屬端和繫線刪除方法等候 300 秒的時間，讓相同的 OracleAgentMemory 執行處理在等待開始之前，已經接受相關的背景記憶體擷取和影像描述產生。delete_thread()、delete_message() 和繫線層次 delete_memory() 等待其繫線；從屬端層次 delete_memory() 只會在其儲存的目標具有繫線範圍時等待；而 delete_user() 和 delete_agent() 則會等待已知擁有的繫線 (無論是否啟用連鎖清除)。逾時會產生 TimeoutError 而不執行刪除。這些等待與過時的影像描述檢查不是其他從屬端執行處理或處理作業的全域並行障礙，而且不支援刪除期間的並行寫入。在其他從屬端或處理作業更新或刪除其描述正在背景中產生的影像之前，請確定原始執行處理已傳回 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 代理程式記憶體也會顯示與 Oracle Deep Data Security 的整合。這是以資料庫資料角色、資料授予和一般使用者安全相關資訊環境為基礎的獨特安全功能。請先複查深資料安全性 API 和安全性參考，再授予原則或使用共用程式實際執行連線集區。該頁面還記錄了「統一稽核」，以及資料庫原則撤銷和 OCI IAM 群組成員變更的不同有效時間。

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

整合應用程式或其他受信任的後端程式碼 (而非由一般使用者直接呼叫) 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 AI Database 連線或集區。套裝程式不會建立或管理資料庫證明資料本身。它也不會代表呼叫程式建立、交涉或升級資料庫網路加密。

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

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

建議使用下列部署實務：

• 僅使用具備必要權限的資料庫使用者：僅授予所選部署模型和綱要原則所需的項目。
• 從應用程式存取區隔綱要管理：使用授權的資料庫使用者一次來建立或更新受管理「代理程式記憶體」綱要。只授予應用程式使用者必要的程式實際執行權限，然後將 SchemaPolicy.REQUIRE_EXISTING 和 schema_owner 設為綱要所屬使用者的應用程式連線。應用程式使用者接著可以讀取及寫入記憶體資料，而不需要接收綱要建立、升級或重新建立權限；請參閱疑難排解指南以取得必要的授權。
• 在切實可行的情況下使用個別的資料庫使用者來刪除工作流程：如果您的應用程式需要移除記錄，請偏好這些路徑的專用連線或集區，並將受管理 Oracle AI Agent Memory 表格上的 DELETE 僅授予該資料庫使用者。將主要程式實際執行連線限制為正常作業所需的非刪除權限，因此意外刪除或不想要的刪除具有較窄的群發半徑。如果呼叫程式透過沒有 DELETE 權限的連線呼叫 delete()，則 Oracle AI Database 會拒絕該敘述句。
• 建立加密的資料庫連線和集區：生產代碼應將啟用 TLS 的 Oracle AI 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 ，並偏好使用專用或受限的網路路徑 (若有的話)。
• 明確設定模型端點憑證：對於使用專用 CA 的 HTTPS OpenAI 相容端點，請透過 Llm 或 Embedder 上的 ca_file 傳送其信任的 PEM 憑證或組合。若為相互 TLS，請同時透過 cert_file 和 key_file 傳送用戶端憑證和私密金鑰，並以適當的檔案系統權限保護私密金鑰。伺服器憑證驗證會維持啟用狀態；請勿以不受信任的憑證取代受信任的 CA 材料。
• 刻意控制提供者代理主機環境設定值：提供者預設會採用 HTTPX 代理主機和 TLS 相關環境變數。必須使用特定代理主機時傳送 proxy；明確的代理主機優先於代理主機環境變數。當應用程式必須忽略這些環境設定值時，請設定 trust_env=False。明確的 proxy 在 trust_env=False 中仍然有效。
• 監督外送流量和提供者使用狀況，瞭解未預期的目的地、異常要求磁碟區或異常權杖使用狀況。
• 在受規範或敏感的工作流程上啟用主動記憶體功能之前，請選取符合規範和駐留需求的提供者。

關於資源耗盡向量的考量

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

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

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

建議的 Oracle Deep Data Security 部署

Oracle Deep Data Security (Deep Sec) 可在資料庫中強制執行代理程式記憶體列和欄限制，例如允許一般使用者只讀取和寫入包含自己 user_id 的列。UserOwnRowsDeepDataSecurityPolicy 原則也會防止一般使用者在插入後更新所有權和識別資料欄；請參閱深資料安全性以瞭解每個表格的確切權限。

若要在最完整程度上使用此安全功能，建議針對每個安全責任使用個別的資料庫使用者，讓應用程式在沒有一般使用者相關資訊環境時，無任何授權的備用。

我們建議在生產中分離下列帳戶：

• 安全性管理員：建立和管理資料角色、資料授予、應用程式識別及其與 IAM 群組的對應。此帳戶是管理設定帳戶，不用於一般「代理程式記憶體」要求。
• 受管理綱要擁有者：建立並擁有「Oracle 代理程式記憶體」表格和受管理綱要物件。此帳戶具有這些表格的擁有者權限，因此沒有一般使用者安全相關資訊環境的連線可以存取所有資料列。請勿使用它作為執行時期應用程式帳戶。限制其用於綱要設定、移轉及控制管理作業。此使用者應具有建立 JOB 的權限。
• 應用程式資料庫使用者：在程式實際執行時連線，而且只有建立資料庫階段作業和附加一般使用者安全相關資訊環境 (一般為 CREATE SESSION 和 CREATE END USER SECURITY CONTEXT) 所需的權限。請勿在受管理表格上授予此使用者一般的 SELECT、INSERT、UPDATE 或 DELETE 權限。達到此帳戶的要求若沒有有效的一般使用者相關資訊環境，便會關閉該要求，而非降回更廣泛的表格權限。

針對每個一般使用者要求，認證 OAM sdk 以外的使用者、取得一個應用程式集區連線、附加該使用者的一般使用者安全相關資訊環境，以及透過該連線執行「代理程式記憶體」作業。將連線釋出到集區之前，請先清除相關資訊環境。相關資訊環境屬於一個實體資料庫階段作業；它不能重複用於另一個使用者。Oracle Deep Sec end-user security context lifecycle documentation 說明相應的附件、取代及發行行為。

除非資料庫驅動程式設定為在每個取得的連線附加目前要求的一般使用者相關資訊環境，否則請勿將一般應用程式集區直接傳遞至「代理程式記憶體」執行處理。否則，SDK 作業可以借用沒有相關資訊環境的階段作業，或是使用錯誤的要求相關資訊環境。請改為取得並設定應用程式中的連線，然後將該相關資訊環境控制連線傳遞至要求範圍的「代理程式記憶體」元件。

讀取或寫入使用者擁有之記錄的背景或延遲工作需要相同的保護。在工作完成之前，將授權的連線及其一般使用者相關資訊環境保持有效，或安排工作者取得新連線並附加正確認證的使用者相關資訊環境。絕對不要透過綱要擁有者執行此工作，只略過遺漏的一般使用者相關資訊環境。