Deep Agents, Claude Code를 오픈소스로 재현한 LangChain의 에이전트 하네스

2025년 12월, LangChain의 창업자 Harrison Chase는 블로그에 “Deep Agents”라는 글을 올렸다¹. Claude Code가 단순한 코딩 도구를 넘어 범용 에이전트로 쓰이는 현상을 관찰한 뒤, 그 핵심 구조를 추출해 오픈소스로 만들겠다는 선언이었다. 그로부터 3개월, Deep Agents는 GitHub 스타 10,200개를 넘기며 LangChain 생태계의 새로운 축으로 자리잡았다.

”깊은” 에이전트란 무엇인가

LLM에 도구를 붙여 루프를 돌리는 것은 에이전트의 가장 단순한 형태다. 문제는 이 방식이 복잡한 작업 앞에서 금방 한계에 부딪힌다는 점이었다. Chase는 이를 “shallow agent”라 불렀다. 반면 Claude Code, Deep Research, Manus 같은 서비스는 장시간에 걸쳐 복잡한 작업을 수행했다. 이들의 공통점은 네 가지였다.

1. 상세한 시스템 프롬프트 — Claude Code의 시스템 프롬프트는 수천 줄에 달하며, 도구 사용법과 상황별 행동 지침을 포함한다
2. 계획 도구 — 할 일 목록(Todo list)을 통해 작업을 분해하고 추적한다
3. 서브 에이전트 — 개별 작업을 위임할 수 있는 하위 에이전트를 생성한다
4. 파일 시스템 — 작업 결과를 저장하고, 메모를 남기고, 에이전트 간 협업 공간으로 활용한다

Deep Agents는 이 네 가지를 하나의 패키지로 묶은 것이다.

[!KEY] Deep Agents의 핵심은 “LLM + 도구 루프”라는 단순한 구조에 계획, 파일 시스템, 서브 에이전트, 정교한 프롬프트를 결합해 장기 작업 수행 능력을 확보한 것이다.

아키텍처: LangGraph 위에 세운 에이전트

Deep Agents를 이해하려면 LangChain 생태계의 계층 구조를 먼저 파악해야 한다.

graph TD
    A[LangGraph<br/>에이전트 런타임] --> B[LangChain<br/>에이전트 추상화]
    B --> C[Deep Agents<br/>에이전트 하네스]
    C --> D[Deep Agents CLI<br/>터미널 코딩 에이전트]
    A --> E[LangSmith<br/>관측·디버깅]
    C --> F[사용자 커스텀 에이전트]

LangGraph는 LangChain이 만든 에이전트 오케스트레이션 프레임워크다². 상태 기반 그래프로 에이전트의 실행 흐름을 정의하며, 스트리밍, 체크포인팅, 영속성 같은 프로덕션 기능을 제공한다. Klarna, Replit, Elastic 등이 실제 서비스에 사용하고 있다.

Deep Agents의 create_deep_agent() 함수는 컴파일된 LangGraph 그래프를 반환한다. 따라서 LangGraph의 모든 기능 — 스트리밍, Studio 연동, 체크포인터 — 을 그대로 사용할 수 있다. 이는 단순한 래퍼가 아니라 LangGraph 네이티브 애플리케이션이라는 뜻이다.

내장 도구 일람

Deep Agents는 다섯 가지 범주의 도구를 기본 제공한다.

흥미로운 점은 write_todos 도구다. Claude Code의 Todo list 도구와 마찬가지로, 이 도구는 실제로 아무 작업도 수행하지 않는다. LLM이 도구를 호출하는 행위 자체가 “지금 무엇을 해야 하는지” 정리하는 효과를 낳는다. 일종의 컨텍스트 엔지니어링 전략이다.

서브 에이전트 역시 주목할 만하다. 메인 에이전트가 복잡한 리서치를 수행할 때, 개별 주제를 담당하는 서브 에이전트를 생성해 병렬로 작업할 수 있다. 각 서브 에이전트는 독립된 컨텍스트 윈도우를 가지므로, 메인 에이전트의 컨텍스트가 오염되지 않는다.

사용법: 세 줄이면 충분하다

from deepagents import create_deep_agent

