GitHub 추천: langchain-ai/deepagents로 에이전트 하네스 빠르게 실험하기
LangChain 기반 장기 실행 에이전트를 직접 만들기 전 확인할 저장소
GitHub 추천: langchain-ai/deepagents로 에이전트 하네스 빠르게 실험하기
deepagents는 LangChain 생태계의 agent harness 저장소로, 장기 실행 에이전트 구조를 직접 만들기 전에 기준 구현처럼 검토할 수 있습니다. 2026년 5월 28일 기준 GitHub 활동과 개발자 proof는 강하지만, 첫 도입은 작은 SDK 실험과 sandbox 전제에서 시작하는 편이 안전합니다.
AI 에이전트를 만들다 보면 단순 tool calling 다음 단계에서 손이 멈춥니다. 긴 작업을 이어가고, 파일을 다루고, 하위 에이전트를 나누고, 중간 상태를 복구하는 구조를 어디까지 직접 만들어야 하는지 애매해지기 때문입니다.
`langchain-ai deepagents GitHub agent harness`는 바로 그 지점에 놓인 저장소입니다. LangChain/LangGraph를 이미 쓰고 있거나 검토 중인 개발자라면, 에이전트 하네스를 백지에서 설계하기 전에 deepagents의 기본 구조를 먼저 만져볼 만합니다.
2026년 5월 28일 확인 기준 GitHub API에서는 같은 날 push가 확인됐고, 약 23.4k stars와 3.3k forks 수준의 관심도도 보였습니다. 다만 제가 보기에는 이 숫자는 '바로 운영에 넣어도 된다'는 보증이 아니라, 지금 비교 후보에 올릴 만큼 개발자 신호가 있다는 뜻에 가깝습니다.
저장소 소개만 읽고 끝내면 실제 판단에 별 도움이 없습니다. 그래서 기준을 사용 판단 쪽에 둡니다. 무엇을 해결하는지, Deep Agents 설치는 어디서 시작할지, LangGraph와의 관계는 무엇인지, 실무 도입 전에 어떤 권한과 비용을 먼저 막아야 하는지가 이 글의 순서입니다.
deepagents는 무엇이고 LangGraph와 어떤 관계인가?
Deep Agents는 LangGraph를 대체하는 도구가 아니라 LangGraph 런타임 위에 planning, filesystem, subagents, context management를 묶은 더 opinionated한 harness입니다. 단순 tool-calling agent보다 긴 작업을 빠르게 실험하려는 개발자에게 맞습니다.
공식 문서의 설명을 기준으로 보면 레이어가 먼저 보입니다. LangGraph는 durable execution, streaming, human-in-the-loop 같은 실행 기반을 맡고, deepagents는 그 위에서 장기 작업형 에이전트에 필요한 관례를 묶습니다.
LangChain의 `create_agent`가 가벼운 에이전트 시작점이라면, deepagents는 filesystem, subagents, context management, skills 같은 운영 모양을 더 많이 정해 둔 쪽에 가깝습니다. 그래서 `langchain-ai deepagents GitHub agent harness`를 볼 때는 '새 프레임워크로 갈아타는가'보다 'LangChain/LangGraph 위에서 반복 구현하던 하네스를 빌려 쓸 수 있는가'로 보는 편이 정확합니다.
한국 사용자 입장에서는 이 구분이 실용적입니다. 사내 PoC나 개인 자동화에서 처음부터 장기 실행 구조를 모두 직접 만들면, 실제 모델 성능보다 상태 관리와 도구 권한 설계에 시간을 더 쓰게 됩니다. deepagents는 그 시행착오를 줄이는 기준점이 될 수 있습니다.
2026년 5월 28일 기준 확인한 활동 타임라인
2026년 5월 말 기준 deepagents는 SDK, CLI, coding-agent 패키지가 모두 움직이고 있으며 같은 날 push 신호도 확인됐습니다. star와 fork 수는 계속 변하므로 확인 시점 기준의 근사치로 읽어야 합니다.
저장소 추천 글에서 활동 신호는 과장하기 쉽습니다. 여기서는 '인기'보다 '현재 검토할 만한 살아 있는 프로젝트인가'에 초점을 둡니다.
| 확인 항목 | 의미 |
|---|---|
| 2025년 7월 27일 저장소 생성 | 공개 저장소 이력이 2025년에 시작된 것으로 확인됩니다. |
| 2026년 5월 26일 deepagents 0.6.4 release | SDK 쪽 변경과 수정이 최근까지 이어졌습니다. |
| 2026년 5월 27일 deepagents-code 0.1.6 release | 터미널 코딩 에이전트 패키지도 별도 흐름으로 움직입니다. |
| 2026년 5월 28일 GitHub push 확인 | 오늘의 GitHub 추천 후보로 볼 만한 freshness가 있습니다. |
PyPI 기준 `deepagents` 패키지는 Python 3.11 이상 4.0 미만을 요구하고, Development Status는 Beta로 표시됩니다. 이 한 줄은 꽤 중요합니다. 설치가 가능하고 활발하다는 말과, 모든 조직의 프로덕션 환경에서 검증됐다는 말은 다릅니다.
실제로 확인할 부분은 버전 숫자보다 패키지의 역할 분리입니다. SDK는 `deepagents`, 배포 관련 CLI는 `deepagents-cli`, 터미널 코딩 에이전트는 `deepagents-code`/`dcode` 쪽으로 나뉩니다. 이 셋을 하나의 설치법으로 섞으면 첫 테스트부터 꼬일 수 있습니다.
도입 시뮬레이션: 설치, 첫 테스트, 운영 모델까지
첫 실험은 Python 3.11 이상 환경에서 SDK를 설치하고 민감하지 않은 demo tool 하나로 `create_deep_agent`를 호출하는 순서가 적절합니다. 이후 `thread_id`, memory scope, sandbox, approval gate를 붙여 실제 운영 모델을 검증해야 합니다.
`langchain-ai deepagents GitHub agent harness`를 처음 보는 팀이라면 바로 사내 repo나 고객 데이터에 연결하지 않는 편이 낫습니다. 먼저 아주 작은 명령형 PoC로 agent loop, tool call, state persistence가 어떤 느낌인지 확인해야 합니다.
가장 작은 경로는 Python SDK입니다. 공식 quickstart 흐름은 `uv add deepagents`로 패키지를 추가하고, 코드에서는 `from deepagents import create_deep_agent`를 쓰는 쪽입니다. provider별 모델을 붙일 때는 문서에 나온 것처럼 `deepagents`와 `langchain-openai` 같은 provider 패키지를 함께 준비합니다.
첫 테스트는 민감하지 않은 로컬 샘플 폴더와 읽기 전용 도구 하나로 충분합니다. `examples/deep_research`나 `text-to-sql-agent`를 그대로 운영 데이터에 붙이지 말고, 더미 문서 3개 또는 샘플 SQLite 파일 1개를 대상으로 답변 품질과 tool 호출 로그를 보는 식이 낫습니다.
운영 검토는 설치보다 더 중요합니다. long-running agent라면 `thread_id`로 대화와 작업 단위를 분리하고, memory에는 어떤 사용자/세션 정보가 남는지 정해야 합니다. sandbox는 매 실행마다 어떻게 만들고 지울지, 실패한 작업은 어디서 재시도할지, LangSmith나 LangGraph 배포 로그로 어떤 trace를 남길지도 미리 정합니다.
> 제 판단으로는 deepagents의 첫 가치는 '완성된 앱'이 아니라, 장기 실행 에이전트 구조를 논의할 때 팀이 같은 샘플을 보며 이야기할 수 있게 해 주는 기준점입니다.
어떤 팀과 프로젝트에 맞나?
deepagents는 research agent, coding agent, documentation/wiki agent, text-to-SQL agent처럼 긴 컨텍스트와 파일 작업, subagent 위임이 필요한 PoC에 잘 맞습니다. 단순 챗봇이나 한두 개 tool call이면 LangChain `create_agent`가 더 가볍습니다.
실제 용도를 놓고 보면, 이미 LangChain 또는 LangGraph를 검토하고 있고 에이전트가 여러 단계를 이어 가야 하는 팀에 잘 맞습니다. 문서 리서치 자동화, 코드베이스 탐색, 내부 위키 초안 작성, SQL 질의 보조, MCP 문서 에이전트 같은 흐름이 여기에 들어갑니다.
반대로 단순 FAQ 챗봇, 고정된 API 호출 1~2개, stateless한 분류 작업이라면 deepagents는 무겁게 느껴질 수 있습니다. 이 경우에는 LangChain `create_agent`나 더 작은 함수 호출 구조가 유지보수에 유리합니다.
SDK, CLI, dcode도 목적을 나눠 봐야 합니다.
| 선택지 | 먼저 볼 상황 | 주의할 점 |
|---|---|---|
| `deepagents` SDK | 앱 안에 agent harness를 통합하고 싶을 때 | Python 3.11 이상과 provider 패키지, tool 권한을 함께 확인해야 합니다. |
| `deepagents-cli` | Deep Agents 배포 흐름을 실험할 때 | 현재 README 기준 배포 subcommand 중심으로 이해해야 합니다. |
| `deepagents-code` / `dcode` | 터미널에서 coding agent를 써 보고 싶을 때 | `/auth`, provider credential, optional Tavily key 같은 실행 전 준비가 필요합니다. |
한국 개발자에게 특히 맞는 사용처는 개인 자동화보다 팀 PoC입니다. 혼자 쓰는 도구는 단순한 스크립트가 더 빠를 때가 많지만, 팀에서는 에이전트의 memory, approval, trace, rollback 기준을 합의해야 합니다. deepagents는 그 논의를 코드 예제로 끌어내는 데 유용합니다.
왜 지금 GitHub 추천으로 볼 만한가?
장기 실행 AI 에이전트와 agent harness 검색 수요가 커지는 상황에서 deepagents는 LangChain/LangGraph 사용자에게 바로 비교할 수 있는 기준 구현을 제공합니다. stars와 forks는 발견 신호로 쓰되, 실제 채택 여부는 보안 경계와 비용, latency, eval 결과로 판단해야 합니다.
요즘 에이전트 논의는 '모델이 똑똑한가'에서 '작업을 오래 끌고 가도 망가지지 않는가'로 이동하고 있습니다. agent harness가 필요한 이유도 여기에 있습니다. 실행 이력, 도구 호출, 중간 산출물, 재시도, 사람이 승인해야 하는 단계가 한꺼번에 엮입니다.
`langchain-ai deepagents GitHub agent harness`가 오늘의 추천 후보가 되는 이유는 이 문제를 LangChain/LangGraph 생태계 안에서 비교적 직접적으로 다루기 때문입니다. GitHub topic에도 ai, deepagents, langchain, langgraph, python, typescript가 걸려 있고, Python 중심 저장소라는 점도 확인됩니다.
다만 star가 많다는 이유만으로 채택을 결정하면 위험합니다. 실제 PoC에서는 provider 비용, tool call latency, 실패한 thread 복구, memory 삭제 정책, eval 기준이 더 중요합니다. promptfoo 같은 LLM 평가 도구나 LangSmith trace를 함께 붙여서 '좋아 보이는 데모'와 '재현 가능한 성능'을 분리해야 합니다.
실무 도입 전에 반드시 확인할 리스크
Deep Agents가 agent 실행 구조를 제공하더라도 shell, filesystem, memory, external API 권한은 자동으로 안전해지지 않습니다. 실제 데이터와 연결하기 전 sandbox, approval, tracing, eval, rollback 기준을 먼저 정해야 합니다.
다만 여기서 조심할 점은 명확합니다. 에이전트 하네스가 있다고 해서 권한 경계가 자동으로 생기지는 않습니다. 특히 로컬 파일 접근, shell 실행, 외부 API 호출, 장기 memory는 각각 별도의 위험 표면입니다.
공식 threat model은 사용자가 model, tools, backend, checkpointer, store, memory, skills, subagents를 통제하는 구조를 전제로 합니다. LocalShellBackend가 기본값은 아니지만, shell 또는 host filesystem 접근을 켜는 순간 신뢰 경계를 직접 설계해야 합니다.
프로덕션에서는 다음 항목을 먼저 막아야 합니다.
- `LocalShellBackend`와 host filesystem 접근을 배포 에이전트에서 기본 옵션으로 두지 않기
- `thread_id`별 memory와 store에 남는 개인정보, 고객 데이터, 내부 문서 범위를 제한하기
- API key, Tavily key, model provider credential을 agent prompt나 파일시스템에 노출하지 않기
- tool call마다 approval gate가 필요한 작업과 자동 실행 가능한 작업을 분리하기
- LangSmith trace, eval, rollback 기준을 PoC 때부터 남기기
이 조건을 아직 정하지 못했다면 deepagents를 학습용 sandbox에서만 돌리는 편이 맞습니다. 특히 의료, 금융, 법무처럼 권한과 감사 로그가 중요한 조직은 '작동한다'보다 '감사 가능한가'를 먼저 봐야 합니다.
자주 묻는 질문
Q. deepagents는 LangGraph와 어떤 관계인가?
A. Deep Agents는 LangGraph를 대체하지 않습니다. LangGraph 런타임 위에서 장기 실행, streaming, human-in-the-loop 같은 기반을 활용하고, 그 위에 파일시스템, subagents, context management 같은 agent harness 관례를 더한 라이브러리로 보는 편이 정확합니다.
Q. Deep Agents 설치와 첫 테스트는 어떻게 시작하면 되나?
A. SDK 기준으로는 Python 3.11 이상 환경에서 `uv add deepagents`로 시작하고, 코드에서는 `from deepagents import create_deep_agent`를 확인하는 것이 가장 작습니다. 첫 테스트는 민감하지 않은 더미 문서나 샘플 DB를 대상으로 tool call과 trace가 남는지 보는 방식이 안전합니다.
Q. `deepagents`, `deepagents-cli`, `deepagents-code`는 어떻게 다르게 봐야 하나?
A. `deepagents`는 앱에 통합하는 SDK, `deepagents-cli`는 배포 subcommands 중심의 CLI, `deepagents-code`/`dcode`는 터미널 코딩 에이전트 흐름입니다. 설치 명령과 인증 흐름이 다르므로 하나의 도구처럼 섞어 이해하면 안 됩니다.
Q. 실무 도입 전에 `thread_id`, memory, sandbox를 왜 먼저 정해야 하나?
A. 장기 실행 에이전트는 한 번의 답변보다 작업 이력과 상태 복구가 중요합니다. `thread_id`는 작업 단위를 나누고, memory scope는 저장되는 정보를 제한하며, sandbox는 파일과 shell 권한의 피해 범위를 줄입니다.
Q. 로컬 파일 접근이나 shell 실행은 언제 피해야 하나?
A. 고객 데이터, 내부 repo, 운영 credential, 배포 서버 파일시스템이 연결된 환경에서는 기본적으로 피해야 합니다. 공식 threat model도 shell과 filesystem 접근을 명시적 신뢰 경계로 보므로, sandbox와 approval 없이 켜는 방식은 실무 PoC에도 맞지 않습니다.
Q. 어떤 프로젝트에서는 deepagents를 쓰지 않는 편이 나은가?
A. 단순 FAQ, 고정 API 호출 1~2개, 상태가 거의 없는 분류 작업은 deepagents보다 작은 LangChain `create_agent`나 일반 함수 호출 구조가 낫습니다. 권한 설계, trace, eval을 운영할 여력이 없는 팀도 일단 학습용 sandbox에 머무르는 편이 안전합니다.
함께 읽으면 좋은 글
- Gemini CLI GitHub 추천: 터미널에서 Gemini 에이전트 쓰는 법 — GITHUB 추천
- open-multi-agent 추천: 목표를 작업 DAG로 나누는 TypeScript 멀티 에이전트 프레임워크 — GITHUB 추천
- promptfoo 추천: LLM 앱과 RAG를 배포 전 자동 평가하는 오픈소스 도구 — GITHUB 추천
참조 링크
- langchain-ai/deepagents — 원본 저장소, README, quickstart, security 설명 확인
- GitHub API: langchain-ai/deepagents repository metadata — 2026년 5월 28일 기준 push, stars, forks, topics, language, license 확인
- Deep Agents overview — LangGraph runtime 관계와 Deep Agents 개념 확인
- Deep Agents releases — 최근 SDK, CLI, deepagents-code release 흐름 확인
- deepagents on PyPI — 패키지 버전, Python 요구사항, Beta classifier 확인
- Deep Agents Code overview — dcode 설치, 인증, one-shot 실행, Tavily key 전제 확인
- Deep Agents CLI deployment README — deepagents-cli와 deepagents-code 역할 분리 확인
- Going to production — thread_id, memory, sandbox, guardrails, deployment 운영 전제 확인
- Deep Agents SDK threat model — LocalShellBackend, filesystem, tool 권한 경계 확인