以编程方式使用文档

该 langchain-spicedb 包提供 LangChain 工具，使代理能够在采取行动之前检查 SpiceDB 权限。这些工具对于构建智能体 RAG 系统特别有用，在这些系统中，代理需要在检索或操作资源之前验证访问权限。

安装

pip install langchain-spicedb

设置

环境设置

# SpiceDB connection details
os.environ["SPICEDB_ENDPOINT"] = "localhost:50051"
os.environ["SPICEDB_TOKEN"] = "sometoken"

工具

SpiceDBPermissionTool

检查单个用户是否有权访问特定资源。

初始化

from langchain_spicedb import SpiceDBPermissionTool

permission_tool = SpiceDBPermissionTool(
    spicedb_endpoint="localhost:50051",
    spicedb_token="sometoken",
    resource_type="article",
    subject_type="user",
    fail_open=False,
)

参数

  • spicedb_endpoint (str): SpiceDB 服务器地址（默认值："localhost:50051"）
  • spicedb_token (str): SpiceDB 认证的预共享密钥
  • resource_type (str): SpiceDB 资源类型（例如 "document"、"article"）
  • subject_type (str): SpiceDB 主体类型（默认值："user"）
  • fail_open (bool): 如果为 True，则在错误时允许访问；如果是 False，则在错误时拒绝（默认值：False）
  • use_tls (bool): 是否使用 TLS 进行 SpiceDB 连接（默认值：False）

与代理一起使用

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_spicedb import SpiceDBPermissionTool

# Create the permission checking tool
permission_tool = SpiceDBPermissionTool(
    spicedb_endpoint="localhost:50051",
    spicedb_token="sometoken",
    resource_type="article",
)

# Create agent with the tool
llm = ChatOpenAI(model="gpt-4", temperature=0)

agent = create_agent(
    llm,
    tools=[permission_tool],
    system_prompt="""You are a security-aware assistant.
Before accessing any document, ALWAYS check if the user has permission
using the check_spicedb_permission tool."""
)

# Agent checks permissions before proceeding
result = agent.invoke({
    "messages": [{"role": "user", "content": "Can user alice view document doc1?"}]
})

print(result["messages"][-1].content)
# Output: "Yes, user alice can view document doc1" or "No, user alice cannot view document doc1"

直接工具使用

# Check if alice can view doc1
result = await permission_tool._arun(
    subject_id="alice",
    resource_id="doc1",
    permission="view"
)

print(result)  # "true" or "false"

# Check edit permission
result = await permission_tool._arun(
    subject_id="alice",
    resource_id="doc1",
    permission="edit"
)

SpiceDBBulkPermissionTool

一次性检查多个资源的权限——当代理需要在继续操作之前验证对多个文档的访问权限时非常有用。

初始化

from langchain_spicedb import SpiceDBBulkPermissionTool

bulk_tool = SpiceDBBulkPermissionTool(
    spicedb_endpoint="localhost:50051",
    spicedb_token="sometoken",
    resource_type="article",
    subject_type="user",
)

参数

同上 SpiceDBPermissionTool （见上文）。

与代理一起使用

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_spicedb import SpiceDBBulkPermissionTool

# Create the bulk permission checking tool
bulk_tool = SpiceDBBulkPermissionTool(
    spicedb_endpoint="localhost:50051",
    spicedb_token="sometoken",
    resource_type="article",
)

llm = ChatOpenAI(model="gpt-4", temperature=0)

agent = create_agent(
    llm,
    tools=[bulk_tool],
    system_prompt="You are a helpful assistant. Check permissions before accessing documents."
)

# Agent checks multiple documents at once
result = agent.invoke({
    "messages": [{"role": "user", "content": "Which of these documents can alice access: doc1, doc2, doc3?"}]
})

print(result["messages"][-1].content)
# Output: "alice can access: doc1, doc3"

直接工具使用

# Check multiple resources at once
result = await bulk_tool._arun(
    subject_id="alice",
    resource_ids="doc1,doc2,doc3",  # Comma-separated IDs
    permission="view"
)

print(result)
# Output: "alice can access: doc1, doc3" or "alice cannot access any of the requested resources"

代理如何决定调用这些工具

