セキュリティーに関する考慮事項

スコープ: この記事では、エージェント・メモリーPython SDKに関連するセキュリティ上の考慮事項について説明します。これは、SDKのアクティブ・メモリー機能またはストア・レイヤーのいずれかを使用するアプリケーションにのみ適用されます。

重要な理由: エージェント・メモリーは、Oracle AI Databaseでスレッド・コンテンツおよびメモリー・レコードを保持でき、LLMにバックアップされた機能が有効になっている場合は、サマリー、メモリー抽出または埋込み用に構成済のモデル・エンドポイントにコンテンツを送信します。したがって、セキュアなデプロイメントは、アプリケーション・データの慎重な処理、取得範囲、データベース・アクセス、外部モデル・エンドポイントおよび保存ポリシーに依存します。

LLMバックアップ・メモリー処理に関する考慮事項

エージェント・メモリーは、スレッド要約や自動メモリー抽出などのアクティブメモリー機能をサポートしています。これらの機能を有効にすると、SDKは、構成済のLLMまたは埋込みエンドポイントに、最近のメッセージ、スレッド・サマリー、取得済メモリーまたは検索テキストを送信できます。

ノート:構成済モデル・エンドポイントおよびデプロイメント・ポリシーに適したコンテンツのみをエージェント・メモリーに送信します。シークレット、資格証明または不要な機密データが含まれるように見えるデータに対してアクティブ・メモリーが有効になっている場合は、メッセージがメモリー・パイプラインに入る前にそのコンテンツを最小化またはリダクションします。抽出された記憶、要約、コンテキスト・カードおよびその他のモデル派生テキストを信頼できない出力として処理します。この出力は、統合アプリケーションによって安全にレビューおよび処理する必要があります。

警告:モデル派生テキストが永続メモリー状態になる可能性があります。自動抽出、要約またはコンテキスト・カード機能が有効になっている場合、アプリケーションがその特定の中間値をレビューする前に、SDKによってサマリー、抽出されたメモリーまたは取得されたレコードが、メモリー抽出、要約、コンテキスト・カードまたはエージェント・プロンプトなどの後のプロンプトに挿入される可能性があります。これを通常の信頼できないLLMデータ・フローとして扱います。アプリケーションが消費する出力を確認して検証し、メモリー由来のコンテンツが特権アクションまたはバイパス・ポリシーを認可しないようにします。

アクティブ・メモリー機能を使用する場合は、次の推奨事項に従います。

• アプリケーション・データの検証および最小化: アプリケーションがSDKに送信するメッセージ、メタデータおよびIDを確認します。メモリー・ワークフローが必要とするより多くのデータを渡さないでください。

• 信頼できるモデル・エンドポイントの使用: LLMを構成し、トランスポート・セキュリティ、データ・レジデンシ、保持および運用モニタリングの要件を満たすエンドポイントを埋め込みます。

• 生成されたメモリーをアプリケーション・データおよび信頼できない出力として処理: 抽出されたメモリー、サマリーおよびコンテキスト・カードは導出された出力です。特権アクション、外部ツール・コールまたは顧客に見える決定に影響を与える前に、アプリケーションがそれらを使用する方法を確認します。

• 永続的プロンプト・インジェクションのアカウント: メモリーに格納されたコール元提供、取得またはモデル派生テキストは、後で要約、抽出、コンテキスト・カードまたはエージェント・プロンプトにリプレイできます。プロンプト・デリミタ、エスケープおよび抽出命令は、モデル入力の構成に役立ちますが、セキュリティ境界ではありません。抽出された記憶、要約、コンテキスト・カード、およびその他の永続的またはプロンプトバウンドの中間テキストを確認してから、それらに依存します。モデル派生テキストが将来の抽出またはコンテキスト構成に影響を与える前にワークフローでレビューが必要な場合は、自動抽出を無効にし、明示的なメモリー書込みまたは別のアプリケーション制御レビュー・ゲートを使用します。

