LangChain DeepAgents 입문: 장기 작업 가능한 AI 에이전트 만들기 (2026)

"AI 에이전트한테 30분짜리 리서치 작업 시키면 왜 자꾸 중간에 길을 잃을까?"

📌 핵심 3줄 요약

• DeepAgents는 LangChain이 공개한 장기 작업용 에이전트 빌더로 create_deep_agent() 한 줄로 시작한다.
• 빌트인 도구 4종(write_todos · write_file · read_file · ls)과 subagent로 컨텍스트가 폭발하지 않게 잡아준다.
• LangGraph 위에 얹혀 있어 스트리밍·체크포인팅·휴먼인더루프가 그대로 작동한다.

1. DeepAgents가 뭐고 왜 나왔나

직접 pip install deepagents를 돌려보니 LangGraph와 LangChain Core가 함께 설치된다. 패키지 크기는 작지만 의존성 해소까지 30초쯤 걸렸다. 단순한 ReAct 에이전트가 30분짜리 리서치나 코딩 작업에서 자꾸 망가지는 문제를 푸는 게 목표다.

영감은 Claude Code다. LangChain 팀은 Claude Code가 잘 동작하는 이유를 4가지로 본다 — 상세한 시스템 프롬프트, 계획 도구, 서브에이전트, 가상 파일시스템. DeepAgents는 이 4요소를 라이브러리로 묶은 결과물이다.

💡 핵심 한 줄

DeepAgents = LangGraph 기반 + Claude Code 패턴의 4요소(시스템 프롬프트·계획·서브에이전트·가상 FS)를 라이브러리화한 것.

2. 설치와 첫 에이전트

파이썬 3.10 이상이면 설치는 1분도 안 걸린다. 가상환경에서 다음 두 줄이면 끝난다.

terminal · bash

pip install deepagents
export ANTHROPIC_API_KEY="sk-ant-..."

기본 모델은 Claude Sonnet 4.5(init_chat_model("claude-sonnet-4-5"))다. OpenAI나 다른 모델로 바꾸려면 model= 인자에 LangChain BaseChatModel 인스턴스를 넘기면 된다.

가장 단순한 리서치 에이전트는 다음과 같이 시작한다.

researcher.py · Python

from deepagents import create_deep_agent

def search(query: str) -> str:
    """간단한 검색 도구 — 실제로는 Tavily나 Serper로 교체."""
    return f"검색 결과: {query}에 대한 요약..."

agent = create_deep_agent(
    tools=[search],
    system_prompt="너는 시니어 리서처다. 보고서를 final_report.md에 저장해라.",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "DeepAgents 사용 사례 3가지 조사"}]
})
print(result["files"]["final_report.md"])

실제로 돌려보니 에이전트가 알아서 write_todos로 계획을 짜고, 검색을 반복한 뒤 write_file로 보고서를 남긴다. 토큰 비용은 Sonnet 4.5 기준 한 번 실행에 대략 8천~2만 토큰, 달러로는 0.05~0.15달러 수준이다.

3. 빌트인 도구 4종과 가상 파일시스템

DeepAgents가 기본으로 주는 도구는 단순하지만 강력하다. 실제 디스크가 아니라 LangGraph 상태 안의 가상 파일시스템이라 사이드 이펙트 걱정 없이 쓸 수 있다.

도구	역할	언제 쓰이나
write_todos	작업 계획을 todos 리스트로 작성	작업 시작 직후, 단계 전환 시
write_file	가상 FS에 파일 저장	중간 결과·최종 보고서 저장
read_file	가상 FS에서 파일 읽기	이전 단계 결과 참조
ls	가상 FS 파일 목록	작업 컨텍스트 점검

write_todos가 핵심이다. Claude Code의 TodoWrite와 동작이 거의 같아서, 에이전트가 "지금 어디까지 왔는지" 스스로 추적한다. 30분짜리 작업도 길을 덜 잃는 비결이 여기 있다.

4. subagent로 컨텍스트 격리하기

긴 작업의 두 번째 적은 컨텍스트 윈도 폭발이다. 검색 결과 100건을 메인 컨텍스트에 쌓으면 토큰이 빠르게 소진된다. subagent가 이걸 풀어준다.

subagent.py · Python

