백엔드

적절한 사용 사례:

• 로컬 개발 CLI (코딩 어시스턴트, 개발 도구)
• 에이전트의 코드를 신뢰하는 개인 개발 환경
• 적절한 비밀 관리가 있는 CI/CD 파이프라인

부적절한 사용 사례:

• 프로덕션 환경 (웹 서버, API, 멀티테넌트 시스템 등)
• 신뢰할 수 없는 사용자 입력 처리 또는 신뢰할 수 없는 코드 실행

보안 위험:

• 에이전트가 여러분의 사용자 권한으로 임의 셸 명령을 실행할 수 있음
• 에이전트가 접근 가능한 모든 파일(비밀, API 키, 자격 증명, .env 파일 포함)을 읽을 수 있음
• 비밀이 노출될 수 있음
• 파일 수정과 명령 실행은 영구적이고 되돌릴 수 없음
• 명령이 호스트 시스템에서 직접 실행됨
• 명령이 무제한 CPU, 메모리, 디스크를 소비할 수 있음

권장 보호 장치:

1. 실행 전에 작업을 검토하고 승인하도록 휴먼 인 더 루프 (HITL) 미들웨어 활성화. 강력히 권장됩니다.
2. 전용 개발 환경에서만 실행. 공유 또는 프로덕션 시스템에서는 절대 사용 금지.
3. 셸 실행이 필요한 프로덕션 환경에는 샌드박스 백엔드 사용.

참고: 셸 접근이 활성화되면 명령이 시스템의 어떤 경로에든 접근할 수 있으므로 virtual_mode=True는 보안을 제공하지 않습니다.

import { createDeepAgent, LocalShellBackend } from "deepagents";

const backend = new LocalShellBackend({ workingDirectory: "." });

const agent = createDeepAgent({
  model: "google-genai:gemini-3.6-flash",
  backend,
});

import { createDeepAgent, LocalShellBackend } from "deepagents";

const backend = new LocalShellBackend({ workingDirectory: "." });

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  backend,
});

import { createDeepAgent, LocalShellBackend } from "deepagents";

const backend = new LocalShellBackend({ workingDirectory: "." });

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-5",
  backend,
});

import { createDeepAgent, LocalShellBackend } from "deepagents";

const backend = new LocalShellBackend({ workingDirectory: "." });

const agent = createDeepAgent({
  model: "openrouter:z-ai/glm-5.2",
  backend,
});

import { createDeepAgent, LocalShellBackend } from "deepagents";

const backend = new LocalShellBackend({ workingDirectory: "." });

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  backend,
});

import { createDeepAgent, LocalShellBackend } from "deepagents";

const backend = new LocalShellBackend({ workingDirectory: "." });

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  backend,
});

import { createDeepAgent, LocalShellBackend } from "deepagents";

const backend = new LocalShellBackend({ workingDirectory: "." });

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  backend,
});

작동 방식:

• 호스트에서 셸 명령을 실행하는 execute 도구로 FilesystemBackend를 확장합니다.
• 명령은 샌드박싱 없이 subprocess.run(shell=True)를 사용해 머신에서 직접 실행됩니다.
• 환경 변수용 timeout(기본 120초), max_output_bytes(기본 100,000), env, inherit_env를 지원합니다.
• 셸 명령은 root_dir을 작업 디렉터리로 사용하지만 시스템의 어떤 경로에든 접근할 수 있습니다.

최적의 경우:

• 로컬 코딩 어시스턴트 및 개발 도구
• 에이전트를 신뢰할 때 개발 중 빠른 반복

StoreBackend (LangGraph store)

import { createDeepAgent, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore(); // Good for local dev; omit for LangSmith Deployment

const agent = createDeepAgent({
  model: "google-genai:gemini-3.6-flash",
  backend: new StoreBackend({
    namespace: (rt) => [rt.serverInfo.user.identity],
  }),
  store,
});

import { createDeepAgent, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore(); // Good for local dev; omit for LangSmith Deployment

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  backend: new StoreBackend({
    namespace: (rt) => [rt.serverInfo.user.identity],
  }),
  store,
});

