Deep Agents: Skill 실행 체계가 웹으로 내려온 순간

Deep Agents는 LangChain create_agent 위에 계획·서브에이전트·파일시스템·컨텍스트 관리·Skill을 기본 탑재한 “에이전트 하네스(harness)“다.
이 글은 기능 나열보다, 내 관점에서 가장 중요한 변화 — Skill 기반 실행 체계가 로컬을 벗어나 웹으로 이식된 사건 — 에 초점을 둔다.

앞선 두 글에서 LangChain은 단일 LLM 호출의 표준화를, LangGraph는 여러 호출의 상태와 흐름 제어를 담당한다고 정리했다. 그렇다면 그 위에 한 겹이 더 있다면 무엇일까. “에이전트를 처음부터 조립하지 않고, 잘 튜닝된 기본값으로 바로 굴리고 싶다”는 요구가 바로 그 지점이다. Deep Agents는 그 층을 채우는 라이브러리다.

이 글에서는 Deep Agents가 무엇인지, 어떤 버전 변화를 거쳤는지, 기술적으로 어떤 특징이 있는지를 먼저 정리한다. 그리고 마지막에 내가 이 프로젝트에서 진짜로 주목한 한 가지 — Skill 구조를 웹에서 그대로 실행할 수 있게 되었다는 점 — 으로 수렴한다.

Deep Agents란 무엇인가: create_agent 위의 하네스

Deep Agents(deepagents)는 2025년 7월 말, LangChain의 Harrison Chase가 주말 동안 뚝딱 만들어(원문 표현은 “hacked on over the weekend”) 공개한 오픈소스 패키지에서 출발했다. 문제의식은 단순했다. “LLM을 루프에서 도구를 호출시키는” 가장 단순한 에이전트 아키텍처는 짧은 작업에는 잘 동작하지만, 길고 복잡한 다단계 작업에서는 “얕은(shallow)” 에이전트가 되어 계획을 세우고 오래 실행하지 못한다.

Deep Research, Manus, Claude Code 같은 애플리케이션은 이 한계를 네 가지 요소의 조합으로 넘어섰다는 것이 원 논지였다.

• 상세한 시스템 프롬프트 — 도구 사용법과 few-shot 예시가 촘촘히 담긴 긴 프롬프트
• 계획 도구(planning tool) — Claude Code의 Todo 리스트처럼, 사실상 no-op이지만 에이전트를 궤도에 유지시키는 컨텍스트 엔지니어링 장치
• 서브에이전트(sub agents) — 작업을 분리해 격리된 컨텍스트에서 깊게 파고들게 하는 위임 구조
• 파일시스템 — 노트를 적고 중간 결과를 저장하며, 에이전트들이 공유하는 작업 공간

핵심 알고리즘은 여전히 “LLM이 루프에서 도구를 호출하는 것”으로 동일하다. 차이는 이 네 가지를 기본 탑재했느냐에 있다. Deep Agents는 바로 이 특성들을 일반화해 “어떤 버티컬에도 커스터마이징 가능한 범용 딥 에이전트”로 패키징한 것이다.

공식 문서는 이를 에이전트 하네스(agent harness) 라고 부른다. 생태계에서의 위치를 정리하면 이렇다.

즉 Deep Agents는 LangGraph를 밑에 두고, create_agent 위에 “잘 튜닝된 기본값”을 얹은 층이다. 같은 빌딩블록을 쓰되, 오래 걸리는 다단계 작업에 맞춘 결정들이 미리 내려져 있다.

버전 변화: 주말 프로토타입에서 완비형 하네스로

Deep Agents의 궤적은 라이브러리의 성격 변화를 그대로 보여준다.

0.0.x (2025년 7월) — 개념 증명. 최초 공개 버전은 말 그대로 주말 프로토타입이었다. Claude Code에서 영감을 받은 시스템 프롬프트, no-op Todo 계획 도구, 서브에이전트 스폰 기능, 그리고 LangGraph의 state를 활용한 가상(mocked) 파일시스템 — 이 네 가지가 전부였다. 파일시스템조차 실제 디스크가 아니라 에이전트 상태 위에 흉내 낸 것이었다.

