[!info] related notes

• 所属 MOC: Agent Runtime MOC
• 相关: Sandbox, Guardrails, Tool Permission Check

Permission Boundary

一句话定义

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

核心原理

权限维度

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

Python 实现

from dataclasses import dataclass, field

@dataclass(frozen=True)
class PermissionBoundary:
    allowed_tools: frozenset[str]
    denied_tools: frozenset[str] = field(default_factory=frozenset)
    max_steps: int = 10
    max_tokens: int = 10000
    read_only: bool = False
    tenant_id: str | None = None

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

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

在 Agent Runtime 中应用（协议示意）

从可信认证上下文解析 actor 和 tenant，不接受模型自报的身份
从服务端工具注册表查找工具，未知工具拒绝
检查 allowed_tools / denied_tools / read_only
验证参数 schema，解析目标资源并检查租户和资源权限
原子预留本次执行预算，避免并发请求同时通过同一个剩余额度
在受约束的执行器中调用工具；数据层再次应用授权范围

常见设计模式

1. 角色化权限

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

示例角色集合不是固定默认权限；tenant_id 必须由认证上下文提供。上面的类只做名称白名单和步数比较，max_tokens、read_only、租户隔离尚需执行层实现。空白名单表示无工具可用；向 arguments 塞 tenant_id 不能证明 SQL 或远程服务真正限定了数据范围。

2. 动态权限

根据用户角色、任务授权和服务端策略取交集；模型输出不能自行扩大权限。执行前重新检查可能变化的授权，路径还需考虑规范化、符号链接和间接调用。

常见坑

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

参考资料

• Guardrails in Agents
• Least Privilege