• 宛先の派生テキストをサニタイズまたはエスケープ: 抽出されたメモリー、サマリー、コンテキスト・カードまたはその他のモデル派生テキストがHTML、Markdown、テンプレート、ログまたはその他の出力サーフェスにレンダリングされる場合は、コンテキストに適したエスケープまたはサニタイズを適用します。派生テキストをダウンストリーム・プロンプト、ツール入力、コマンドまたはその他のインタプリタのようなコンテキストで再利用する前に、同じ注意を払ってください。

• 適切なオペレーティング・モードの選択: モデル派生テキストが後で抽出またはコンテキスト構成に影響を与える前にアプリケーションを確認する必要がある場合は、自動抽出を実行しないワークフローに明示的なメモリー書込み、ストア専用統合またはextract_memories=Falseを使用することを検討してください。

永続性およびデータの最小化に関する考慮事項

エージェント・メモリーは、DBバック・ストアが使用されたときに、メッセージ、メモリー、メタデータおよび埋込みをOracle AI Databaseに永続化するように設計されています。これにより、恒久的な取得およびクロスセッション・メモリーが可能になりますが、保持に適したデータをアプリケーションが計画する必要があることも意味します。

次のガイダンスは、セキュアなデータ処理プラクティスに従ってデプロイメントを維持するのに役立ちます。

• ストアのみの使用の場合、必要なもののみを保持: 役立つビジネスに適したコンテンツのみがメモリー・ストアに書き込まれるようにアプリケーションを設計します。

• アクティブ・メモリー機能が有効になっている場合、導出されたレコードの計画: メッセージやメタデータなどのコール元提供のコンテンツに加えて、抽出されたメモリー、サマリーまたは埋込みもワークフローによって保持される場合があります。

• 信頼できるものとして書込み可能なメモリー・パスを処理: メッセージ、サマリー、メモリー、メタデータ、埋込みまたはスレッド・ランタイム状態を記述できるデータベース資格証明およびバックエンド・コード・パスは、今後のプロンプトおよび取得結果に影響する可能性があります。アクティブ・メモリー機能は意図的にモデル派生状態を維持します。ワークフローに適さない場合は、自動抽出を無効にするか、より狭いアプリケーション・コントロールとのストア専用/手動書込み統合を使用します。

• 保存作業の正しい削除スコープの選択: delete_message()は、RAWメッセージ・レコードのみを削除します。導出されたメモリーまたはそのメッセージから作成されたその他のダウンストリーム・スレッド・スコープのアーティファクトは、抽出されたメモリーがメッセージごとの来歴を現在保持していないため、検索可能なままにできます。関連付けられたメモリーおよび管理対象ベクトル/チャンク・データも削除するスレッド・スコープのクリーンアップが必要な場合は、OracleAgentMemory.delete_thread()を使用します。

• 保持および削除ポリシーを事前に定義: アプリケーションで削除または保持のコミットメントが提供されている場合は、ワークフローによって作成されたRAWメッセージ、抽出されたメモリー、メタデータおよびその他の関連レコードをカバーしていることを確認してください。

• 記憶を信頼できる情報源として利用しない: 格納された記憶は、コンテキストと検索を改善することを目的としています。アプリケーションは、重要な決定のために信頼できるシステムに依存し続ける必要があります。

取得範囲およびアクセス制御に関する考慮事項

エージェント・メモリーでは、コール元提供のuser_id、agent_idおよびthread_id値を使用して、取得の範囲を指定します。これは強力なフィルタリング・モデルですが、取得したコンテンツの使用方法または表示方法を決定する際にアプリケーションが依存する唯一の制御ではありません。

デフォルトでは、スレッド・スコープ取得では、user_idとagent_idの完全一致とthread_idのより広い一致が使用されるため、関連する結果は、同じユーザー・エージェント・ペアの過去のスレッドにまたがることができます。最上位のOracleAgentMemory.search()およびsearch_async()コールでは、明示的なユーザー・スコープ指定と正確なユーザー一致も必要です。パブリック・クライアントAPIが誤って複数のユーザーを検索しないように、省略されたユーザー・スコープおよびexact_user_match=Falseを拒否します。user_id=Noneの受渡しは、ユーザー完全一致でのみ許可され、スコープなしレコードのみをターゲットとします。

取得を設計する際には、次の演習を使用します。

• アプリケーション・ルールをメモリー・スコープにマップ: アプリケーションがSDKに渡すスコープが、テナント、ユーザーおよびデータ共有ルールと一致していることを確認します。

