🔥 09. Deep Agents: 플래닝+파일시스템+서브에이전트 하니스

Deep Agents는 LangChain/LangGraph 기반으로 만든 에이전트 하니스다. 플래닝, 파일 읽기/쓰기, 셸 실행, 서브에이전트 분기, 긴 대화 요약까지 기본 배터리를 묶어 제공한다.

이 레포는 9위 · ⭐ +4.9K로 회자된 프로젝트다. 별 숫자만 보면 유행처럼 보일 수 있지만, 실제로는 개발자들이 지금 어디에 시간을 쓰고 있는지를 꽤 솔직하게 드러낸다. 많은 개발자가 에이전트를 만들고 싶어 하지만, 매번 프롬프트·도구·파일시스템·컨텍스트 요약을 처음부터 묶는 건 귀찮다. Deep Agents는 바로 그 반복 작업을 줄인다. 특히 “Claude Code에서 뭐가 먹혔나”를 오픈소스스럽게 재구성한 느낌이라 관심이 몰리기 좋았다.

flowchart LR
A[문제] --> B[deepagents]
B --> C[설치]
C --> D[최소 실험]
D --> E[업무 적용 판단]

칠판 판서형 치트시트

• 이 레포의 한 줄 키워드는 deepagents다.
• 이번 보강에서는 설치와 사용 순서를 공식 README 기준으로 더 촘촘하게 정리했다.
• 읽을 때는 전제 조건 → 설치 → 첫 실행 → 검증 순서로 보면 된다.
• “대단해 보인다”보다 “내 업무에서 반복 비용을 줄이는가”를 먼저 본다.

이 레포를 한 줄로 보면

Deep Agents는 LangChain/LangGraph 기반으로 만든 에이전트 하니스다. 플래닝, 파일 읽기/쓰기, 셸 실행, 서브에이전트 분기, 긴 대화 요약까지 기본 배터리를 묶어 제공한다.

왜 지금 이 레포가 뜨는가

많은 개발자가 에이전트를 만들고 싶어 하지만, 매번 프롬프트·도구·파일시스템·컨텍스트 요약을 처음부터 묶는 건 귀찮다. Deep Agents는 바로 그 반복 작업을 줄인다. 특히 “Claude Code에서 뭐가 먹혔나”를 오픈소스스럽게 재구성한 느낌이라 관심이 몰리기 좋았다.

레포 안에서 먼저 볼 것

• write_todos 기반 플래닝과 진행 추적
• read/write/edit/ls/glob/grep 같은 파일시스템 도구 묶음
• 서브에이전트 분기와 자동 요약까지 포함한 out-of-the-box 하니스

설치 전에 확인할 것

• Python 환경
• LangChain 계열을 크게 커스텀하지 않고 빠르게 시작해보고 싶은 상황
• 실험할 폴더 하나

설치 방법

공식 확인 링크

• GitHub README: https://github.com/langchain-ai/deepagents
• 개요 문서: https://docs.langchain.com/oss/python/deepagents/overview
• API 레퍼런스: https://reference.langchain.com/python/deepagents/

Python 라이브러리 설치

pip install deepagents
# 또는
uv add deepagents

설치 직후 가장 짧은 예시는 아래다.

from deepagents import create_deep_agent
 
agent = create_deep_agent()
result = agent.invoke({"messages": [{"role": "user", "content": "Research LangGraph and write a summary"}]})

CLI 설치

CLI까지 보고 싶다면 공식 스크립트가 있다.

curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/main/libs/cli/scripts/install.sh | bash

README 기준 CLI는 웹 검색, 원격 샌드박스, persistent memory, human-in-the-loop approval 같은 확장 기능을 다룬다.

설치 확인

• create_deep_agent()가 기본 객체를 만들고 invoke가 응답하는지 본다.
• CLI 설치 시 실행 파일이 잡히는지 확인한다.

사용 방법

1. 가장 단순한 목표를 하나 정한다. 예: 폴더 문서 읽고 요약 만들기.
2. 기본 create_deep_agent()를 먼저 쓰고, 커스텀 모델·툴은 나중에 붙인다.
3. 필요하면 init_chat_model과 custom tool을 추가해 커스터마이즈한다.
4. 실행 로그에서 write_todos, 파일 접근, 서브에이전트 분기가 실제로 어떻게 쓰이는지 본다.

커스터마이징 예시는 공식 README 기준 아래처럼 시작한다.

from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent
 
agent = create_deep_agent(
    model=init_chat_model("openai:gpt-4o"),
    tools=[my_custom_tool],
    system_prompt="You are a research assistant.",
)

MCP는 langchain-mcp-adapters로 연결할 수 있다고 문서가 안내한다.

어디에 바로 써먹을 수 있나

사례 A. 리서치+문서 작성 에이전트

폴더 안 자료를 읽고 요약 보고서를 쓰는 작업은 Deep Agents에 잘 맞는다. 파일도 직접 읽고, 필요한 경우 서브에이전트를 따로 보내고, 중간 산출물을 저장하는 흐름이 이미 준비돼 있기 때문이다.

사례 B. 코드베이스 탐색 PoC

레거시 프로젝트에서 관련 파일을 찾고 수정 후보를 정리하는 일도 시범 적용하기 좋다. 다만 실제 수정 권한을 줄 때는 샌드박스와 승인 정책을 따로 챙겨야 한다.

처음 해볼 최소 실험

1. 작은 폴더 하나를 대상으로 요약 작업을 시킨다.
2. 기본 에이전트만으로 동작시키고 결과 파일/요약을 확인한다.
3. 그다음 custom tool 하나만 추가해 확장성을 본다.
4. 서브에이전트 분기와 자동 요약이 실제로 필요한지 판단한다.

검증 포인트는 간단하다. 도입 성공 여부는 기능 수보다, 정말로 바로 실행 가능한 기본 에이전트가 나왔는지에 달려 있다. 커스터마이징 전에 기본 흐름이 안정적인지 먼저 본다.

볼 때 주의할 점

• 프로젝트도 직접 말하듯 trust-the-LLM 모델이라 도구 경계 설계가 중요하다.
• 기본 배터리가 많아서 작은 작업에는 오히려 무거울 수 있다.
• LangGraph 생태계 이해가 전혀 없으면 내부 구조를 파악하는 데 시간이 걸린다.

다음 읽기

• 🔥 02. superpowers
• 🔥 08. Context Hub
• 🔥 Git Trend 허브

이 글은 AI를 활용해 초안을 정리했고, GitHub README와 공식 링크를 다시 확인해 실무 적용 관점으로 풀어썼다.