agent = create_deep_agent()
result = agent.invoke({
    "messages": [{"role": "user", "content": "LangGraph에 대해 조사하고 요약해줘"}]
})

모델 교체, 커스텀 도구 추가, 시스템 프롬프트 수정도 간단하다.

from langchain.chat_models import init_chat_model

agent = create_deep_agent(
    model=init_chat_model("openai:gpt-4o"),
    tools=[my_custom_tool],
    system_prompt="너는 리서치 어시스턴트야.",
)

MCP(Model Context Protocol) 도구는 langchain-mcp-adapters를 통해 연결할 수 있다. MCP 서버를 운영하고 있다면 별도 코드 없이 기존 도구를 Deep Agents에 바로 붙일 수 있다는 뜻이다.

Deep Agents CLI: 터미널 코딩 에이전트

SDK만으로도 충분하지만, LangChain은 한 발 더 나아가 CLI 버전을 제공한다. Claude Code나 Codex CLI처럼 터미널에서 바로 사용하는 코딩 에이전트다.

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

CLI의 주요 기능은 다음과 같다.

• 웹 검색 — Tavily API를 통한 실시간 웹 검색
• HTTP 요청 — 외부 API 호출 및 데이터 수집
• 영속 메모리 — ~/.deepagents/<agent_name>/memories/ 경로에 마크다운 파일로 기억을 저장한다. 프로젝트 컨벤션, 코딩 스타일, 선호도를 세션 간에 유지한다
• Human-in-the-loop — 민감한 도구 호출 시 사용자 승인을 요구한다
• 스킬 시스템 — 커스텀 전문 지식과 지침을 스킬 디렉터리에 저장해 에이전트 역량을 확장한다
• 컨텍스트 압축 — 긴 세션에서 이전 대화를 요약하고 원본을 백엔드에 오프로드해 컨텍스트 윈도우를 확보한다
• MCP 도구 — 설정 파일을 통해 외부 MCP 서버의 도구를 자동 로드한다
• LangSmith 트레이싱 — 에이전트의 도구 호출과 판단 과정을 LangSmith에서 추적할 수 있다

영속 메모리 방식이 특히 인상적이다. 에이전트는 “memory-first protocol”을 따른다. 작업을 시작하기 전에 기존 메모리를 검색하고, 실행 중 불확실한 상황에서 메모리를 참조하며, 새로운 정보를 자동으로 저장한다. Claude Code의 CLAUDE.md와 유사하지만, 에이전트가 스스로 메모리를 관리한다는 점에서 더 자동화되어 있다.

경쟁 구도: Claude Agent SDK, Codex SDK와의 비교

Deep Agents는 혼자 존재하지 않는다. Anthropic의 Claude Agent SDK와 OpenAI의 Codex SDK가 같은 영역에서 경쟁한다³.

Deep Agents의 가장 큰 차별점은 모델 비종속성이다. Claude Agent SDK는 Claude 모델에, Codex SDK는 OpenAI 모델에 묶여 있다. Deep Agents는 Anthropic, OpenAI, 오픈소스 모델 어디든 연결할 수 있다. 프로덕션에서 비용이나 성능에 따라 모델을 교체해야 하는 상황이라면 이 유연성이 결정적인 장점이 된다.

반면 Claude Agent SDK는 Claude 모델과의 깊은 통합이 강점이다. 권한 시스템, hooks를 통한 행동 제어 등 보안 측면에서 더 정교한 설정이 가능하다. Codex SDK는 데스크톱 앱, IDE 확장, 클라우드 인터페이스까지 갖춘 완성형 제품에 가깝다.

[!KEY] 모델을 자유롭게 교체하고 싶다면 Deep Agents, 특정 모델과의 깊은 통합이 필요하면 Claude Agent SDK나 Codex SDK가 적합하다.

보안 모델: “LLM을 신뢰하라”

Deep Agents의 보안 철학은 명확하다. “Trust the LLM” — 에이전트가 도구가 허용하는 모든 것을 할 수 있도록 두되, 경계는 도구와 샌드박스 레벨에서 설정한다는 것이다.

