Deep Agents 개요

Deep Agents 개요 (Deep Agents overview)

Deep Agents는 LLM으로 구동되는 에이전트와 애플리케이션을 만들기 시작하는 가장 쉬운 방법이에요. 컨텍스트 관리를 위한 파일시스템, 서브에이전트 스폰, 장기 메모리 같은 기능이 기본 내장되어 있고, 작업 계획(task planning)이나 스킬 같은 선택 기능은 필요할 때만 확장해 쓸 수 있어요. 복잡하고 여러 단계로 나뉜 작업까지, 거의 모든 작업에 딥 에이전트를 쓸 수 있어요.

출처: 공식문서

기본 제공 기능

Deep Agents가 기본으로 제공하는 능력은 다음과 같아요.

환경에서 행동하기: 도구로 행동하고, 파일을 읽고 쓰고, 코드를 실행
데이터 연결: 적절한 순간에 메모리·스킬·도메인 지식을 로드
커지는 컨텍스트 관리: 긴 실행 동안 히스토리 요약과 큰 결과를 오프로드
작업 병렬화: 격리된 컨텍스트 윈도우 안에서 돌아가는 일반·전용 서브에이전트에게 위임
루프 유지: 중요한 결정 지점에서 인간 승인을 위해 일시 정지
시간이 지나며 개선: 실제 사용을 바탕으로 메모리·스킬·프롬프트 갱신

각 구성 요소를 자세히 보려면 Core capabilities 섹션을 참고하면 돼요.

Quickstart

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

model=에는 원하는 제공자 식별자를 넣으면 돼요. 예를 들어 openai:gpt-5.5, anthropic:claude-sonnet-4-6, openrouter:z-ai/glm-5.2, fireworks:accounts/fireworks/models/glm-5p2, baseten:zai-org/GLM-5.2, ollama:north-mini-code-1.0 같은 형식으로요. (각 제공자별로 동일한 코드 패턴이 적용돼요.)

Core capabilities

Deep Agents는 "에이전트 하네스(agent harness)"예요. 다른 에이전트 프레임워크와 같은 핵심 툴 호출 루프를 쓰면서도, 실제 작업에서 에이전트를 믿고 쓸 수 있게 해 주는 기능들이 내장되어 있어요.

실행 환경: 도구, 가상 파일시스템, 선택적 샌드박스, REPL(인터프리터)
컨텍스트 관리: 스킬, 메모리, 요약, 컨텍스트 오프로드, 프롬프트 캐싱
위임: 서브에이전트 스폰과 선택적 작업 계획
스티어링: human-in-the-loop 승인과 인터럽트

deepagents는 LangChain의 에이전트용 핵심 빌딩 블록 위에 세워진 독립 라이브러리예요. 내구성 있는 실행, 스트리밍, human-in-the-loop 같은 기능을 위해 LangGraph 런타임을 사용하지요. 이런 내장 기능 없이 커스텀 에이전트를 만들고 싶다면 LangChain의 create_agent나 커스텀 LangGraph 워크플로를 고려해 볼 수 있어요.

실행 환경 (Execution environment)

에이전트가 행동하는 장소로, 네 개의 계층이 있어요.

도구: 에이전트가 호출할 수 있는 커스텀 함수·API·데이터베이스
가상 파일시스템: 플러그 가능한 백엔드가 뒷받침하는 파일 도구
파일시스템 권한: 에이전트가 읽거나 쓸 수 있는 경로를 선언적으로 제어
코드 실행: 샌드박스 처리된 셸 실행과 프로세스 내 JavaScript 인터프리터

도구와 MCP

tools= 파라미터로 커스텀 함수, LangChain 도구, 또는 어떤 MCP 서버의 도구든 넘길 수 있어요. Deep Agents는 Model Context Protocol(MCP)을 완전히 지원해서, 데이터베이스·API·파일시스템 등을 표준 인터페이스로 연결할 수 있지요.

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[search, fetch_page, run_query],
)

가상 파일시스템 접근

하네스는 설정 가능한 가상 파일시스템을 제공해요. 메모리 상태, 로컬 디스크, LangGraph store, 합성 라우팅, 또는 읽기·쓰기 권한 규칙을 가진 커스텀 백엔드로 뒷받침할 수 있어요. 제공되는 파일시스템 연산은 다음과 같아요.