0.x 중기 — 백엔드 추상화의 등장. 가상 파일시스템이 “pluggable backend” 구조로 진화한 것이 결정적이었다. 인메모리 state, 로컬 디스크(FilesystemBackend), LangGraph store, 복합 라우팅, 커스텀 백엔드까지 — 같은 파일 도구(ls, read_file, write_file, edit_file, glob 등)가 어디에 저장되든 동일하게 동작하도록 분리됐다. 이 추상화가 나중에 Skill을 “어디서든 로드”할 수 있게 만든 토대가 된다.

0.6.x (2026년) — 필요한 게 다 갖춰진 하네스. 현재 시점의 Deep Agents는 스스로를 “the batteries-included agent harness”라 부른다. batteries-included는 Python의 표준 라이브러리 철학에서 온 관용구로, 별도로 뭘 더 붙이지 않아도 상자를 열면 바로 쓸 수 있게 필요한 것이 다 들어 있다는 뜻이다. 200개가 넘는 릴리스를 거치며 다음이 정식 기능으로 자리 잡았다.

• 서브에이전트 — 격리된 컨텍스트로 작업 위임 (task 도구)
• 파일시스템 — 로컬·샌드박스·원격 백엔드 위에서 읽기/쓰기/편집/검색
• 컨텍스트 관리 — 긴 스레드 요약, 도구 출력의 디스크 오프로딩, 프롬프트 캐싱
• 셸 접근 — 선택한 샌드박스에서 명령 실행, 인프로세스 인터프리터(REPL)
• 영속 메모리 — 세션 간 회상을 위한 pluggable state/store 백엔드
• HITL — 도구 호출 전 승인·수정·거부(interrupt_on)
• Skills — 필요할 때 로드하는 재사용 가능한 동작 단위
• 도구/MCP — 사용자 함수는 물론 임의의 MCP 서버 연결

또한 파이썬 단독을 넘어 JS/TS 라이브러리(deepagents.js), 그리고 터미널용 코딩 에이전트인 Deep Agents Code(Claude Code·Cursor에 대응하는 CLI)까지 확장됐다. 모델 관점에서는 tool calling을 지원하는 어떤 LLM이든 — 프론티어 API, 오픈웨이트, 로컬 모델 — 붙일 수 있는 model-agnostic 설계를 유지한다.

정리하면, Deep Agents의 버전 변화는 “Claude Code를 흉내 낸 프로토타입”에서 “Claude Code의 일반화된 오픈소스 재구현”으로, 그리고 다시 “프로덕션 배포 가능한 하네스”로 무게중심이 옮겨온 과정이다.

기술 특징: 컨텍스트를 다루는 네 개의 축

Deep Agents의 기술적 정체성은 공식 문서가 제시하는 네 개의 카테고리로 요약된다.

• 실행 환경(Execution environment) — 도구, 가상 파일시스템, 선택적 샌드박스, REPL 인터프리터
• 컨텍스트 관리(Context management) — Skill, 메모리, 요약, 컨텍스트 오프로딩, 프롬프트 캐싱
• 위임(Delegation) — 서브에이전트 스폰과 작업 계획
• 조종(Steering) — HITL 승인과 인터럽트

이 중 실무적으로 가장 흥미로운 건 컨텍스트 관리 축이다. 에이전트가 복잡한 작업을 오래 수행할수록 필요한 컨텍스트가 함께 불어난다. 모든 지시문을 시스템 프롬프트에 우겨넣으면, 지금 작업과 무관한 정보에 토큰을 낭비하게 된다. Deep Agents는 이 문제를 메모리(AGENTS.md, 항상 로드)와 Skill(필요할 때만 로드)이라는 두 도구로 나눠 접근한다.