import { createDeepAgent, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore(); // Good for local dev; omit for LangSmith Deployment

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-5",
  backend: new StoreBackend({
    namespace: (rt) => [rt.serverInfo.user.identity],
  }),
  store,
});

import { createDeepAgent, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore(); // Good for local dev; omit for LangSmith Deployment

const agent = createDeepAgent({
  model: "openrouter:z-ai/glm-5.2",
  backend: new StoreBackend({
    namespace: (rt) => [rt.serverInfo.user.identity],
  }),
  store,
});

import { createDeepAgent, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore(); // Good for local dev; omit for LangSmith Deployment

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  backend: new StoreBackend({
    namespace: (rt) => [rt.serverInfo.user.identity],
  }),
  store,
});

import { createDeepAgent, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore(); // Good for local dev; omit for LangSmith Deployment

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  backend: new StoreBackend({
    namespace: (rt) => [rt.serverInfo.user.identity],
  }),
  store,
});

import { createDeepAgent, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore(); // Good for local dev; omit for LangSmith Deployment

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  backend: new StoreBackend({
    namespace: (rt) => [rt.serverInfo.user.identity],
  }),
  store,
});

작동 방식:

• StoreBackend는 런타임이 제공하는 LangGraph BaseStore에 파일을 저장하여 스레드 간 내구성 스토리지를 가능하게 합니다.

최적의 경우:

• 이미 구성된 LangGraph 스토어(BaseStore 뒤의 Redis, Postgres, 클라우드 구현 등)로 실행 중일 때.
• LangSmith Deployment로 에이전트를 배포할 때 (에이전트를 위한 스토어가 자동으로 프로비저닝됨).

네임스페이스 팩토리 (Namespace factories)

네임스페이스 팩토리는 StoreBackend가 데이터를 읽고 쓰는 위치를 제어합니다. LangGraph Runtime을 받아 스토어 네임스페이스로 사용되는 문자열 튜플을 반환합니다. 사용자, 테넌트, 어시스턴트 간에 데이터를 격리하려면 네임스페이스 팩토리를 사용하세요.

StoreBackend를 구성할 때 namespace 파라미터에 네임스페이스 팩토리를 전달하세요:

NamespaceFactory = Callable[[Runtime], tuple[str, ...]]

Runtime은 다음을 제공합니다:

• rt.context — LangGraph의 컨텍스트 스키마를 통해 전달된 사용자 제공 컨텍스트 (예: user_id)
• rt.serverInfo — LangGraph Server에서 실행할 때의 서버별 메타데이터 (어시스턴트 ID, 그래프 ID, 인증된 사용자)
• rt.executionInfo — 실행 식별 정보 (스레드 ID, 실행 ID, 체크포인트 ID)

일반적인 네임스페이스 패턴:

import { StoreBackend } from "deepagents";

// Per-user: each user gets their own isolated storage
const backend = new StoreBackend({
  namespace: (rt) => [rt.serverInfo.user.identity],  // [!code highlight]
});

// Per-assistant: all users of the same assistant share storage
const backend = new StoreBackend({
  namespace: (rt) => [rt.serverInfo.assistantId],  // [!code highlight]
});

// Per-thread: storage scoped to a single conversation
const backend = new StoreBackend({
  namespace: (rt) => [rt.executionInfo.threadId],  // [!code highlight]
});

더 구체적인 범위를 위해 여러 컴포넌트를 결합할 수 있습니다 — 예: 사용자별·대화별 격리의 (user_id, thread_id), 또는 같은 범위가 여러 스토어 네임스페이스를 사용할 때 "filesystem" 같은 접미사를 붙여 구별할 수 있습니다.

네임스페이스 컴포넌트는 영숫자 문자, 하이픈, 밑줄, 점, @, +, 콜론, 물결표만 포함해야 합니다. 와일드카드(*, ?)는 glob 주입을 방지하기 위해 거부됩니다.

ContextHubBackend