도구	설명
`ls`	메타데이터(크기·수정 시간)와 함께 디렉터리 파일 나열
`read_file`	줄 번호와 함께 파일 읽기, 큰 파일용 offset/limit 지원. 텍스트가 아닌 파일(이미지·비디오·오디오·문서)은 멀티모달 콘텐츠 블록으로 반환
`write_file`	새 파일 생성 또는 기존 파일 덮어쓰기
`edit_file`	파일에서 정확한 문자열 치환(글로벌 교체 모드 포함)
`delete`	파일 삭제, 또는 디렉터리와 내용 재귀 삭제
`glob`	패턴(예: `*/.py`)에 맞는 파일 찾기
`grep`	여러 출력 모드(파일만·컨텍스트 포함 내용·개수)로 파일 내용 검색
`execute`	환경에서 셸 명령 실행 (샌드박스 백엔드에서만 제공)

delete 도구는 deepagents>=0.7이 필요해요. 삭제를 지원하지 않는 백엔드에서는 이 도구가 모델에서 자동으로 숨겨져요.

지원되는 멀티모달 파일 확장자는 다음과 같아요.

유형	확장자
이미지	`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.heic`, `.heif`
비디오	`.mp4`, `.mpeg`, `.mov`, `.avi`, `.flv`, `.mpg`, `.webm`, `.wmv`, `.3gpp`
오디오	`.wav`, `.mp3`, `.aiff`, `.aac`, `.ogg`, `.flac`
파일	`.pdf`, `.ppt`, `.pptx`

파일시스템 도구 숨기기

파일시스템 도구를 모델에서 숨기려면 excluded_tools로 하네스 프로필을 등록하면 돼요. FilesystemMiddleware 자체를 excluded_middleware로 제거하는 방식은 의도적으로 거부되니 참고하세요. excluded_tools로 모델에 보이는 도구 표면만 숨기고 미들웨어는 그대로 두는 게 맞아요.

파일시스템 도구 제한하기

전부 숨기는 대신 일부만 노출하려면, FilesystemMiddleware에 도구 허용 목록(allowlist)을 넘기고 middleware=를 통해 인스턴스를 제공해요. 목록에서 빠진 내장 파일시스템 도구는 모델의 도구 목록에서 제거돼요.

from deepagents import create_deep_agent
from deepagents.middleware import FilesystemMiddleware

# Read-only agent: write_file, edit_file, delete, and execute are never shown
agent = create_deep_agent(
    model="claude-sonnet-4-6",
    middleware=[
        FilesystemMiddleware(backend=backend, tools=["read_file", "ls", "glob", "grep"]),
    ],
)

read_file은 목록에 항상 포함해야 해요. 빠뜨리면 에이전트 생성 시 ValueError가 나요. execute와 delete도 설정된 백엔드가 지원하지 않으면 도구 표면에서 빠져요. create_deep_agent의 tools=로 추가한 커스텀 도구는 이 허용 목록의 영향을 받지 않아요. 선언적 서브에이전트는 이 제한을 상속하지 않으니, 필요하면 해당 서브에이전트의 middleware 필드에 FilesystemMiddleware(tools=...) 인스턴스를 넣어 독립적으로 제한해야 해요.

파일시스템 권한 (Filesystem permissions)

하네스는 에이전트가 읽거나 쓸 수 있는 파일·디렉터리를 제어하는 선언적 권한 규칙을 지원해요. 에이전트를 만들 때 permissions=에 규칙 리스트를 넘기면 되고, 각 규칙은 다음을 담아요.

operations: "read" 및/또는 "write"
paths: 파일·디렉터리의 Glob 패턴
mode: "allow" 또는 "deny"

규칙은 위에서 아래로 평가되고 첫 번째로 일치하는 규칙이 우선해요. 일치하는 규칙이 없으면 기본적으로 허용돼요. 이 모델로 에이전트를 특정 디렉터리(예: /workspace/)에 국한하거나, .env 같은 민감 파일을 보호하고, 부모 에이전트보다 서브에이전트에 더 좁은 접근 권한을 줄 수 있어요. 샌드박스 백엔드에는 권한이 적용되지 않아요(execute로 임의 명령 실행을 지원하니까). 커스텀 검증 로직이 필요하면 백엔드 정책 훅(policy hooks)을 쓰세요.

코드 실행 (Code execution)

Deep Agents는 코드 실행을 두 가지 방식으로 지원해요.

샌드박스 백엔드 — 격리된 환경에서 셸 명령을 실행하는 execute 도구 노출. 의존성 설치, 테스트 실행, CLI 호출, OS 파일시스템 작업이 필요할 때 사용해요. SandboxBackendProtocolV2를 구현하며, 감지되면 하네스가 execute 도구를 추가해요.
인터프리터 — 스코프된 QuickJS 런타임에서 JavaScript를 실행하는 eval 도구 추가. 루프·배칭·결정적 데이터 변환·프로그래매틱 툴 호출용 가벼운 계층이 필요할 때 사용해요. 셸 접근, 패키지 설치, 파일시스템·네트워크 접근은 제공하지 않아요.

스트리밍 (Streaming)

