[!info] related notes

• 所属 MOC: Agent Runtime MOC
• 相关: [[sandbox|Sandbox]], Guardrails, Tool Permission Check

Permission Boundary

一句话定义

Permission Boundary 是定义 Agent 可以做什么、不可以做什么的权限范围。不是所有 Agent 都需要相同的权限——客服 Agent 不需要删除数据的权限，代码 Agent 不需要访问用户数据的权限。

核心原理

权限维度

维度	例子
工具白名单	只能用 search、query，不能用 delete
参数限制	query 工具只能查自己的数据
操作范围	只能读，不能写
资源限制	最多 10 步，最多 1000 token
数据范围	只能访问 tenant_1 的数据

Python 实现

@dataclass
class PermissionBoundary:
    allowed_tools: list[str]       # 允许的工具列表
    denied_tools: list[str]        # 禁止的工具列表
    max_steps: int = 10            # 最大步数
    max_tokens: int = 10000        # 最大 token
    read_only: bool = False        # 是否只读
    data_scope: dict = None        # 数据范围（如 tenant_id）

    def can_use_tool(self, tool_name: str) -> bool:
        if self.denied_tools and tool_name in self.denied_tools:
            return False
        if self.allowed_tools and tool_name not in self.allowed_tools:
            return False
        return True

    def check_step_limit(self, current_steps: int) -> bool:
        return current_steps < self.max_steps

在 Agent Runtime 中应用

class BoundedAgentRuntime:
    def __init__(self, boundary: PermissionBoundary):
        self.boundary = boundary

    async def execute_tool(self, tool_call, context):
        # 检查工具权限
        if not self.boundary.can_use_tool(tool_call.name):
            return ToolResult(error=f"Tool {tool_call.name} not allowed")

        # 注入数据范围
        if self.boundary.data_scope:
            tool_call.arguments.update(self.boundary.data_scope)

        # 只读检查
        if self.boundary.read_only:
            tool = registry.get(tool_call.name)
            if not tool.read_only:
                return ToolResult(error="Read-only mode")

        return await tool_runtime.execute(tool_call, context)

常见设计模式

1. 角色化权限

BOUNDARIES = {
    "customer_service": PermissionBoundary(
        allowed_tools=["search_knowledge", "query_order", "create_ticket"],
        denied_tools=["delete_record", "execute_code"],
        max_steps=5,
    ),
    "code_agent": PermissionBoundary(
        allowed_tools=["read_file", "write_file", "execute_code", "search_web"],
        max_steps=20,
    ),
    "data_analyst": PermissionBoundary(
        allowed_tools=["query_database", "create_chart"],
        read_only=True,
        data_scope={"tenant_id": "current"},
    ),
}

2. 动态权限

根据用户角色和上下文动态调整权限。

常见坑

1. 权限太宽: Agent 有删除数据的权限但不需要
2. 权限太窄: Agent 需要的工具被禁止
3. 不做数据隔离: Agent A 能访问 Agent B 的数据
4. 权限配置散落: 每个工具各自检查权限，没有统一管理

参考资料

• Guardrails in Agents
• Least Privilege