research_subagent = {
    "name": "research-agent",
    "description": "특정 주제 하나를 깊게 조사한다.",
    "prompt": "전달받은 주제를 검색하고 요약만 메인에 돌려준다.",
    "tools": ["search"],
}

agent = create_deep_agent(
    tools=[search],
    system_prompt="필요하면 research-agent에 위임해라.",
    subagents=[research_subagent],
)

이렇게 등록하면 메인 에이전트가 task 도구로 subagent를 호출한다. subagent의 긴 컨텍스트는 격리되고, 메인은 결과 요약만 받는다. 직접 토큰 사용량을 비교해 보니 컨텍스트 절약 효과가 30~50% 정도 나왔다.

5. DeepAgents vs LangGraph vs CrewAI

선택 기준이 헷갈리는 분들을 위해 정리.

항목	DeepAgents	LangGraph 직접	CrewAI
출발점	한 줄 함수 호출	노드·엣지 직접 정의	역할 기반 Crew 구성
학습 곡선	낮음	중간~높음	낮음
장기 작업 적합도	높음(빌트인 todos·FS)	가장 유연	중간
커스터마이즈	중간	가장 자유	중간
추천 시나리오	리서치·코딩 보조	복잡한 워크플로	협업형 멀티에이전트

DeepAgents가 모든 경우에 정답은 아니다. 결제 승인 같은 결정론적 워크플로는 LangGraph로 직접 짜는 게 낫다. 반대로 "주제 주면 보고서 써와" 같은 자유도 높은 작업은 DeepAgents가 압도적으로 편하다.

6. 실전 팁과 호환성

스트리밍은 그냥 작동한다. agent.stream()을 호출하면 LangGraph 스트리밍을 그대로 받는다. UI에 토큰별로 흘려보내기 좋다.

체크포인터를 붙이면 작업 중단 후 재개도 된다. create_deep_agent(..., checkpointer=MemorySaver()) 식으로 넘기면 LangGraph의 휴먼인더루프 패턴이 그대로 적용된다.

📘 알아두기

• 스트리밍 · 체크포인팅 · 메모리는 LangGraph 기능을 그대로 상속한다.
• Tavily · Serper · Exa 같은 외부 검색 도구를 그대로 꽂을 수 있다.
• Studio UI(LangGraph Studio)에서 시각적으로 디버그 가능.

⚠️ 단점과 주의할 점

• 현재 라이선스는 MIT지만 v0.x 단계라 API가 종종 바뀐다. 프로덕션 투입 전 버전 핀 고정 필수.
• 무료·소형 모델만으로는 만족스러운 결과가 안 나온다. Sonnet 4.5나 GPT-4 클래스가 사실상 필요해 운영비가 따라온다.
• 가상 FS는 LangGraph 상태에 들어 있어 영속화하려면 직접 디스크에 dump 하는 코드를 짜야 한다.
• 결정론적 비즈니스 로직(승인·결제 등)에는 부적합 — 자유도 높은 리서치·코딩 보조 쪽이 본업.

✅ 핵심 정리

• DeepAgents = LangGraph + Claude Code 패턴(시스템 프롬프트·계획·서브에이전트·가상 FS)을 라이브러리화.
• create_deep_agent(tools, instructions, subagents, model) 한 줄로 시작 가능.
• 빌트인 도구 4종과 가상 FS가 30분 이상 장기 작업의 컨텍스트 폭발을 막는다.
• 자유도 높은 리서치·코딩 보조에 강하고, 결정론 워크플로엔 LangGraph 직접 작성이 낫다.

🚀 지금 바로 할 일

1. 가상환경 만들고 pip install deepagents 실행.
2. 위 researcher.py 코드를 그대로 복붙해서 검색 도구만 Tavily로 교체.
3. 토큰 비용 안전장치로 도구 호출 횟수 제한을 걸어 두고 첫 실행.

💬 의견

이전에 LangGraph로 에이전트를 직접 짜본 경험이 있다면 DeepAgents의 추상화가 충분하다고 느꼈는지 댓글로 공유 부탁드립니다.

참고 자료

• LangChain DeepAgents GitHub
• LangGraph 공식 문서
• Anthropic Claude Sonnet 4.5 모델 카드

---

작성자: AI·기술 도구를 직접 설치하고 토큰 비용을 실측해 정리하는 블로그 운영자. LangChain·LangGraph 기반 에이전트를 여러 차례 프로덕션에 투입한 경험을 바탕으로 작성.