이벤트 스트리밍은 에이전트 실행을 메시지·툴 호출·값·출력에 대한 타입화된 투영(projection)으로 노출해요. Deep Agents는 stream.subagents를 추가해서, 각 위임된 작업이 독립적인 메시지·툴 호출·중첩 서브에이전트 스트림을 가진 자체 핸들을 갖게 해요.

컨텍스트 관리 (Context management)

에이전트가 무엇을 아는지, 토큰 한도 안에서 얼마나 오래 동작할 수 있는지, 세션 간 무엇을 유지하는지 제어하는 구성 요소로, 네 개의 계층이 있어요.

스킬: 스킬 파일에서 점진적으로 로드되는 온디맨드 도메인 지식. 각 스킬은 Agent Skills 표준을 따르며 SKILL.md 파일이 있는 디렉터리로 구성돼요. Deep Agents는 progressive disclosure 방식으로, 시작 시 SKILL.md 프론트매터만 읽고 작업에 실제 필요할 때 전체 스킬 내용을 읽어요. 그래서 시작 컨텍스트는 가볍게 유지하면서 풍부한 기능은 온디맨드로 제공할 수 있어요.
메모리: 대화 전반에 걸친 영속 컨텍스트(코딩 스타일, 선호, 규칙, 프로젝트 가이드라인). 에이전트를 만들 때 memory 파라미터로 넘기는 AGENTS.md 파일을 사용해요. 스킬과 달리 메모리 파일은 항상 로드되고, 내용은 설정한 백엔드(StateBackend, StoreBackend, 또는 FilesystemBackend)에 저장돼요.
요약과 컨텍스트 오프로드: 대화 히스토리와 큰 툴 결과를 자동으로 압축. 입력 컨텍스트(시스템 프롬프트·메모리·스킬·툴 프롬프트), 압축(내장 오프로딩·요약), 격리(서브에이전트가 무거운 하위 작업을 격리하고 최종 결과만 반환), 장기 메모리(가상 파일시스템 영속 저장)가 함께 동작해요.
프롬프트 캐싱: Anthropic과 Amazon Bedrock 모델에서 create_deep_agent가 시스템 프롬프트의 정적 부분(매 턴 반복되는 기본 에이전트 지시·메모리·스킬 내용)에 자동으로 프롬프트 캐싱을 적용해요. 같은 토큰을 여러 번 재처리하지 않아 지연 시간과 비용을 줄여 주고, 설정 없이 기본 활성화돼요.

위임 (Delegation)

에이전트가 큰 문제를 더 작고 병렬화 가능한 작업 단위로 쪼갤 수 있게 해 주는 구성 요소로, 두 개의 계층이 있어요.

작업 계획(task planning): 구조화된 작업 추적을 위한 옵트인 write_todos 도구. v0.7부터는 옵트인 전용이에요(이전 버전에서는 기본 포함이었어요). TodoListMiddleware를 middleware 파라미터에 넘기면 에이전트가 실행 중 구조화된 작업 목록을 유지하는 write_todos 도구를 갖게 돼요.

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    middleware=[TodoListMiddleware()],
)

작업은 'pending', 'in_progress', 'completed' 상태 추적을 지원하고 에이전트 상태에 영속돼요.

서브에이전트: 메인 에이전트가 격리·장기·다단계·병렬 작업을 위해 임시 서브에이전트를 만드는 내장 task 도구. 각 호출은 고유 컨텍스트를 가진 새 에이전트 인스턴스를 만들고, 자율적으로 끝까지 실행하다가 최종 보고서 하나를 메인 에이전트에 돌려줘요.

스티어링 (Steering)

스티어링 구성 요소는 런타임에 인간이 에이전트 동작을 제어할 수 있게 하고, 에이전트 작업의 파일시스템 권한을 설정해요.

Human-in-the-loop

Deep Agents는 LangGraph 인터럽트와 통합돼서 민감한 툴 호출 시 일시 정지하고 승인받을 수 있어요. create_deep_agent의 interrupt_on 파라미터로 이 동작을 켜요. interrupt_on은 도구 이름과 인터럽트 설정의 매핑을 받아요. 예를 들어 interrupt_on={"edit_file": True}는 모든 편집 전에 일시 정지해서 호출을 승인하거나, 안내를 추가하거나, 도구 입력을 수정하고 나서 실행하게 해 줘요. 파괴적 작업, 비싼 API 호출, 인터랙티브 디버깅을 위한 런타임 안전·제어 계층이 돼요.

더 알아보기 (Learn more)

Core capabilities와 각 구성 요소 상세
Deep Agents Quickstart·Customization 가이드
도구(Tools), 백엔드(backends), 권한(Permissions), 스킬(Skills), 메모리(Memory), 서브에이전트(Subagents), human-in-the-loop 문서