• すべてのクライアント検索で明示的なユーザー・スコープを渡す: リクエストJSONまたはその他のコール元制御入力からではなく、認証されたリクエスト・コンテキストからuser_idを導出し、各トップレベルのOracleAgentMemory.search()またはsearch_async()コールで指定します。user_id=Noneは、スコープなしレコードに意図的に制限されたワークフローに対してのみ使用します。

• ユース・ケースを満たす最も狭いスコープの優先: より機密性の高いデータを処理するワークフローには、完全一致フィルタと厳密なフィルタを使用します。

• クロススレッド取得を意図的に確認する: より広範な取得により、セッション間の継続性が向上しますが、アプリケーションでは、そのアプローチが適切な場合にのみ有効にする必要があります。

• 検索結果を最終決定ではなく、取得したコンテンツとして処理: 返された記憶は関連性がある可能性がありますが、アプリケーションはそれらを表示または処理するかどうか、およびその方法を決定する責任を負います。

• 取得したテキストを統合境界で安全に処理: 取得したレコードには、コール元提供のテキストまたはモデル派生テキストを含めることができます。取得したメモリーまたはその他の返されたテキストがHTML、Markdown、テンプレート、ログまたはその他の出力サーフェスにレンダリングされる場合、コンテキストに適したエスケープまたはサニタイズを適用してから、それを表示、変換、ロギング、またはダウンストリーム・システムに渡します。

アプリケーション統合と発信者信頼に関する考慮事項

エージェント・メモリーは、エンド・ユーザーによって直接ではなく、統合アプリケーションまたは他の信頼できるバックエンド・コードによってコールされます。ロー・メモリーAPIは、エンド・ユーザー向けのセキュリティ境界ではなく、エンド・ユーザー認証または認可を単独で実行しません。パッケージは、コール元を信頼して、各操作に対して正しいuser_id、agent_id、thread_idおよび取得スコープを提供します。

ノート:統合アプリケーションは、エージェント・メモリーAPIをコールする前に、エンド・ユーザーの認証、アクセスの認可、および正しいuser_idとスコープの導出を行います。コール元が提供するuser_idは、アイデンティティの証明ではなく、範囲指定値です。

SDKをエージェント・アプリケーションに統合する場合は、次の演習を使用します。

• セキュリティに依存するアプリケーション入力としてuser_idを処理: 統合アプリケーションが、認証されたコンテキストではなく、リクエストJSONまたはその他のコール元制御入力からuser_idを導出する場合、クロスユーザー・メモリー・アクセスを許可できます。エンド・ユーザーが任意の値を選択できるようにするのではなく、認証済アプリケーション・コンテキストからuser_idを導出します。

• すべてのメモリー・コールの前にアプリケーション認可を適用: 統合アプリケーションは、現在のリクエストに対して有効なuser_id、agent_id、thread_idおよび検索スコープ値を決定し、意図したテナントおよびユーザー境界内で読取りおよび書込みを保持する必要があります。

• RAWメモリーAPIをエンド・ユーザーに公開しない: add_memoryや検索ヘルパーなどのパッケージAPIは、コール元を検証し、ポリシーを適用し、書込みまたは返すことができるデータを制御するアプリケーション・ロジックにラップする必要があります。

• ユーザーID検出および列挙権限を保持: パッケージがuser_id値のリストまたは列挙のためのヘルパーを追加する場合は、管理機能としてのみ処理し、統合アプリケーションを介してエンド・ユーザーに公開することはありません。

• スコープのオーバーライドの慎重な確認: スレッド・スコープを広げ、完全一致を無効化したり、下位レベルのストアAPIにドロップするワークフローは、信頼できるコンポーネントに制限され、クロスユーザー効果またはクロステナント効果についてレビューする必要があります。

ロギングおよび診断に関する考慮事項

Agent Memoryは、標準のPythonロギングを使用し、統合アプリケーションのアプリケーション・ログ・ハンドラまたはログ・レベルを構成しません。統合アプリケーションでSDKのDEBUGロギングを有効にすると、デバッグ・ログにトラブルシューティングの詳細が追加される場合があります。本番デプロイメントを非DEBUGレベルに維持します。DEBUGロギングは、制御された開発またはサポート診断のみを目的としており、本番ログの収集には適していません。