ContextHubBackend는 에이전트의 파일시스템을 LangSmith Context Hub 저장소에 저장합니다. 독립형 저장소 또는 스킬 저장소로 링크되는 에이전트 저장소를 사용할 수 있습니다.

저장소 구조: Context Hub에서 에이전트 저장소는 에이전트의 최상위 지침과 설정(예: AGENTS.md, tools.json)을 보유합니다. 하나 이상의 스킬 저장소로 링크할 수 있으며, 각 스킬 저장소는 재사용 가능한 능력(예: 이메일 포맷팅이나 코드 리뷰 지침이 있는 SKILL.md)으로 패키징됩니다. ContextHubBackend("my-agent")를 전달하면 백엔드가 에이전트 저장소를 파일시스템 루트에 마운트하고, 링크된 스킬 저장소는 /skills/ 아래 하위 디렉터리로 나타납니다.

이는 에이전트의 컨텍스트가 의도적으로 여러 저장소에 걸쳐 있다는 뜻입니다: 에이전트당 하나의 저장소, 스킬별 별도 저장소. 그 분리는 스킬이 여러 에이전트에서 독립적으로 버전 관리, 공유, 재사용될 수 있게 합니다. 분산되어 보인다면 연결된 저장소에서 그 근거를 확인하세요.

owner/name 또는 name 형식의 저장소 식별자로 구성하세요.

작동 방식:

• 첫 사용 시 Hub 저장소 트리를 지연적으로 가져오고, 이후 읽기는 인메모리 캐시에서 제공합니다.
• 쓰기와 편집을 Hub 커밋으로 영속화하고 성공적인 커밋 후 캐시를 업데이트합니다.
• 낙관적 부모 커밋 쓰기(parent_commit)를 사용합니다: 각 푸시는 가장 최근에 알려진 커밋 해시를 대상으로 합니다.

동작 및 제한:

• 저장소가 존재하지 않으면 첫 가져오기는 빈 것으로 처리됩니다; 첫 성공적인 쓰기가 저장소를 만들 수 있습니다.
• 다른 작성자가 먼저 저장소를 진행하면, 오래된 부모 커밋 쓰기가 실패할 수 있습니다. 충돌 시 다시 가져와 재시도하세요.
• upload_files()는 UTF-8 텍스트를 수용합니다. 비-UTF-8 파일은 경로별로 invalid_path로 거부됩니다.

최적의 경우:

• LangGraph BaseStore를 별도로 연결하지 않는 LangSmith 네이티브 내구성 파일시스템 영속성.
• 파일시스템 변경에 Hub 커밋 기록의 이점을 활용하는 워크플로.

CompositeBackend (라우터)

import {
  createDeepAgent,
  CompositeBackend,
  StateBackend,
  StoreBackend,
} from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = createDeepAgent({
  model: "google-genai:gemini-3.6-flash",
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: () => ["memories"],
    }),
  }),
  store,
});

import {
  createDeepAgent,
  CompositeBackend,
  StateBackend,
  StoreBackend,
} from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: () => ["memories"],
    }),
  }),
  store,
});

import {
  createDeepAgent,
  CompositeBackend,
  StateBackend,
  StoreBackend,
} from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-5",
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: () => ["memories"],
    }),
  }),
  store,
});

import {
  createDeepAgent,
  CompositeBackend,
  StateBackend,
  StoreBackend,
} from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = createDeepAgent({
  model: "openrouter:z-ai/glm-5.2",
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: () => ["memories"],
    }),
  }),
  store,
});

import {
  createDeepAgent,
  CompositeBackend,
  StateBackend,
  StoreBackend,
} from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: () => ["memories"],
    }),
  }),
  store,
});

import {
  createDeepAgent,
  CompositeBackend,
  StateBackend,
  StoreBackend,
} from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: () => ["memories"],
    }),
  }),
  store,
});

import {
  createDeepAgent,
  CompositeBackend,
  StateBackend,
  StoreBackend,
} from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: () => ["memories"],
    }),
  }),
  store,
});

작동 방식:

• CompositeBackend는 경로 접두사에 따라 파일 연산을 서로 다른 백엔드로 라우팅합니다.
• 목록과 검색 결과에서 원래 경로 접두사를 보존합니다.

최적의 경우:

• 에이전트에게 스레드 범위와 스레드 간 스토리지를 모두 주고 싶을 때, CompositeBackend로 StateBackend와 StoreBackend를 모두 제공할 수 있습니다.
• 에이전트에게 단일 파일시스템의 일부로 제공하려는 여러 정보 소스가 있을 때.
  • 예: 한 Store의 /memories/ 아래에 장기 메모리를 저장하고, /docs/에서 접근할 수 있는 문서를 가진 커스텀 백엔드도 있을 때.

백엔드 지정하기 (Specify a backend)

• 백엔드 인스턴스를 createDeepAgent({ backend: ... })에 전달하세요. 파일시스템 미들웨어가 모든 도구에 이를 사용합니다.
• 백엔드는 AnyBackendProtocol(BackendProtocolV1 또는 BackendProtocolV2)을 구현해야 합니다 — 예: new StateBackend(), new FilesystemBackend({ rootDir: "." }), new StoreBackend().
• 생략하면 기본값은 new StateBackend()입니다.

다른 백엔드로 라우팅 (Route to different backends)