여기서 Skill이 등장한다. 그리고 이 지점이 내가 이 글을 쓰는 진짜 이유다.

핵심: Skill 기반 실행 체계

SKILL.md — 디렉터리 하나가 곧 능력 하나

Skill은 워크플로, 베스트 프랙티스, 스크립트, 참조 문서, 템플릿 같은 도메인 전문성을 재사용 가능한 디렉터리로 묶은 것이다. 구조는 놀랄 만큼 단순하다.

skills/
  langgraph-docs/
    SKILL.md        # YAML frontmatter + 지시문
    scripts/        # 실행 가능한 스크립트
    references/     # 참조 문서
    assets/         # 템플릿·자산

각 Skill은 SKILL.md 하나를 중심으로 한다. 파일 상단의 YAML frontmatter에 name과 description이 있고, 그 아래에 에이전트가 따를 마크다운 지시문이 온다.

---
name: langgraph-docs
description: LangGraph 관련 요청에 대해 최신 문서를 가져와 정확한 가이드를 제공할 때 사용한다.
---

# langgraph-docs

## Instructions

### 1. 문서 인덱스 가져오기
fetch_url 도구로 https://docs.langchain.com/llms.txt 를 읽는다.

### 2. 관련 문서 선택
질문에 맞는 2-4개의 문서 URL을 인덱스에서 고른다.

### 3. 가져와서 종합
선택한 URL을 읽고, 직접적인 답을 먼저 제시한 뒤 원문을 링크한다.

에이전트를 만들 때 Skill 디렉터리 경로만 넘기면 된다.

from deepagents import create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend

backend = FilesystemBackend(root_dir="./my-project")

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=backend,
    skills=["./my-project/skills/"],
)

점진적 공개(progressive disclosure) — 3단계 로딩

Skill의 진짜 설계 미학은 점진적 공개에 있다. 모든 것을 한꺼번에 컨텍스트에 밀어넣지 않고, 필요한 순간에 층층이 로드한다.

시작 시점의 시스템 프롬프트에는 각 Skill의 이름과 한 줄 설명만 올라간다. 작업이 특정 Skill의 description과 맞아떨어지는 순간 비로소 본문을 읽고, 스크립트나 참조 문서는 그마저도 지시문이 실제로 필요로 할 때만 디스크에서 읽힌다. Deep Agents 내부에서는 SkillsMiddleware가 레벨 1·2를 담당하고, 레벨 3은 LLM이 지시문을 따라가며 스스로 읽는다.

이 구조는 컨텍스트 비대화를 막는 동시에, Skill을 에이전트·프로젝트 간에 공유하고 여러 Skill을 한 에이전트에 조합하는 것을 자연스럽게 만든다. 이름이 겹치면 나중에 나열된 소스가 이긴다(last one wins) — 베이스 Skill을 프로젝트별 Skill이 덮어쓰는 레이어링이 가능하다.

표준이 있다 — Agent Skills specification

주목할 점은 이 SKILL.md 포맷이 Deep Agents만의 사유물이 아니라는 것이다. Deep Agents의 Skill은 Agent Skills specification(agentskills.io)을 따른다. name(디렉터리명과 일치, 소문자·하이픈), description(최대 1,024자), 선택적으로 license·compatibility·allowed-tools 등의 frontmatter 필드가 규격으로 정의돼 있다.

즉 Skill은 특정 런타임에 종속된 설정이 아니라, 에이전트 간에 이식 가능한 표준 포맷이다. Claude Code에서 쓰던 skill 디렉터리를, 원리상 Deep Agents로 그대로 옮길 수 있다는 뜻이다.

내 관점: Skill 실행 체계가 웹으로 내려왔다

여기서 내가 이 프로젝트를 두고 진짜 하고 싶은 이야기로 온다.