データベース・アクセス、スキーマ管理およびシークレットに関する考慮事項

エージェント・メモリーは、コール元提供のOracle AI Database接続またはプールを使用します。パッケージは、データベース資格証明自体を作成または管理しません。また、コール元にかわってデータベース・ネットワーク暗号化を作成、ネゴシエートまたはアップグレードしません。

ノート:

• 本番デプロイメントの場合は、エージェント・メモリーに渡す前に、暗号化されたトランスポートを有効にしてOracle AI Database接続またはプールを作成します。信頼できないネットワーク、共有ネットワークまたは外部ネットワーク間でプレーン・テキストのデータベース接続を使用しないでください。python-oracledbを使用する場合は、公式のOracle AI Databaseへのネットワーク・トラフィックの安全な暗号化の項に従って、接続またはプールの作成の一部としてTLSまたは別の承認済暗号化トランスポートを構成します。

• APIキー、パスワードまたはその他のシークレットをアプリケーション・コード、チェックイン構成またはエクスポートされたアーティファクトに直接埋め込むことはありません。セキュア・インジェクション・メカニズムを常に使用し、資格証明アクセスの最小権限の原則に従います。

次のデプロイメント・プラクティスをお薦めします。

• 必要な権限のみを持つデータベース・ユーザーの使用: 選択したデプロイメント・モデルおよびスキーマ・ポリシーに必要なもののみを付与します。

• 実際の場合、削除ワークフローに別のデータベース・ユーザーを使用します: アプリケーションでレコードを削除する必要がある場合は、それらのパスの専用の接続またはプールを優先し、管理対象エージェント・メモリー表のDELETEをそのデータベース・ユーザーにのみ付与します。通常の操作に必要な削除以外の権限に限定されたメイン・ランタイム接続を保持して、偶発的または不要な削除のブラスト半径が狭くなるようにします。DELETE権限のない接続を介してコール元がdelete()を呼び出すと、Oracle AI Databaseはその文を拒否します。

• 暗号化されたデータベース接続およびプールの作成: 本番コードは、TLS対応のOracle AI Database接続またはプールをSDKに渡す必要があります。エージェント・メモリーは、コール元が指定したとおりに接続またはプールを使用します。python-oracledbの場合、protocol="tcps"や同等のTCPS DSNなどのTLS対応接続を優先し、必要なウォレットまたはCA資料を構成し、サーバー証明書検証を有効のままにします。

• DDL変更を明示的に必要でないかぎり、デフォルトのスキーマ・ポリシーを保持します: SchemaPolicy.REQUIRE_EXISTINGがデフォルトであり、標準アプリケーションの起動時にスキーマ・オブジェクトの作成、変更または削除が回避されます。

• 破壊的設定モードの制限: SchemaPolicy.RECREATEは、設定、テストまたは管理ワークフローを目的としており、標準の本番パスでは使用しないでください。

• アプリケーション・コード内の動的SQLアセンブリではなく、パッケージ管理SQLパスに依存: 管理対象DBパスでは、レコード値および検索フィルタがバインド変数とともに送信され、管理対象オブジェクト名は検証済接頭辞から導出されます。

• 接続およびプロバイダの資格証明の保護: データベース、LLMを格納し、OCI Vaultなどのシークレット・マネージャに資格証明を埋め込み、定期的にローテーションします。

• 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_message_token_lengthは、抽出ワークフローで使用されるプロンプト時コピーを制限します。格納されたメッセージは変更されません。

• バインドされた取得サイズ: アプリケーション検索に適切なmax_results値およびレコード・タイプ・フィルタを使用します。

• SDK外部へのインフラストラクチャ制限の適用: データベース割当て、接続制限、ネットワーク制御、エンドポイント・タイムアウトおよび周囲のデプロイメントでのレート制限を使用します。

• 時間の経過に伴う増加の監視: 格納されたメッセージ量、永続メモリーの増加、プロバイダの使用量および問合せレイテンシを追跡して、信頼性に影響が及ぶ前に保持またはチューニングの変更を行えるようにします。