권한

권한 (Permissions)

Deep Agents를 위한 선언적 권한 규칙으로 파일시스템 접근을 제어하세요.

선언적 권한 규칙을 사용해 에이전트가 읽거나 쓸 수 있는 파일과 디렉터리를 제어하세요. permissions=에 규칙 목록을 전달하면 에이전트의 내장 파일시스템 도구가 이를 존중합니다.

권한은 내장 파일시스템 도구(ls, read_file, glob, grep, write_file, edit_file)에만 적용됩니다. 파일시스템에 접근하는 커스텀 도구와 MCP 도구는 포함되지 않습니다. 또한 권한은 execute 도구를 통한 임의 명령 실행을 지원하는 샌드박스 백엔드에는 적용되지 않습니다.

출처: 문서

본문

기본 사용법 (Basic usage)

createDeepAgent에 FilesystemPermission 규칙 목록을 전달하세요. 규칙은 선언된 순서대로 평가됩니다. 첫 번째로 일치하는 규칙이 우선합니다. 일치하는 규칙이 없으면 연산이 허용됩니다.

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("basic: agent not created");

규칙 구조 (Rule structure)

각 FilesystemPermission에는 세 가지 필드가 있습니다:

규칙은 first-match-wins 평가를 사용합니다: operations와 paths가 현재 호출과 일치하는 첫 번째 규칙이 결과를 결정합니다. 일치하는 규칙이 없으면 호출은 허용됩니다 (허용 기본값).

경로는 절대 경로여야 하며(/로 시작) ..나 ~를 포함할 수 없습니다. 유효하지 않은 경로는 에이전트 생성 시 throw합니다.

예시 (Examples)

워크스페이스 디렉터리로 격리

/workspace/ 아래에서만 읽기와 쓰기를 허용하고 나머지는 모두 거부:

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("isolate-workspace: agent not created");

특정 파일 보호

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/.env", "/workspace/examples/**"],
      mode: "deny",
    },
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("protect-files: agent not created");

읽기 전용 메모리

에이전트가 메모리 파일을 읽을 수 있게 하되 수정은 막으세요. 조직 전체 정책이나 애플리케이션 코드로만 업데이트해야 하는 공유 지식 베이스에 유용합니다. 추가 컨텍스트는 읽기 전용 vs 쓰기 가능 메모리를 참고하세요.

const store = new InMemoryStore();
const agent = createDeepAgent({
  model,
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: (rt) => [rt.serverInfo.user.identity],
    }),
    "/policies/": new StoreBackend({
      namespace: (rt) => [rt.context.orgId],
    }),
  }),
  permissions: [
    {
      operations: ["write"],
      paths: ["/memories/**", "/policies/**"],
      mode: "deny",
    },
  ],
  store,
});
if (!agent) throw new Error("read-only-memory: agent not created");

모든 접근 거부

모든 읽기와 쓰기를 차단. 그 위에 더 구체적인 허용 규칙을 쌓을 수 있는 제한적 기준선입니다:

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("deny-all: agent not created");

규칙 순서 (Rule ordering)

first-match-wins 때문에 규칙 순서가 중요합니다. 더 구체적인 규칙을 더 넓은 규칙 앞에 두세요:

const correctPermissions: FilesystemPermission[] = [
  { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
  {
    operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

const incorrectPermissions: FilesystemPermission[] = [
  {
    operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  {
    operations: ["read", "write"],
    paths: ["/workspace/.env"],
    mode: "deny",
  },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

서브에이전트 권한 (Subagent permissions)

서브에이전트는 기본적으로 부모 에이전트의 권한을 상속합니다. 서브에이전트에게 다른 권한을 주려면 스펙에 permissions 필드를 설정하세요. 이는 부모의 규칙을 완전히 대체합니다.

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ],
  subagents: [
    {
      name: "auditor",
      description: "Read-only code reviewer",
      systemPrompt: "Review the code for issues.",
      permissions: [
        { operations: ["write"], paths: ["/**"], mode: "deny" },
        { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
        { operations: ["read"], paths: ["/**"], mode: "deny" },
      ],
    },
  ],
});
if (!agent) throw new Error("subagent: agent not created");

서브에이전트에게 명시적으로 제한 없는 접근을 부여하려면 permissions: []를 설정하세요. 빈 배열은 제한 없이 부모 규칙을 대체합니다. permissions를 생략하면 부모에서 상속합니다.

컴포지트 백엔드 (Composite backends)

샌드박스 기본값의 CompositeBackend를 사용할 때, 모든 권한 경로는 알려진 라우트 접두사 아래에 범위가 지정되어야 합니다. 샌드박스는 임의 명령 실행을 지원하므로 경로 기반 제한만으로는 셸 명령을 통한 파일시스템 접근을 막을 수 없습니다. 권한을 라우트별 백엔드로 범위를 지정하면 이 충돌을 피할 수 있습니다.

const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,
});
const agent = createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/memories/**"], mode: "deny" },
  ],
});
if (!agent) throw new Error("composite-backend: agent not created");

어떤 라우트에도 없는 경로를 포함한 권한은 생성 시 throw합니다:

const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,
});

createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/workspace/**"], mode: "deny" },
  ],
});

createDeepAgent({
  model,
  backend: composite,
  permissions: [{ operations: ["read"], paths: ["/**"], mode: "deny" }],
});

더 알아보기

• 이 문서를 MCP로 연결하면 Claude, VSCode 등에서 실시간 답변을 받을 수 있어요.
• GitHub에서 이 페이지 편집하기 또는 이슈 제출하기.