安全注意事项

范围：本文介绍了与代理内存 Python SDK 相关的安全注意事项。它适用于使用 SDK 的活动内存功能或仅使用存储层的应用程序。

重要性：代理内存可以在 Oracle AI Database 中保留线程内容和内存记录，并且在启用 LLM 支持的功能时，将内容发送到配置的模型端点以进行汇总、内存提取或嵌入。因此，安全部署取决于对应用数据、检索范围、数据库访问、外部模型端点和保留策略的仔细处理。

关于 LLM 备份内存处理的注意事项

代理内存支持主动内存功能，例如线程汇总和自动内存提取。启用这些功能后，SDK 可能会向配置的 LLM 或嵌入端点发送最近的消息、线程摘要、检索的内存或搜索文本。

注：仅将适合已配置模型端点和部署策略的内容发送到代理内存。在内容进入内存管道之前验证和最小化内容，并避免在消息或内存中包括密钥、凭证或不必要的敏感数据。将提取的记忆、摘要、上下文卡和其他模型推导的文本视为不可信的输出，必须通过集成应用程序安全地进行审查和处理。

使用活动内存功能时，请遵循以下建议：

• 验证和最小化应用数据：查看应用向 SDK 发送的消息、元数据和 ID。避免传递比内存工作流所需的更多数据。

• 使用可信模型端点：配置 LLM 并嵌入满足传输安全、数据驻留、保留和操作监视要求的端点。

• 将生成的内存作为应用程序数据和不可信输出进行处理：提取的内存、摘要和上下文卡是派生的输出。查看应用如何使用它们，尤其是在它们影响特权操作、外部工具调用或客户可见决策之前。

• 持久提示注入帐户：内存中存储的呼叫者提供的、检索的或模型推导的文本可以重放到以后的汇总、提取、上下文卡或代理提示中。提示分隔符、转义和提取指令可以帮助构建模型输入，但它们不是安全边界。将来自自动循环的派生记忆视为不可信，直到您的应用程序审查了它们。

• 对其目标进行清理或转义派生文本：在 HTML、Markdown、模板、日志或其他输出表面中呈现模型派生内容之前，应用与上下文相关的转义或清理。在下游提示、工具输入、命令或其他类似解释器的上下文中重复使用派生文本之前，请使用相同的注意事项。

• 选择正确的操作模式：如果您的应用需要对持久内存的内容进行完全控制，请考虑对不应执行自动提取的工作流使用显式内存写入、仅存储集成或 extract_memories=False。

关于持久性和数据最小化的注意事项

代理内存用于在使用数据库支持的存储时在 Oracle AI Database 中持久保存消息、内存、元数据和嵌入。这允许持久的检索和跨会话内存，但也意味着应用程序应该计划哪些数据适合保留。

以下指南可帮助部署与安全的数据处理实践保持一致：

• 对于仅存储使用，仅保留所需内容：设计应用程序，以便仅将有用的、适合业务的内容写入内存存储。

• 启用活动内存功能后，规划派生记录：除了调用方提供的内容（例如消息和元数据）外，工作流还可能保留提取的内存、摘要或嵌入。

• 提前定义保留和删除策略：如果您的应用提供了删除或保留承诺，请确保这些承诺涵盖由工作流创建的原始消息、提取的内存、元数据和其他相关记录。

• 避免将内存作为事实来源：存储的内存旨在改善上下文和检索。应用程序应继续依赖权威系统作出重要决定。

关于检索范围和访问控制的注意事项

代理内存使用调用方提供的 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() 调用上提供该 user_id。

• 首选满足该用例的最窄范围：对处理更敏感数据的工作流使用精确匹配和更严格的筛选器。

• 有意查看跨线程检索：更广泛的检索可以提高会话的连续性，但应用程序应仅在适当的情况下启用该方法。

• 将搜索结果视为检索的内容，而不是最终决策：返回的记忆可能相关，但应用程序仍有责任决定它们是应该显示还是应该执行。

• 将检索到的文本处理为集成边界上的不可信内容：检索到的记录可以包括调用方提供的或模型派生的文本。在显示、转换或将内容传递到下游系统之前，根据目标需要验证、消毒或转义该内容。

关于应用程序集成和调用方信任的注意事项

代理内存由集成应用程序或其他可信后端代码调用，而不是由最终用户直接调用。它不是面向最终用户的安全边界，它不会自行执行最终用户验证或授权。软件包信任调用方为每个操作提供正确的 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 或搜索助手）封装在应用程序逻辑中，以验证调用方、强制执行策略并控制可以写入或返回哪些数据。

• 保留 user-ID 搜索和枚举特权：如果软件包添加了用于列出或枚举 user_id 值的帮助器，则仅将其视为管理功能，并且从不通过集成应用程序向最终用户公开这些功能。

• 仔细审查范围覆盖：任何扩展线程范围、禁用精确匹配或丢弃到较低级别存储 API 的工作流都应限制为可信组件，并审查是否具有跨用户或跨租户效果。

关于数据库访问、方案管理和密钥的注意事项

代理内存使用调用方提供的 Oracle AI Database 连接或池。该程序包不会自行创建或管理数据库身份证明。它也不会代表调用方创建、协商或升级数据库网络加密。

注:

• 对于生产部署，请先创建启用了加密传输的 Oracle AI Database 连接或池，然后再将其传递到代理内存中。不要跨不可信、共享或外部网络使用纯文本数据库连接。When using python-oracledb, follow the official section Securely Encrypting Network Traffic to Oracle AI Database and configure TLS or another approved encrypted transport as part of connection or pool creation.

• 切勿将 API 密钥、密码或其他密钥直接嵌入到应用程序代码、签入配置或导出的构件中。始终使用安全注入机制，并遵循最少权限原则进行身份证明访问。

建议采用以下部署实践：

• 仅使用具有所需权限的数据库用户：仅授予所选部署模型和方案策略所需的权限。

• 创建加密的数据库连接和池：代理内存完全按照调用方提供的方式使用连接或池。对于 python-oracledb，首选启用了 TLS 的连接（例如 protocol=\"tcps\" 或等效的 TCPS DSN），配置所需的 wallet 或 CA 材料，并保持服务器证书验证处于启用状态。

• 除非明确需要 DDL 更改，否则保留默认方案策略：SchemaPolicy.REQUIRE_EXISTING 是默认值，可避免在标准应用程序启动期间创建、修改或删除方案对象。

• 限制破坏性设置模式：SchemaPolicy.RECREATE 用于设置、测试或管理工作流，不应在标准生产路径中使用。

• 依赖于程序包管理的 SQL 路径，而不是应用程序代码中的动态 SQL 组合件：在托管数据库路径中，使用绑定变量发送记录值和搜索筛选器，托管对象名称由验证的前缀派生。

• 保护连接和提供程序身份证明：在 OCI Vault 等密钥管理器中存储数据库、LLM 和嵌入身份证明，并定期轮换。

• 在 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 之外的基础设施限制：在周边部署中使用数据库配额、连接限制、网络控制、端点超时和速率限制。

• 监视随时间推移的增长情况：跟踪存储的消息量、持久内存增长、提供商使用情况和查询延迟，以便在影响可靠性之前进行保留或优化更改。