터미널 창의 검은 배경 위로 하얀 텍스트가 쉼 없이 쏟아져 내린다. 수십 번의 루프를 돌며 도구를 호출하던 기존 에이전트가 결국 Maximum iterations reached라는 붉은 에러 메시지를 띄우며 멈춰 섰을 때, 묘한 답답함이 밀려왔다. 단순한 반복만으로는 결코 도달할 수 없는, 더 깊은 수준의 계획과 실행이 필요하다는 신호였다.
얕은 에이전트의 한계와 딥 에이전트의 등장
우리가 흔히 접해온 LLM 기반 에이전트들은 대부분 ‘얕은(shallow)’ 구조를 가지고 있다. LLM이 도구를 선택하고, 실행 결과를 받아 다시 다음 도구를 선택하는 단순한 루프 방식이다. 짧은 작업에서는 효율적이지만, 호흡이 긴 복잡한 과업을 맡기면 금세 길을 잃는다. 계획을 세우지 않은 채 눈앞의 단계만 처리하다 보니, 전체 맥락을 놓치고 무한 루프에 빠지거나 엉뚱한 결론으로 치닫는 경우가 허다했다.
LangChain이 제시하는 Deep Agents는 바로 이 지점에서 출발한다. 이는 단순한 라이브러리를 넘어 일종의 ‘에이전트 하네스(Agent Harness)’ 역할을 한다. LangGraph를 기반으로 구축된 이 시스템은 더 긴 시간 지평(time horizon)을 두고 계획을 세우며, 스스로 컨텍스트를 관리하고, 필요에 따라 하위 에이전트(sub-agents)에게 업무를 위임하는 능력을 갖췄다. 이제 에이전트는 단순히 도구를 호출하는 기계가 아니라, 프로젝트 매니저처럼 전체 공정을 설계하고 관리하는 존재가 된 셈이다.
딥 에이전트의 핵심 메커니즘: 계획, 메모리, 그리고 파일시스템
Deep Agents가 기존 방식과 차별화되는 가장 큰 특징은 공유 작업 공간으로서의 파일시스템 활용이다. 기존 에이전트들이 짧은 대화 기록(Chat History)에만 의존했다면, 딥 에이전트는 로컬 파일시스템을 메모리처럼 사용하여 중간 결과물을 저장하고 다시 읽어 들인다. 이는 마치 개발자가 코드를 짜다가 임시 파일을 만들고, 이를 바탕으로 다음 단계의 분석을 진행하는 과정과 매우 흡사하다.
또한, ‘신뢰 기반 모델(Trust the LLM)’을 채택하고 있다는 점이 흥미롭다. 모델이 도구를 통해 할 수 있는 모든 일을 허용하되, 제약 사항은 모델의 프롬프트가 아니라 툴/샌드박스 레벨에서 강제한다. 이는 모델이 억지로 규칙을 지키게 만들어 성능을 깎아먹는 대신, 안전한 환경(Sandbox)을 제공하고 그 안에서 최대한의 자율성을 부여해 복잡한 문제 해결 능력을 극대화하는 전략이다.
실제로 Deep Agents 구축해보기
Deep Agents를 프로젝트에 도입하려면 먼저 관련 라이브러리를 설치하고 환경을 설정해야 한다. LangGraph의 생태계 위에 구축되었으므로, 그래프 기반의 상태 관리에 익숙하다면 훨씬 빠르게 적응할 수 있다. 아래는 기본적인 설치 및 실행 흐름이다.
- 먼저
pip를 통해deepagents라이브러리와 LangChain 관련 패키지를 설치한다. - LLM API 키(OpenAI, Anthropic 등)를 환경 변수로 설정하여 인증을 완료한다.
- 에이전트가 사용할 도구(Tools)와 파일시스템 접근 권한이 부여된 샌드박스 경로를 지정한다.
- Deep Agent 하네스를 통해 계획-실행-검토 루프를 구성하고 실행한다.
# 1. 라이브러리 설치
pip install langchain-ai deepagents langgraph
# 2. 기본 실행 구조 예시 (Python)
from deepagents import DeepAgent
from langchain_openai import ChatOpenAI
# LLM 설정 및 에이전트 초기화
llm = ChatOpenAI(model="gpt-4o")
agent = DeepAgent(
llm=llm,
workspace_dir="./agent_workspace", # 공유 작업 공간 경로
tools=["python_repl", "file_writer", "web_search"]
)
# 복잡한 과업 부여
result = agent.run("최근 3년간의 AI 트렌드 리포트를 분석해서 요약본을 pdf로 저장하고, 핵심 인사이트를 메일로 보내줘")
print(result)실행 과정에서 가장 흔히 발생하는 문제는 PermissionError다. 에이전트가 ./agent_workspace 경로에 파일을 쓰려고 할 때 권한이 없으면 프로세스가 중단된다. 이 경우 chmod -R 755 ./agent_workspace 명령어로 쓰기 권한을 명확히 부여하거나, 도커(Docker) 컨테이너 내부의 격리된 볼륨을 마운트하여 사용하는 것이 가장 안전하고 확실한 해결책이다.
효율적인 워크플로우를 위한 설정 팁
딥 에이전트를 사용할 때 단순히 run() 메서드만 호출하기보다, 하위 에이전트의 역할을 세분화하는 것이 성능 향상에 도움이 된다. 예를 들어, ‘데이터 수집 전담 에이전트’와 ‘분석 및 리포팅 전담 에이전트’를 나누어 배치하고, 이들이 파일시스템의 특정 경로(예: /tmp/raw_data $\rightarrow$ /tmp/analyzed_data)를 통해 데이터를 주고받게 설정하는 식이다.
또한, max_iterations 옵션을 너무 낮게 잡으면 복잡한 추론 과정에서 흐름이 끊길 수 있다. 딥 에이전트는 계획을 수정하고 다시 시도하는 과정이 필수적이므로, 단순 챗봇보다는 훨씬 넉넉한 반복 횟수를 설정하는 것이 좋다. 만약 에이전트가 특정 단계에서 계속 헤맨다면, system_prompt에서 도구 사용의 우선순위를 명시적으로 가이드해 주는 것만으로도 성공률이 비약적으로 상승하는 것을 경험할 수 있다.
앞으로의 실험: 더 깊은 자율성을 향해
결국 Deep Agents가 주는 가치는 ‘개발자가 일일이 짜놓은 워크플로우(Hard-coded loop)’에서 벗어나 ‘LLM이 스스로 판단하는 워크플로우’로 옮겨갈 수 있게 해준다는 점에 있다. 이제 우리는 “A 다음에 B를 해”라고 명령하는 대신, “결과적으로 C가 나오게끔 네가 계획을 세워봐”라고 말할 수 있게 되었다.
이번에 Deep Agents를 살펴보며 느낀 점은, AI 에이전트의 성능은 모델의 파라미터 수만큼이나 그 모델이 움직일 수 있는 ‘구조적 환경(Harness)’이 중요하다는 사실이다. 다음에는 파일시스템 외에 외부 데이터베이스나 API 상태를 직접 관찰하고 수정하는 더 공격적인 툴셋을 결합해 보려 한다. 과연 에이전트가 어디까지 스스로 계획하고 수정하며 정답에 다가갈 수 있을까? 여러분의 프로젝트에서는 어떤 복잡한 과업을 에이전트에게 맡겨보고 싶으신가?