Deep Agents 백엔드

Deep Agents 백엔드 (Backends)

Deep Agents는 ls, read_file, write_file, edit_file, delete, glob, grep 같은 도구를 통해 에이전트에게 파일시스템 표면(filesystem surface)을 노출해요. 이 도구들은 전부 플러그 가능한(pluggable) 백엔드를 통해 동작하지요. 이 페이지에서는 백엔드를 고르는 법, 경로별로 다른 백엔드를 연결하는 법, 커스텀 백엔드를 구현하는 법, 파일시스템 접근 권한 설정, 그리고 백엔드 프로토콜을 준수하는 법을 안내해요.

출처: 공식문서

먼저 알아둘 것

read_file 도구는 모든 백엔드에서 이미지 파일(.png, .jpg, .jpeg, .gif, .webp)을 기본 지원해서 멀티모달 콘텐츠 블록으로 반환해요. Sandbox와 LocalShellBackend는 추가로 execute 도구도 제공해요. LangSmith Deployment에 배포하면 store가 자동으로 프로비저닝되니까, LangSmith tracing으로 파일 경로·권한 거절·스레드 간 저장 문제를 디버깅할 수 있어요. 추적을 모니터링하고 문제를 감지해 수정안을 제안하는 LangSmith Engine도 추천해요.

Quickstart — 미리 만들어진 백엔드

딥 에이전트에서 바로 쓸 수 있는 파일시스템 백엔드는 다음과 같아요.

내장 백엔드

StateBackend

기본 백엔드예요. create_deep_agent에 백엔드를 지정하지 않으면 자동으로 제공돼요.

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# By default we provide a StateBackend
agent = create_deep_agent(model="google_genai:gemini-3.6-flash")

# Under the hood, it looks like
agent2 = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=StateBackend(),
)

StoreBackend와 namespace

StoreBackend는 LangGraph BaseStore에 파일을 저장해 스레드 간에 유지되는 저장을 제공해요. 다중 사용자·다중 대화 격리를 위해 namespace factory를 지정할 수 있어요. 예를 들어 사용자별·대화별 격리에 ("user_id", "conversation_id") 같은 튜플을 반환하거나, 같은 스코프가 여러 store 네임스페이스를 쓸 때 "filesystem" 같은 접미사를 붙여 구분할 수 있어요. 네임스페이스 구성 요소는 영숫자, 하이픈, 밑줄, 점, @, +, 콜론, 물결표만 허용돼요. 와일드카드(*, ?)는 glob 인젝션 방지를 위해 거부돼요.

namespace 파라미터는 v0.5.0에서 필수가 돼요. 새 코드에는 항상 명시적으로 설정하세요. 네임스페이스 factory를 제공하지 않으면 레거시 기본 동작으로 LangGraph config 메타데이터의 assistant_id를 사용해요. 즉 같은 어시스턴트의 모든 사용자가 저장 공간을 공유하게 되죠. 다중 사용자 운영에서는 항상 namespace factory를 제공하세요.

ContextHubBackend

시작 전에 ContextHubBackend는 LangSmith에 Context Hub 저장소가 설정돼 있어야 해요. 이 백엔드는 에이전트의 파일시스템을 LangSmith Context Hub 저장소에 저장해요. 독립 저장소(standalone repo)나 스킬 저장소로 연결되는 에이전트 저장소를 쓸 수 있어요. ContextHubBackend("my-agent")를 넘기면 에이전트 저장소를 파일시스템 루트에 마운트하고, 연결된 스킬 저장소는 /skills/ 아래 하위 디렉터리로 나타나요. 에이전트 하나당 저장소 하나, 스킬별로 별도 저장소로 두는 셈이라, 스킬을 여러 에이전트에서 독립적으로 버전 관리·공유·재사용할 수 있어요.

사용 준비:

• 저장소 식별자를 owner/name 또는 name 형식으로 구성해요.
• 사용 전에 LANGSMITH_API_KEY를 설정하세요.

동작 방식:

• 첫 사용 시 Hub 저장소 트리를 지연해서(lazily) 가져온 뒤, 읽기는 인메모리 캐시로 처리해요.
• 쓰기·수정은 Hub 커밋으로 기록하고 성공 후 캐시를 갱신해요.
• 낙관적 부모-커밋 쓰기(parent_commit)를 사용해서 각 push가 가장 최근에 알려진 커밋 해시를 대상으로 해요.

제약과 한계:

• 저장소가 없으면 첫 pull을 빈 것으로 처리하고, 첫 성공적 쓰기가 저장소를 만들 수 있어요.
• 다른 작성자가 먼저 저장소를 진행시키면 자신의 낡은 부모-커밋 쓰기가 실패할 수 있어요. 그땐 다시 pull하고 재시도하면 돼요.
• upload_files()는 UTF-8 텍스트만 받아요. 비 UTF-8 파일은 경로당 invalid_path로 거부돼요.

코드 예시:

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=ContextHubBackend("my-agent"),
)

CompositeBackend (라우터)

경로별로 다른 백엔드를 지정해요. 아래 예시는 /memories/는 StoreBackend로, 나머지는 StateBackend로 보내요.

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    store=InMemoryStore(),  # Store passed to create_deep_agent, not backend
)

더 알아보기 (Learn more)

• 커스텀 백엔드 구현과 파일시스템 권한(permissions) 설정
• Deep Agents 개요의 가상 파일시스템 접근 섹션
• OpenWiki로 에이전트가 파일시스템 도구로 읽을 수 있는 내구성 있는 저장소 위키 만들기