이는 모델이 스스로 행동을 자제할 것을 기대하지 않겠다는 현실적인 판단이다. 프롬프트 인젝션이나 탈옥 시도가 성공하더라도, 도구 자체의 권한이 제한되어 있으면 피해를 최소화할 수 있다. CLI의 human-in-the-loop 승인 시스템도 이 맥락에서 작동한다. 셸 명령어 실행 같은 고위험 동작에 대해 사용자의 명시적 승인을 요구한다.

다만 이 모델에는 한계도 있다. 도구 권한 설정이 세밀하지 않으면 의도치 않은 파일 삭제나 민감 정보 노출이 발생할 수 있다. Claude Agent SDK의 다층 권한 시스템(모드, 규칙, hooks)에 비하면 아직 거친 편이다.

한계와 현실적 고려사항

커뮤니티 반응을 종합하면 몇 가지 한계가 드러난다.

프로덕션 배포의 복잡성 — Reddit의 한 스레드에서 지적된 바와 같이, 프로덕션 환경에서 인증 처리나 성능 최적화를 위해 LangSmith 라이선스가 사실상 필요하다는 의견이 있었다⁴. 오픈소스이지만 프로덕션 수준의 관측성과 배포를 원하면 유료 인프라에 의존하게 되는 구조다.

용도의 모호함 — LangChain, LangGraph, Deep Agents 세 가지 중 무엇을 써야 하는지 혼란스러워하는 사용자가 적지 않았다. 공식 가이드라인은 명확하다 — LangChain은 밑바닥부터 구축할 때, LangGraph는 워크플로우와 에이전트를 조합할 때, Deep Agents는 즉시 사용 가능한 자율 에이전트가 필요할 때 — 이지만, 실제로는 경계가 흐릿하다.

프롬프트 의존성 — Deep Agents의 성능은 내장 시스템 프롬프트의 품질에 크게 좌우된다. Claude Code가 수천 줄의 정교한 프롬프트로 성능을 끌어올린 것처럼, Deep Agents도 프롬프트 엔지니어링에 상당한 투자가 필요하다. 기본 프롬프트가 모든 사용 사례를 커버하지는 못한다.

LangChain 생태계에서의 위치

Deep Agents는 LangChain 생태계의 최상위 레이어에 해당한다. LangGraph가 저수준 오케스트레이션을 담당하고, LangChain이 에이전트 추상화를 제공하며, Deep Agents가 그 위에서 즉시 사용 가능한 완성형 에이전트를 구현한다.

이 구조는 의도적이다. LangChain 팀은 개발자의 필요에 따라 추상화 수준을 선택할 수 있도록 설계했다. 최대한의 제어가 필요하면 LangGraph를, 적절한 추상화가 필요하면 LangChain을, 바로 쓸 수 있는 에이전트가 필요하면 Deep Agents를 선택하면 된다. LangSmith는 이 모든 레이어에 걸쳐 관측성을 제공한다.

이전 에이전트 플랫폼 전쟁 분석에서 살펴본 것처럼, 에이전트 프레임워크 시장은 빠르게 분화하고 있다. Anthropic은 Claude Code와 Agent SDK로 자사 모델 중심의 통합 경험을, OpenAI는 Codex로 엔드투엔드 코딩 솔루션을, LangChain은 Deep Agents로 모델 비종속적인 오픈 플랫폼을 내세운다.

결론: 누구를 위한 도구인가

Deep Agents는 두 가지 니즈를 동시에 충족한다. 첫째, 에이전트를 빠르게 프로토타이핑하고 싶은 개발자에게 pip install deepagents 한 줄로 작동하는 에이전트를 제공한다. 둘째, 프로덕션 에이전트를 구축하려는 팀에게 모델 교체, 커스텀 도구, LangGraph 기반 배포라는 확장 경로를 제공한다.

Claude Code에서 영감받았다는 점은 솔직한 고백이자 전략적 포지셔닝이다. Claude Code의 아키텍처가 왜 효과적인지를 분석하고, 그 패턴을 모든 LLM에서 사용할 수 있도록 일반화한 것이 Deep Agents의 본질이다. 특정 모델에 종속되지 않으면서도 “깊은” 에이전트를 구현할 수 있다는 것, 그것이 Deep Agents가 10,000개 이상의 스타를 받은 이유일 것이다.