工作原理
存储项由一个命名空间元组(例如("memories", "preferences"))和一个键 组织。与线程和助手不同,存储命名空间由你的应用程序定义,因此授权的工作方式有所不同:
- 你的
@auth.authenticate处理器验证调用者并为每个用户返回一个唯一的identity。 - 你的
@auth.on.store处理器要么验证命名空间以该身份开头,要么重写命名空间以在其前面添加该身份。 - 服务器使用经过验证或重写的命名空间进行实际的读写操作。
("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 这样的特定操作处理器。
显式命名空间 + 拒绝
你的应用程序代码在每个命名空间中包含用户身份作为第一段(例如("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):
("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 并在认证处理器中配置了两个测试用户后,验证存储数据不会在用户间泄露:
与线程隔离结合
存储隔离和线程隔离解决的是不同的问题:
对于多用户代理,两者都需要配置。有关线程和运行的作用域,请参阅使对话私有化。
另请参阅
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