Claude Code가 처음 보여준 것은 “잘 짜인 SKILL.md 하나가 에이전트의 능력이 된다”는 실행 모델이었다. 하지만 그것은 어디까지나 내 로컬 터미널 안에서 일어나는 일이었다. 개발자가 자기 머신에서 CLI를 띄우고, 로컬 디스크의 skill 디렉터리를 읽어 실행하는 구조. 강력하지만 닫혀 있었다.

Deep Agents가 바꾼 지점은 정확히 이것이다.

첫째, Skill이 백엔드 위에서 실행된다. 앞서 본 pluggable backend 추상화 덕분에, Skill은 로컬 디스크(FilesystemBackend)뿐 아니라 LangGraph store, 원격 소스, 인메모리 state 어디에서든 로드된다. skill 디렉터리가 더 이상 “내 노트북의 특정 경로”에 매여 있지 않다.

둘째, 그 에이전트가 곧 웹 서비스가 된다. Deep Agents는 LangGraph 런타임 위에 있고, LangGraph는 처음부터 서버 배포·스트리밍·영속화·HITL을 전제로 설계됐다. LangSmith를 붙이면 트레이싱·평가·원클릭 배포까지 이어진다. 다시 말해, 로컬 CLI에서만 돌던 skill 기반 에이전트를 웹 백엔드로 그대로 올릴 수 있다.

이 둘을 합치면 결론은 하나다.

Claude Code가 로컬에서 증명한 Skill 기반 실행 체계가, 이제 웹 애플리케이션 안에서 1급 시민(first-class primitive)으로 재현된다. 같은 SKILL.md, 같은 점진적 공개 모델, 그러나 실행되는 곳은 내 터미널이 아니라 웹 백엔드다.

이것이 왜 중요한가. 지금까지 “에이전트에게 절차적 지식을 주입한다”는 것은 대체로 시스템 프롬프트를 길게 늘리거나, RAG로 문서를 밀어넣거나, 도구를 하나 더 붙이는 일이었다. Skill은 그 사이의 빈 자리를 메운다 — 필요할 때만 열리는, 표준화되고 이식 가능한, 실행 가능한 절차 단위. 그리고 Deep Agents는 그 단위를 로컬의 울타리에서 꺼내 웹으로 옮겨 놓았다.

메모리와 Skill의 관계도 이 관점에서 다시 보인다. 문서는 둘을 스펙트럼으로 설명한다 — 항상 로드되는 메모리(AGENTS.md)와, 필요할 때 회상되는 Skill. 에이전트가 작업하며 스스로 Skill을 갱신할 수 있으므로, Skill은 사실상 점진적 공개형 메모리로 기능한다. 웹에서 돌아가는 에이전트가, 실행 중에 자기 능력을 skill 디렉터리에 적어 넣고, 다음 세션에서 다시 꺼내 쓴다. 로컬 도구가 하던 일을, 이제 서비스가 한다.

마무리

Deep Agents를 한 문장으로 요약하면 “Claude Code의 일반화된 오픈소스 재구현”이다. 계획·서브에이전트·파일시스템·상세 프롬프트라는 딥 에이전트의 네 기둥을 LangGraph/LangChain 위에 얹어, 주말 프로토타입에서 프로덕션 하네스로 성장했다.

하지만 내가 이 시리즈의 연장선에서 진짜 기록해 두고 싶은 것은 기능 목록이 아니다. Skill이라는 표준 포맷과 점진적 공개 실행 모델이, pluggable backend와 LangGraph 런타임을 만나 웹으로 이식됐다는 사실이다. 로컬 CLI의 전유물이던 skill 기반 실행 체계를, 이제 누구나 자기 웹 서비스 안에 심을 수 있다.

에이전트에게 능력을 부여하는 단위가 “프롬프트 문자열”에서 “이식 가능한 실행 가능한 디렉터리”로 바뀌는 것 — 그리고 그 실행 무대가 내 터미널에서 웹으로 넓어지는 것. Deep Agents가 남긴 가장 실질적인 변화는 여기에 있다고 본다.