安全性考量

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

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

LLM 備份記憶體處理的考量

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

注意：請只將內容傳送至適用於已設定模型端點和部署原則的「代理程式記憶體」。在內容進入記憶體管線之前進行驗證並將其最小化，並避免在訊息或記憶體中包含加密密碼、證明資料或不必要的機密資料。將擷取的記憶體、摘要、相關資訊環境卡和其他模型衍生文字視為不受信任的輸出，必須由整合應用程式安全複查及處理。

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

• 驗證應用程式資料並將其降到最低：複查應用程式傳送到 SDK 的訊息、描述資料以及 ID。避免傳遞比記憶體工作流程需求更多的資料。

• 使用受信任的模型端點：設定符合傳輸安全性、資料駐留、保留及作業監控需求的 LLM 和內嵌端點。

• 將產生的記憶體視為應用程式資料和不受信任的輸出：擷取的記憶體、摘要和相關資訊環境卡是衍生的輸出。特別是在應用程式影響授權動作、外部工具呼叫或客戶可見決策之前，複查應用程式的使用方式。

• 永久提示插入的帳戶：儲存在記憶體中的呼叫程式提供、擷取或模型衍生文字，可重新執行至後續摘要、擷取、相關資訊環境卡或代理程式提示中。提示分隔符號、遁離和擷取指示可協助建構模型輸入，但它們不是安全界限。將來自自動週期的衍生記憶視為不受信任，直到應用程式複查它們為止。

• 對目的地執行或遁離衍生文字：在 HTML、Markdown、樣板、日誌或其他輸出曲面呈現模型衍生內容之前，先套用相關資訊環境適當的遁離或清除。在重複使用下游提示、工具輸入、命令或其他類似解譯器之相關資訊環境中的衍生文字之前，請務必謹慎。

• 選擇正確的操作模式：如果您的應用程式需要完全控制何種持久性記憶體，請考慮對不應執行自動擷取的工作流程使用明確的記憶體寫入、僅儲存整合或 extract_memories=False。

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

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

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

• 對於僅儲存用途，僅保存所需的項目：設計應用程式，以便只將有用的、適合業務的內容寫入記憶體存放區。

• 啟用 Active-memory 功能時，請規劃衍生記錄：除了呼叫程式提供的內容 (例如訊息和描述資料) 之外，工作流程也可以保存擷取的記憶體、摘要或內嵌項目。

• 事先定義保留和刪除原則：如果您的應用程式提供刪除或保留確認，請確定它們涵蓋原始訊息、擷取的記憶體、描述資料，以及工作流程所建立的其他相關記錄。

• 避免將記憶體作為事實來源：預存記憶體旨在改善內容和擷取。應用程式應繼續仰賴授權系統做出重要決策。

關於擷取範圍與存取控制的考量

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

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

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

• 將應用程式規則對應至記憶體範圍：確定您的應用程式傳送至 SDK 的範圍符合您的租用戶、使用者及資料共用規則。

• 在每個從屬端搜尋上傳送明確的使用者範圍：從已認證的要求相關資訊環境衍生 user_id，並在每個最上層 OracleAgentMemory.search() 或 search_async() 呼叫上提供。

• 偏好符合使用案例的最窄範圍：針對處理更機密資料的工作流程，使用完全相符且更嚴格的篩選條件。

• 刻意複查跨繫線擷取：Broader 擷取可改善階段作業的連續性，但應用程式應該只在該方法適當時才啟用。

• 將搜尋結果視為擷取的內容，而不是最終決定：傳回的記憶可能與之相關，但應用程式仍需負責決定是否顯示或採取動作。

• 將擷取的文字當作整合界限中不受信任的內容處理：擷取的記錄可以包含來電者提供或模型衍生的文字。在顯示內容、轉換內容或傳遞至下游系統之前，先驗證、清理或遁離目的地適用的內容。

關於應用程式整合與來電者信任的考量

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

注意：整合應用程式負責認證一般使用者、授權存取，以及在呼叫「代理程式記憶體 API」之前衍生正確的 user_id 和範圍。呼叫者提供的 user_id 為範圍值，而非識別證明。

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

• 將 ''user_id'' 視為安全敏感應用程式輸入：從已認證的應用程式相關資訊環境衍生 user_id，而不是讓一般使用者選擇任意值。

• 在每次記憶體呼叫前套用應用程式授權：整合應用程式必須決定對目前要求有效的 user_id、agent_id、thread_id 以及搜尋範圍值，並將讀取和寫入保留在預期的用戶和使用者界限內。

• 不向一般使用者公開原始記憶體 API ：套裝程式 API (例如 add_memory 或搜尋協助程式) 應包裝在可驗證呼叫程式、強制實行原則及控制可寫入或傳回之資料的應用程式邏輯中。

• 具備使用者 ID 尋找和列舉權限：如果套裝程式新增用於列出或列舉 user_id 值的協助程式，請只將它們視為管理功能，而且絕對不會透過整合應用程式向一般使用者顯示這些功能。

• 仔細複查範圍覆寫：任何延伸繫線範圍、停用完全相符或捨棄至較低層次存放區 API 的工作流程，都應限制為信任的元件，並針對跨使用者或跨租用戶的效果進行複查。

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

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

注意：

• 對於生產環境部署，請先建立已啟用加密傳輸的 Oracle AI Database 連線或集區，再將其傳送至「代理程式記憶體」。請勿在不受信任、共用或外部網路之間使用純文字資料庫連線。使用 python-oracledb 時，請依照官方區段 Securely Encrypting Network Traffic to Oracle AI Database，並在建立連線或集區時設定 TLS 或其他核准的加密傳輸。

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

建議使用下列部署實務：

• 僅使用具備必要權限的資料庫使用者：僅授予所選部署模型和綱要原則所需的項目。

• 建立加密的資料庫連線和集區：「代理程式記憶體」會使用呼叫程式所提供的連線或集區。對於 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 或內嵌提供者時，代理程式記憶體可與外部服務通訊。SDK 會透過設定的從屬端路徑轉寄提示和要求參數，但周圍的應用程式和部署仍需負責保護這些連線。

我們建議您：

• 在模型端點使用 HTTPS ，並偏好使用專用或受限的網路路徑 (若有的話)。

• 監督外送流量和提供者使用狀況，瞭解未預期的目的地、異常的要求磁碟區或異常權杖使用狀況。

• 在受規範或敏感的工作流程上啟用主動記憶體功能之前，請選擇符合法規遵循和駐留需求的提供者。

關於資源耗盡向量的考量

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

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

• 設定實際提示和訊息界限：設定 max_message_token_length 和 memory_extraction_token_limit 等值以符合您的工作負載和提供者限制。

• 連結擷取大小：使用合理的 max_results 值和記錄類型篩選進行應用程式搜尋。

• 在 SDK 外部套用基礎架構限制：在周圍部署中使用資料庫配額、連線限制、網路控制、端點逾時和速率限制。

• 監控一段時間的成長：追蹤儲存的訊息量、持久的記憶體成長、提供者使用狀況和查詢延遲，以便在變更影響可靠性之前進行保留或調整。