Appearance
权限与安全边界
Deep Agents permissions 是内置 filesystem tools 的声明式路径规则。它能减少误读写，但不是通用 授权框架，更不是 sandbox。安全设计必须同时覆盖工具实现、backend、代码执行、网络、凭据和人工 审批。
版本门槛：Python permissions 需要
deepagents>=0.5.2；TypeScript 需要deepagents>=1.9.1。本文基线0.6.12与1.10.7均满足要求。
规则模型
每条规则有三个字段。TypeScript 1.10.7 的类型是：
ts
type FilesystemPermission = {
operations: ('read' | 'write')[]
paths: string[]
mode: 'allow' | 'deny'
}Python 0.6.12 还支持 mode="interrupt"：匹配的写操作会进入 HITL，而不是直接允许或拒绝；该 模式从 deepagents>=0.6.8 提供，需要 checkpointer。TypeScript 1.10.7 的 permission mode 仍只有 allow 和 deny，需要审批时使用 interruptOn。
规则按声明顺序匹配，第一条匹配规则生效。没有任何规则匹配时，默认允许。因此要建立 default-deny，必须在具体 allow 规则之后放置覆盖全路径的 deny。
前端类比
它类似路由 ACL：/public/** 先允许，最后 /** 拒绝。顺序错误会让宽泛规则提前截获请求。
Deep Agents 原生语义：FilesystemMiddleware 在执行内置文件工具前，根据 operation 和虚拟 路径选择第一条规则。它不会拦截自定义函数、MCP server 内部文件访问或 sandbox 的 shell 命令。
配置 Default-deny
python
import os
from deepagents import create_deep_agent
permissions = [
{
"operations": ["read"],
"paths": ["/knowledge/**"],
"mode": "allow",
},
{"operations": ["read"], "paths": ["/**"], "mode": "deny"},
{
"operations": ["write"],
"paths": ["/workspace/**"],
"mode": "allow",
},
{"operations": ["write"], "paths": ["/**"], "mode": "deny"},
]
agent = create_deep_agent(
model=os.environ["DEEPAGENTS_MODEL"],
permissions=permissions,
)ts
import { createDeepAgent, type FilesystemPermission } from 'deepagents'
const permissions: FilesystemPermission[] = [
{ operations: ['read'], paths: ['/knowledge/**'], mode: 'allow' },
{ operations: ['read'], paths: ['/**'], mode: 'deny' },
{ operations: ['write'], paths: ['/workspace/**'], mode: 'allow' },
{ operations: ['write'], paths: ['/**'], mode: 'deny' },
]
const model = process.env.DEEPAGENTS_MODEL
if (!model) throw new Error('DEEPAGENTS_MODEL is required')
const agent = createDeepAgent({ model, permissions })如果把 deny /** 放在对应 allow 前面，后面的 allow 永远不会命中。
Operations 覆盖哪些工具
| Operation | Python 当前内置工具 | TypeScript 当前内置工具 |
|---|---|---|
| read | ls、read_file、glob、grep | ls、read_file、glob、grep |
| write | write_file、edit_file、delete | write_file、edit_file |
工具集合会随版本和 backend 变化。升级时应重新核对官方 permissions 页，而不是只检查类型是否仍能 编译。
Python Permission Interrupt
Python 可以把特定路径的写操作直接映射到人工审批：
python
import os
from deepagents import FilesystemPermission, create_deep_agent
from langgraph.checkpoint.memory import InMemorySaver
agent = create_deep_agent(
model=os.environ["DEEPAGENTS_MODEL"],
permissions=[
FilesystemPermission(
operations=["write"],
paths=["/secrets/**"],
mode="interrupt",
)
],
checkpointer=InMemorySaver(),
)它会与 interrupt_on 合并并复用同一恢复流程。目录 delete 采用整体判断：只要目标或后代路径被 deny，就拒绝整次删除，不做部分删除。permission interrupt 仍只覆盖内置 filesystem 调用，不能替代 业务工具授权或 sandbox 隔离。
Subagent 继承
Subagent 默认继承父 Agent permissions；一旦 subagent 显式提供自己的规则，会整体替换父级 规则，而不是合并。覆盖时必须重复需要保留的 deny 规则，否则可能意外放宽访问。
适合的做法：
- Researcher 只读
/knowledge/**，拒绝所有 write。 - Writer 只写
/workspace/drafts/**，读取范围按任务限制。 - Reviewer 只读 artifact，不获得业务写工具。
Permissions 明确不覆盖什么
- 自定义 LangChain tools。
- MCP tools 在远程 server 中进行的文件或数据库访问。
- Sandbox/LocalShell 的
execute命令。 - Interpreter PTC bridge 和动态 subagent 内部调用。
- Backend 自身的网络、凭据和租户隔离。
这些能力必须在实现层各自认证和授权。
分层安全模型
| 层 | 负责什么 | 示例 |
|---|---|---|
| 身份 | 谁发起请求 | OIDC/session → trusted runtime context |
| 工具授权 | 能调用哪个业务动作 | 租户校验、资源 owner、幂等键 |
| Filesystem permissions | 内置文件工具可访问的虚拟路径 | /knowledge/** read-only |
| Backend | 路径映射和持久化隔离 | Store namespace、受控工作区 |
| Sandbox | 任意代码与宿主隔离 | 无凭据、默认断网、资源限制 |
| HITL | 对高风险普通 tool call 人工决策 | approve/edit/reject |
| 审计 | 事后追踪和告警 | thread、tool、args hash、result |
Prompt Injection 视角
模型可能从网页、文件、MCP 结果或远程 subagent 接收到恶意指令。System prompt 中的“不要泄露” 不是强制边界。即使模型被诱导，基础设施仍应保证：
- 工具拿不到无关凭据。
- Sandbox 不能访问宿主和不必要网络。
- Backend namespace 不能由模型自由选择。
- 写操作有最小资源范围和审计。
- 高风险动作需要不可绕过的应用级检查。