Jeongsk

READMD

9 min read

Project: Deep Agents with LangGraph

소개

LangChain Academy의 LangGraph를 활용한 딥 에이전트 과정에 오신 것을 환영합니다!

이제 장기간 실행되며 고도로 능숙한 에이전트의 성공 사례가 여러 건 존재합니다. 우리는 이들을 ‘딥 에이전트’라고 명명했는데, 이는 이전 세대 에이전트들과 뚜렷이 차별화되기 때문입니다. 본 과정에서는 그 차별점을 학습하고 여러분만의 딥 에이전트를 구축하게 될 것입니다.

LangChain에서는 사용자가 장기간 실행 에이전트를 빠르고 간편하게 구축할 수 있도록 단순하면서도 구성 가능한 딥 에이전트를 개발했습니다.

본 과정에서는 딥 에이전트를 활용해 심층 연구 에이전트를 구축합니다. 총 7개의 모듈로 구성되어 있습니다.

설정

필수 조건

Python 3.11 이상

Python 3.11 이상을 사용 중인지 확인하십시오. 이 버전은 LangGraph와의 최적의 호환성을 위해 필요합니다.

다른 버전을 사용 중이라면, uv를 사용하여 지정된 Python 버전으로 가상 환경을 설정하는 방법이 있습니다.

uv venv --python 3.11

uv 패키지 관리자

curl -LsSf https://astral.sh/uv/install.sh | sh
# 새 uv 버전을 사용하도록 PATH 경로를 업데이트하십시오.
export PATH="/Users/$USER/.local/bin:$PATH"

설치

깃허브에 위치한 노트북 세트를 사용할 예정입니다. 각 모듈에는 해당 노트북으로 연결되는 링크도 포함될 것입니다.

저장소를 복제

git clone https://github.com/langchain-ai/deep-agents-from-scratch.git
cd deep-agents-from-scratch

패키지와 종속성을 설치

다음 명령어는 가상 환경을 자동으로 생성하고 관리합니다.

uv sync

LangSmith 가입하기

LangSmith 설정 페이지로 이동하여 LangSmith에서 API 키를 생성하세요: https://docs.langchain.com/langsmith/create-account-api-key

LLM API 키 설정

웹 검색용 Tavily API

Tavily Search API는 효율적이고 신속하며 지속적인 검색 결과를 목표로 하는 대규모 언어 모델(LLM)에 최적화된 검색 엔진입니다. Tavily API 키는 여기에서 발급할 수 있습니다. 가입이 간편하며 넉넉한 무료 이용권을 제공합니다. 외부 검색 기능을 갖춘 연구 에이전트 구축에 Tavily API를 활용합니다.

환경 변수 설정

프로젝트 루트 디렉터리에 .env 파일 생성합니다.

# example.env 파일을 .env로 복사합니다.
cp example.env  .env

.env 파일을 편집합니다.

# 외부 검색 기능이 있는 연구 에이전트에 필수
TAVILY_API_KEY=your_tavily_api_key_here

# 모델 사용 시 필수 사항
ANTHROPIC_API_KEY=your_anthropic_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

# 선택 사항: 평가 및 추적을 위해
LANGSMITH_API_KEY=your_langsmith_api_key_here
LANGSMITH_TRACING=true
LANGSMITH_PROJECT=deep-agents-from-scratch
# EU 인스턴스에 접속 중이라면:
LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com

노트북 실행하기

Jupyter가 설치되어 있지 않다면, 여기의 설치 안내를 따르세요.

Jupyter 노트북을 직접 실행할 수 있습니다:

uv run jupyter notebook

또는, 원하는 경우 가상 환경을 활성화하십시오:

source .venv/bin/activate
 
On windows:
.venv\Scripts\activate jupyter notebook

배경

딥 리서치(Deep Research)는 코딩과 함께 최초의 주요 에이전트 활용 사례 중 하나로 부상했습니다.

현재는 다양한 작업에 활용 가능한 범용 에이전트가 등장하고 있습니다. 예를 들어, Manus는 장기적 과제 수행으로 상당한 주목과 인기를 얻었습니다. 평균 Manus 작업은 약 50개의 도구 호출을 사용합니다!

두 번째 사례로, Claude Code는 코딩을 넘어선 다양한 작업에 일반적으로 활용되고 있습니다.

이러한 인기 있는 “심층” 에이전트 전반에 걸친 컨텍스트 엔지니어링 패턴을 면밀히 검토하면 몇 가지 공통적인 접근 방식이 드러납니다:

  • 작업 계획 수립(예: 할 일 목록), 종종 암송과 결합
  • 파일 시스템으로의 컨텍스트 오프로딩
  • 하위 에이전트 위임을 통한 컨텍스트 격리

본 과정에서는 LangGraph를 활용해 이러한 패턴을 처음부터 구현하는 방법을 보여줍니다.

구성

튜토리얼 개요

이 저장소에는 고급 AI 에이전트 구축을 가르치는 5개의 단계별 노트북이 포함되어 있습니다:

0_create_agent.ipynb - 에이전트 컴포넌트 생성

create_agent 컴포넌트 사용법을 배웁니다. 이 컴포넌트는:

  • 많은 에이전트의 기반이 되는 ReAct(추론-행동) 루프를 구현합니다
  • 사용하기 쉽고 빠르게 설정할 수 있습니다
  • Deep Agent의 핵심 구성 요소입니다

1_todo.ipynb - 작업 계획 기초

TODO 목록을 활용한 구조화된 작업 계획 구현법을 배웁니다. 이 노트북에서는 다음을 소개합니다:

  • 상태 관리(pending/in_progress/completed)를 통한 작업 추적
  • 진행 상황 모니터링 및 컨텍스트 관리
  • 복잡한 다단계 워크플로우 조직을 위한 write_todos() 도구
  • 집중력 유지 및 작업 이탈 방지 모범 사례

2_files.ipynb - 가상 파일 시스템

컨텍스트 오프로딩을 위한 에이전트 상태에 저장된 가상 파일 시스템 구현:

  • 파일 작업: Is(), read_file(), write_file()
  • 정보 지속성을 통한 컨텍스트 관리
  • 대화 전환 간 에이전트 “기억” 활성화
  • 상세 정보 파일 저장으로 토큰 사용량 감소

3_subagents.ipynb - 컨텍스트 격리

복잡한 워크플로우 처리를 위한 서브 에이전트 위임 마스터하기:

  • 집중된 도구 세트를 가진 전문화된 서브 에이전트 생성
  • 혼란 및 작업 간섭 방지 위한 컨텍스트 격리
  • task() 위임 도구 및 에이전트 레지스트리 패턴
  • 독립적인 연구 스트림을 위한 병렬 실행 기능

4_full_agent.ipynb - 완성형 연구 에이전트

모든 기법을 결합한 실전형 연구 에이전트:

  • TODO, 파일, 서브 에이전트 통합
  • 지능형 컨텍스트 오프로딩을 통한 실제 웹 검색
  • 콘텐츠 요약 및 전략적 사고 도구
  • 복잡한 연구 작업을 위한 완전한 워크플로

각 노트북은 이전 개념을 기반으로 구축되어, 실제 연구 및 분석 작업을 처리할 수 있는 정교한 에이전트 아키텍처로 완성됩니다.

Course Overview

그래프 뷰

백링크