代理使用工具 **name** 和 **description** 来决定何时调用它们：

工具名称

  • - check_spicedb_permission - 单个权限检查
  • - check_spicedb_bulk_permissions - 批量权限检查

工具描述

两个工具都有详细描述来指导代理：

  • 何时使用在检索敏感文档或执行需要授权的操作之前使用此工具
  • 功能说明：检查用户是否有权访问资源
  • 返回值说明: "true"/"false" or list of accessible resources

影响工具使用

要提高智能体检查权限的可能性：

1. **系统提示词**：包含明确的安全指导 

   prompt = PromptTemplate.from_template(
       """You are a security-conscious assistant.
       Before accessing any document, ALWAYS check if the user has permission
       using the check_spicedb_permission tool."""
   )

2. **降低温度**：使用 temperature=0 以获得更确定性的行为 

   llm = ChatOpenAI(model="gpt-4", temperature=0)

3. **清晰化系统提示词**：提供明确的工具使用说明 

   agent = create_agent(llm, tools, system_prompt="Always check permissions before accessing documents.")

  1. **少样本示例**：在提示词中包含工具使用的示例

输入模式

SpiceDBPermissionTool

{
    "subject_id": "alice",       # User ID to check (required)
    "resource_id": "doc1",       # Resource ID - ONLY the ID portion, not "article doc1" (required)
    "permission": "view"         # Permission to check (default: "view")
}

SpiceDBBulkPermissionTool

{
    "subject_id": "alice",           # User ID to check (required)
    "resource_ids": "doc1,doc2,doc3", # Comma-separated IDs - ONLY ID portions (required)
    "permission": "view"             # Permission to check (default: "view")
}

错误处理

默认失败关闭

默认情况下，工具采用失败关闭策略 — 如果检查权限时发生错误，将拒绝访问：

tool = SpiceDBPermissionTool(
    spicedb_endpoint="localhost:50051",
    spicedb_token="sometoken",
    resource_type="article",
    fail_open=False,  # Default
)

失败开放

适用于开发或特定用例：

tool = SpiceDBPermissionTool(
    spicedb_endpoint="localhost:50051",
    spicedb_token="sometoken",
    resource_type="article",
    fail_open=True,  # Allow access on errors
)

完整示例：安全文档智能体

from dotenv import load_dotenv
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_spicedb import SpiceDBPermissionTool, SpiceDBBulkPermissionTool

# Load environment variables from .env file
load_dotenv()

# Setup
os.environ["SPICEDB_ENDPOINT"] = "localhost:50051"
os.environ["SPICEDB_TOKEN"] = "sometoken"

# Create tools
permission_tool = SpiceDBPermissionTool(
    spicedb_endpoint=os.environ["SPICEDB_ENDPOINT"],
    spicedb_token=os.environ["SPICEDB_TOKEN"],
    resource_type="article",
)

bulk_permission_tool = SpiceDBBulkPermissionTool(
    spicedb_endpoint=os.environ["SPICEDB_ENDPOINT"],
    spicedb_token=os.environ["SPICEDB_TOKEN"],
    resource_type="article",
)

# Create agent
llm = ChatOpenAI(model="gpt-4", temperature=0)

agent = create_agent(
    llm,
    tools=[permission_tool, bulk_permission_tool],
    system_prompt="""You are a security-aware document assistant.
ALWAYS verify user permissions before accessing documents using the permission tools.
Respond with whether the user has access and which documents they can view."""
)

# Run agent
result = agent.invoke({
    "messages": [{"role": "user", "content": "Can alice view documents doc1, doc2, and doc3?"}]
})

print(result["messages"][-1].content)

API 参考

SpiceDBPermissionTool

  • 名称: "check_spicedb_permission"
  • 描述：检查用户是否有权访问资源
  • 参数_模式: SpiceDBPermissionInput
  • 返回_类型: str ("true" or "false")

SpiceDBBulkPermissionTool

  • 名称: "check_spicedb_bulk_permissions"
  • 描述：检查用户是否有权访问多个资源
  • 参数_模式: SpiceDBBulkPermissionInput
  • 返回_类型: str (逗号分隔的可访问资源列表或拒绝消息)

相关组件