每个 LangSmith 部署 都包含一个基于 Postgres 的存储,用于长期记忆和跨线程数据。默认情况下,存储命名空间在所有调用者之间共享。要为每个用户提供独立的存储,需要配置自定义认证并添加一个存储授权处理器,该处理器会重写命名空间以包含已认证用户的身份。 本指南展示如何在 LangSmith Deployment 中配置这种隔离。同样的模式也适用于启用了自定义认证的自托管部署。

工作原理

存储项由一个命名空间元组(例如 ("memories", "preferences"))和一个键 组织。与线程和助手不同,存储命名空间由你的应用程序定义,因此授权的工作方式有所不同:
  1. 你的 @auth.authenticate 处理器验证调用者并为每个用户返回一个唯一的 identity。
  2. 你的 @auth.on.store 处理器要么验证命名空间以该身份开头,要么重写命名空间以在其前面添加该身份。
  3. 服务器使用经过验证或重写的命名空间进行实际的读写操作。
一个用户写入逻辑命名空间 ("memories",),在自动前缀重写后,实际上数据存储在 ("user-123", "memories")。另一个用户无法读取或覆盖该数据,因为他们的请求被限定在 ("user-456", ...)。
存储授权处理器接收一个可变的 value 字典。对 value["namespace"] 的更改会作用于操作。你不需要像处理线程那样返回元数据过滤器。

前提条件

  • 一个配置了自定义认证的 LangSmith Deployment。
  • 一个为每个终端用户返回稳定且唯一 identity 的 @auth.authenticate 处理器。

在 LangSmith Deployment 中配置认证

在 langgraph.json 中将你的部署指向你的认证模块:
auth 对象必须暴露一个 langgraph_sdk.Auth 的实例(通常命名为 auth)。

选择存储授权模式

存储隔离需要一个 @auth.on.store 处理器。两种常见模式都很好用;根据你希望用户作用域设置的位置来选择一种。 这两种模式都使用一个单一的 @auth.on.store 处理器,涵盖所有存储操作(put、get、search、delete 和 list_namespaces)。只有在需要按操作应用不同规则时,才需要像 @auth.on.store.put 这样的特定操作处理器。
如果你使用一个拒绝未处理请求的全局 @auth.on 处理器,请显式注册 @auth.on.store 以便允许存储操作。有关特定操作处理器的名称,请参阅认证参考。

显式命名空间 + 拒绝

你的应用程序代码在每个命名空间中包含用户身份作为第一段(例如 ("user-123", "memories"))。认证处理器验证调用者是否匹配该前缀,并拒绝不匹配的请求:
此模式使存储布局在你的图代码中显式化。如果认证用户是 user-123,那么对命名空间 ("user-456", "memories") 的请求会立即失败。代价是你的代理中的每个存储调用都必须包含用户前缀,通常来自运行时上下文,如 config["configurable"]["langgraph_auth_user_id"]。

自动前缀重写

你的应用程序代码使用不带用户前缀的逻辑命名空间(例如 ("memories", "preferences"))。认证处理器在每次存储操作前,会前置认证用户的身份:
当客户端调用 list_namespaces 而没有前缀时,value["namespace"] 为空。上面的处理器将空命名空间视为 (ctx.user.identity,),因此用户只能看到自己的命名空间。 此模式使代理代码更简单,因为认证层透明地处理用户隔离。代价是你不能在应用程序代码中也给命名空间加前缀,否则会导致数据双重作用域并破坏读取。选择一个作用域层:认证重写或应用程序级命名空间,而不是两者都用。

在代理代码中使用命名空间

如果你使用自动前缀重写,你的图代码使用不带用户前缀的逻辑命名空间。认证层在请求时自动添加用户作用域。将以下内容放入你的图节点或工具中(例如 graph.py):
当用户 A 调用存储 API 时,服务器将数据持久化在 ("user-a", "memories", "preferences")。用户 B 的请求永远无法触及该命名空间。 如果你使用显式命名空间 + 拒绝,则在图代码中的每个命名空间里包含用户身份:

Deep Agents 和 StoreBackend

如果你使用带 [StoreBackend](https://reference.langchain.com/python/deepagents/backends/store/StoreBackend) 的 Deep Agents,请将你的命名空间工厂与认证作用域的布局对齐。当认证前置 ctx.user.identity 时,在后端使用逻辑命名空间,让认证处理用户隔离:
或者,如果你在图内部按用户作用域进行(例如使用 rt.server_info.user.identity),请确保你的认证处理器不会重复给命名空间加前缀。选择一个作用域层:认证重写或应用程序级命名空间,而不是两者都用。 有关命名空间设计的更多信息,请参阅 Deep Agents 后端 和 用户作用域记忆。

测试存储隔离

在运行 langgraph dev 并在认证处理器中配置了两个测试用户后,验证存储数据不会在用户间泄露:

与线程隔离结合

存储隔离和线程隔离解决的是不同的问题: 对于多用户代理,两者都需要配置。有关线程和运行的作用域,请参阅使对话私有化。

另请参阅