네임스페이스의 일부를 다른 백엔드로 라우팅합니다. 일반적으로 /memories/*를 스레드 간에 영속시키고 나머지는 스레드 범위로 유지하는 데 사용합니다.

import { createDeepAgent, CompositeBackend, FilesystemBackend, StateBackend } from "deepagents";

const agent = createDeepAgent({
  backend: new CompositeBackend(
    new StateBackend(),
    {
      "/memories/": new FilesystemBackend({ rootDir: "/deepagents/myagent", virtualMode: true }),
    },
  ),
});

동작:

• /workspace/plan.md → StateBackend (스레드 범위)
• /memories/agent.md → /deepagents/myagent 아래 FilesystemBackend
• ls, glob, grep는 결과를 집계하고 원래 경로 접두사를 보여줍니다.

참고:

• 더 긴 접두사가 우선합니다 (예: "/memories/projects/"가 "/memories/"를 덮어쓸 수 있음).
• StoreBackend 라우팅의 경우 create_deep_agent(model=..., store=...)로 스토어를 제공하거나 플랫폼이 프로비저닝했는지 확인하세요.
• Deep Agents는 내부 데이터(오프로드된 도구 결과, 대화 기록)를 기본 백엔드에 씁니다. 기본값으로 StateBackend를 사용해 이 산출물을 일시적으로 유지하고 디스크나 영구 스토어에 쓰지 않게 하세요. 완전한 예시는 FilesystemBackend 팁을 참고하세요.

커스텀 백엔드 (Custom backends)

데이터베이스, 객체 스토어, 원격 파일시스템 같은 스토리지 시스템에 Deep Agents를 연결하려면 커스텀 백엔드를 구현하세요. 예시는 커뮤니티 구축 백엔드를 참고하세요.

백엔드 프로토콜 구현 (Implement the backend protocol)

BackendProtocol(BackendProtocolV2)을 구현하고 다음 메서드를 제공하세요:

execute 도구(셸 명령 실행)도 지원하려면 BackendProtocolV2를 확장해 execute 메서드를 추가한 SandboxBackendProtocol을 대신 구현하세요.

모든 메서드는 선택적 error 필드가 있는 구조화된 Result 객체를 반환해야 합니다 — 누락된 파일이나 유효하지 않은 패턴에서 throw하지 마세요.

예시: S3 스타일 백엔드 스켈레톤 이 스켈레톤은 파일시스템 경로를 객체 키에 매핑합니다. 각 메서드를 스토리지 클라이언트의 list, read, search, upload, read-modify-write 연산으로 채우세요.

import {
  type BackendProtocolV2,
  type EditResult,
  type GlobResult,
  type GrepResult,
  type LsResult,
  type ReadRawResult,
  type ReadResult,
  type WriteResult,
} from "deepagents";

class S3Backend implements BackendProtocolV2 {
  constructor(private bucket: string, private prefix: string = "") {
    this.prefix = prefix.replace(/\/$/, "");
  }

  private key(path: string): string {
    return `${this.prefix}${path}`;
  }

  async ls(path: string): Promise<LsResult> {
    ...
  }

  async read(filePath: string, offset?: number, limit?: number): Promise<ReadResult> {
    ...
  }

  async readRaw(filePath: string): Promise<ReadRawResult> {
    ...
  }

  async grep(pattern: string, path?: string | null, glob?: string | null): Promise<GrepResult> {
    ...
  }

  async glob(pattern: string, path = "/"): Promise<GlobResult> {
    ...
  }

  async write(filePath: string, content: string): Promise<WriteResult> {
    ...
  }

  async edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult> {
    ...
  }
}

권한 (Permissions)

권한으로 에이전트가 읽거나 쓸 수 있는 파일과 디렉터리를 선언적으로 제어하세요. 권한은 내장 파일시스템 도구에 적용되며 백엔드가 호출되기 전에 평가됩니다.

규칙 순서, 서브에이전트 권한, 컴포지트 백엔드 상호작용을 포함한 전체 옵션은 권한 가이드를 참고하세요.

정책 훅 추가 (Add policy hooks)

경로 기반 허용/거부 규칙(속도 제한, 감사 로깅, 콘텐츠 검사)을 넘어서는 커스텀 검증 로직의 경우, 백엔드를 서브클래싱하거나 래핑해 엔터프라이즈 규칙을 시행하세요.

선택된 접두사 아래의 쓰기/편집 차단 (서브클래스):

import { FilesystemBackend, type WriteResult, type EditResult } from "deepagents";

class GuardedBackend extends FilesystemBackend {
  private denyPrefixes: string[];

  constructor({ denyPrefixes, ...options }: { denyPrefixes: string[]; rootDir?: string }) {
    super(options);
    this.denyPrefixes = denyPrefixes.map(p => p.endsWith("/") ? p : p + "/");
  }

  async write(filePath: string, content: string): Promise<WriteResult> {
    if (this.denyPrefixes.some(p => filePath.startsWith(p))) {
      return { error: `Writes are not allowed under ${filePath}` };
    }
    return super.write(filePath, content);
  }

  async edit(filePath: string, oldString: string, newString: string, replaceAll = false): Promise<EditResult> {
    if (this.denyPrefixes.some(p => filePath.startsWith(p))) {
      return { error: `Edits are not allowed under ${filePath}` };
    }
    return super.edit(filePath, oldString, newString, replaceAll);
  }
}

일반 래퍼 (모든 백엔드에서 작동):

import {
  type BackendProtocolV2,
  type LsResult,
  type ReadResult,
  type ReadRawResult,
  type GrepResult,
  type GlobResult,
  type WriteResult,
  type EditResult,
} from "deepagents";

class PolicyWrapper implements BackendProtocolV2 {
  private denyPrefixes: string[];

  constructor(private inner: BackendProtocolV2, denyPrefixes: string[] = []) {
    this.denyPrefixes = denyPrefixes.map(p => p.endsWith("/") ? p : p + "/");
  }

  private isDenied(path: string): boolean {
    return this.denyPrefixes.some(p => path.startsWith(p));
  }

  ls(path: string): Promise<LsResult> { return this.inner.ls(path); }
  read(filePath: string, offset?: number, limit?: number): Promise<ReadResult> { return this.inner.read(filePath, offset, limit); }
  readRaw(filePath: string): Promise<ReadRawResult> { return this.inner.readRaw(filePath); }
  grep(pattern: string, path?: string | null, glob?: string | null): Promise<GrepResult> { return this.inner.grep(pattern, path, glob); }
  glob(pattern: string, path?: string): Promise<GlobResult> { return this.inner.glob(pattern, path); }

  async write(filePath: string, content: string): Promise<WriteResult> {
    if (this.isDenied(filePath)) return { error: `Writes are not allowed under ${filePath}` };
    return this.inner.write(filePath, content);
  }

  async edit(filePath: string, oldString: string, newString: string, replaceAll = false): Promise<EditResult> {
    if (this.isDenied(filePath)) return { error: `Edits are not allowed under ${filePath}` };
    return this.inner.edit(filePath, oldString, newString, replaceAll);
  }
}

멀티모달 및 바이너리 파일 (Multimodal and binary files)

V2 백엔드는 바이너리 파일을 네이티브로 지원합니다. read()가 바이너리 파일(파일 확장자의 MIME 유형으로 결정)을 만나면 Uint8Array 콘텐츠와 해당 mimeType을 가진 ReadResult를 반환합니다. 텍스트 파일은 string 콘텐츠를 반환합니다.

지원 MIME 유형

바이너리 파일 읽기

const result = await backend.read("/workspace/screenshot.png");

if (result.error) {
  console.error(result.error);
} else if (result.content instanceof Uint8Array) {
  // Binary file — content is Uint8Array, mimeType is set
  console.log(`Binary file: ${result.mimeType}`); // "image/png"
} else {
  // Text file — content is string
  console.log(`Text file: ${result.mimeType}`); // "text/plain"
}

FileData 형식

FileData는 state 및 store 백엔드에서 파일 콘텐츠를 저장하는 데 사용되는 유형입니다.

type FileData =
  // Current format (v2)
  | {
      content: string | Uint8Array; // string for text, Uint8Array for binary
      mimeType: string;             // e.g. "text/plain", "image/png"
      created_at: string;           // ISO 8601 timestamp
      modified_at: string;          // ISO 8601 timestamp
    }
  // Legacy format (v1)
  | {
      content: string[];            // array of lines
      created_at: string;           // ISO 8601 timestamp
      modified_at: string;          // ISO 8601 timestamp
    };

백엔드는 state 또는 store에서 읽을 때 두 형식 모두를 만날 수 있습니다. 프레임워크는 둘 다 투명하게 처리합니다. 새 쓰기는 기본적으로 v2 형식입니다. 이전 독자가 레거시 형식을 필요로 하는 롤링 배포 중에는 백엔드 생성자에 fileFormat: "v1"을 전달하세요 (예: new StoreBackend({ fileFormat: "v1" })).

백엔드 팩토리에서 마이그레이션 (Migrate from backend factories)

이전에는 StateBackend와 StoreBackend 같은 백엔드가 작동하려면 런타임 컨텍스트(state, store)가 필요했기 때문에, 런타임 객체를 받는 팩토리 함수가 필요했습니다. 백엔드는 이제 LangGraph의 get_config(), get_store(), get_runtime() 헬퍼를 통해 이 컨텍스트를 내부적으로 해결하므로 인스턴스를 직접 전달할 수 있습니다.

무엇이 바뀌었나 (What changed)

Deprecated API

마이그레이션 예시

// Before (deprecated)
import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";

const agent = createDeepAgent({
  backend: (config) => new CompositeBackend(
    new StateBackend(config),
    { "/memories/": new StoreBackend(config, {
      namespace: (rt) => [rt.serverInfo.user.identity],
    }) },
  ),
});

// After
const agent = createDeepAgent({
  backend: new CompositeBackend(
    new StateBackend(),
    { "/memories/": new StoreBackend({
      namespace: (rt) => [rt.serverInfo.user.identity],
    }) },
  ),
});

BackendContext에서 마이그레이션

deepagents>=0.5.2(Python) 및 deepagents>=1.9.1(TypeScript)에서 네임스페이스 팩토리는 BackendContext 래퍼 대신 LangGraph Runtime을 직접 받습니다. 이전 BackendContext 형식은 하위 호환 .runtime과 .state 접근자를 통해 여전히 작동하지만, 이 접근자는 deprecation 경고를 방출하며 deepagents>=0.7에서 제거될 것입니다.

바뀐 것:

• 팩토리 인자는 이제 BackendContext가 아닌 Runtime입니다.
• .runtime 접근자를 제거하세요 — 예: ctx.runtime.context.user_id는 rt.server_info.user.identity가 됩니다.
• ctx.state에 대한 직접적인 대체는 없습니다. 네임스페이스 정보는 실행 수명 동안 읽기 전용이고 안정적이어야 하지만, state는 변경 가능하며 단계마다 바뀝니다 — state에서 네임스페이스를 파생하면 데이터가 일관되지 않은 키 아래에 들어갈 위험이 있습니다. 에이전트 state를 읽어야 하는 사용 사례가 있으면 이슈를 열어주세요.

// Before (deprecated, removed in v0.7)
new StoreBackend({
  namespace: (ctx) => [ctx.runtime.context.userId],  // [!code --]
});

// After
new StoreBackend({
  namespace: (rt) => [rt.serverInfo.user.identity],  // [!code ++]
});

프로토콜 레퍼런스 (Protocol reference)

백엔드는 BackendProtocol를 구현해야 합니다.

필수 메서드:

• ls(path: string) → LsResult — 최소 path가 있는 항목을 반환. 가능하면 is_dir, size, modified_at 포함. 결정적인 출력을 위해 path로 정렬.
• read(filePath: string, offset?: number, limit?: number) → ReadResult — 성공 시 파일 데이터를 반환. 파일 누락 시 { error: "File '/x' not found" } 반환.
• readRaw(filePath: string) → ReadRawResult — 파일 콘텐츠를 원시 FileData로 읽기. 타임스탬프를 포함한 전체 파일 데이터를 반환.
• grep(pattern: string, path?: string | null, glob?: string | null) → GrepResult — 리터럴 텍스트 패턴에 대한 파일 내용 검색. MIME 유형으로 판별된 바이너리 파일은 건너뜀. 실패 시 { error: "..." } 반환.
• glob(pattern: string, path?: string) → GlobResult — glob 패턴과 일치하는 파일을 FileInfo 항목으로 반환.
• write(filePath: string, content: string) → WriteResult — 생성 전용 의미. 충돌 시 { error: "..." } 반환. 성공 시 path를 설정하고 state 백엔드의 경우 filesUpdate={...} 설정; 외부 백엔드는 filesUpdate=null 사용.
• edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean) → EditResult — replaceAll=true가 아니면 oldString의 고유성을 강제. 없다면 오류 반환. 성공 시 occurrences 포함.

선택 메서드:

• uploadFiles(files: Array<[string, Uint8Array]>) → FileUploadResponse[] — 여러 파일 업로드 (샌드박스 백엔드용).
• downloadFiles(paths: string[]) → FileDownloadResponse[] — 여러 파일 다운로드 (샌드박스 백엔드용).

결과 유형:

지원 유형:

• FileInfo — path (필수), 선택적으로 is_dir, size, modified_at.
• GrepMatch — path, line (1-인덱스), text.
• FileData — 타임스탬프가 있는 파일 콘텐츠. FileData 형식 참고.

샌드박스 확장:

SandboxBackendProtocolV2는 BackendProtocolV2를 확장합니다:

• execute(command: string) → ExecuteResponse — 샌드박스에서 셸 명령 실행.
• readonly id: string — 샌드박스 인스턴스의 고유 식별자.

기존 백엔드를 V2로 업데이트 (Update existing backends to V2)

메서드 이름 변경:

유형 이름 변경:

적응 유틸리티:

V2 전용 코드와 함께 사용해야 하는 기존 V1 백엔드가 있다면 적응 함수를 사용하세요:

import { adaptBackendProtocol, adaptSandboxProtocol } from "deepagents";

// Adapt a V1 backend to V2
const v2Backend = adaptBackendProtocol(v1Backend);

// Adapt a V1 sandbox to V2
const v2Sandbox = adaptSandboxProtocol(v1Sandbox);

더 알아보기

• OpenWiki: 에이전트가 파일시스템 도구로 읽는 내구성 있는 저장소 Markdown 생성
• 메모리: 파일시스템 기반 장기 메모리
• 샌드박스: 격리된 파일시스템 및 셸 실행

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