gpt-researcher 딥다이브
— 스스로 웹을 뒤져 출처 달린 리포트를 쓰는 AI 연구원

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

gpt-researcher는 스스로를 "웹과 로컬 문서 양쪽을 조사하도록 설계된 최초의 오픈소스 딥 리서치 에이전트"라고 소개한다. 핵심은 단순하다 — LLM(거대 언어모델)에게 "답을 알려줘"라고 직접 묻는 대신, "답을 찾기 위해 무엇을 검색할지 계획을 세우게" 한 뒤, 실제 웹 검색 결과를 읽혀서 답하게 한다. 그래서 결과물이 최신이고, 출처가 달리고, 한쪽으로 치우치지 않는다.

이 프로젝트가 푸는 문제는 명확하다. ① 사람이 직접 하는 조사는 며칠~몇 주가 걸린다. ② LLM 혼자서는 옛날 데이터로 학습돼 환각(hallucination)을 일으키고 출처도 없다. ③ LLM은 한 번에 다룰 수 있는 글자 수(토큰)에 한계가 있어 긴 리포트를 못 쓴다. gpt-researcher는 여러 AI 에이전트를 분업·병렬로 굴려 이 세 문제를 한 번에 푼다.

2왜 주목받는가

트렌딩 이유 · 경쟁 제품 대비 장점.

gpt-researcher가 다시 TrendShift 라이브 멘션에 오른 직접적 계기는 "Claude 스킬(Claude Skill)로 설치 가능"해졌기 때문이다. npx skills add assafelovic/gpt-researcher 한 줄이면 Claude의 대화 안에서 이 딥 리서치 능력을 바로 부를 수 있게 됐고, 이게 X(트위터)·Reddit에서 회자되며 노출이 늘었다. 하지만 인기의 근본은 따로 있다 — "비공개 제품(ChatGPT·Perplexity의 Deep Research)에 맞먹는 기능을 통째로 오픈소스로 제공"한다는 점이다.

차별점은 네 가지다. ① 오픈소스 + 셀프호스팅(내 서버·내 API 키로 돌려 데이터가 밖으로 안 샌다), ② 20개 이상의 검색엔진을 섞어 한쪽 소스 편향을 줄인다, ③ 웹과 로컬 문서를 함께 조사한다(사내 PDF + 최신 웹), ④ 어떤 LLM이든 끼울 수 있다(OpenAI·로컬 모델·기타 호환 API). 비공개 서비스는 이 중 어느 것도 사용자가 마음대로 못 바꾼다.

3기술 스택 전체 지도

에이전트·검색·스크래핑·백엔드·프론트 한눈에.

백엔드는 Python, 프론트엔드는 Next.js로 나뉜 풀스택 구조다. 핵심 두뇌는 gpt_researcher 파이썬 패키지이고, 그 둘레를 검색 어댑터 20종·스크래퍼 7종·LLM 추상화·메모리·웹서버가 감싼다. 레이어별로 보면 이렇다.

4아키텍처 심화 분석

질문 하나가 들어오면 어디서 어디로 흐르는가.

먼저 독수리 시점으로 전체 그림을 보자. 중심에는 GPTResearcher라는 지휘자 객체가 있고, 그가 여러 스킬(skill) 부하들에게 일을 시킨다 — 검색 계획을 짜는 ResearchConductor, 모은 자료를 추리는 ContextManager·SourceCurator, 리포트를 쓰는 ReportGenerator. 그 바깥에 실제 일손인 retriever(검색)·scraper(스크랩)·LLM·memory(벡터 저장)가 붙는다.

이제 대표 흐름 한 줄기를 입구부터 출구까지 따라가 보자 — 코드의 5%가 일의 95%를 한다. 가장 흔한 사건은 "리서치 한 건을 요청받았다"이다. 핵심은 gpt_researcher/skills/researcher.py의 ResearchConductor가 쥐고 있다.

핵심은 ②와 ⑤다. ②에서 "무엇을 검색할지 스스로 계획"(원 질문을 여러 하위 질문으로 쪼갬)하기 때문에 한 번의 검색으로 끝나지 않고, ⑤에서 "모은 자료 중 질문과 진짜 관련된 부분만 골라" LLM에게 넘기기 때문에 토큰 한계 안에서도 깊이 있는 리포트가 나온다. 이 두 단계가 "딥 리서치"라는 이름의 알맹이다.

이 프로젝트 특유의 관례 하나: GPTResearcher는 모든 기능을 자기가 직접 들고 있지 않고, 스킬 객체들을 조립(composition)해 갖는다. 생성자에서 부하들을 한 줄씩 임명하는 모양이 그대로 보인다.

# gpt_researcher/agent.py — 지휘자가 스킬(부하)들을 '조립'해 갖는다
self.research_conductor = ResearchConductor(self)   # 계획·검색·수집
self.context_manager    = ContextManager(self)      # 벡터로 관련 맥락만 추림
self.source_curator     = SourceCurator(self)       # 출처 정리·인용
self.report_generator   = ReportGenerator(self)     # 리포트 작성
self.deep_researcher    = DeepResearchSkill(self)   # (옵션) 재귀 심층 탐색

덕분에 한 부분만 바꿔 끼우기 쉽다("작성기만 교체", "검색 수집만 커스텀"). 상속 대신 조립으로 짠 이 구조가 코드베이스를 읽는 첫 열쇠다.

한편 gpt-researcher에는 더 무거운 멀티에이전트 모드(multi_agents/)가 따로 있다. 여기선 LangGraph 상태 그래프로 여러 전문 에이전트가 신문사 편집국처럼 협업한다 — ChiefEditorAgent(편집장)가 흐름을 지휘하고, 노드(node) 하나하나가 한 직무를 맡는다.

# multi_agents/agents/orchestrator.py — 편집국 워크플로(LangGraph StateGraph)
browser  ─▶ planner ─▶ human ─▶ researcher ─▶ writer ─▶ fact_checker
   (초기조사)  (개요)   (검토)   (병렬 연구)    (집필)    (사실확인)
                 │                                          │
                 └── 사람이 개요를 검토·수정(최대 5회) ◀──────┘  ─▶ publisher (발행)

여기엔 사람이 끼어드는 단계(human-in-the-loop)가 있어서, AI가 짠 리서치 개요를 사람이 승인·수정한 뒤에야 본 조사가 시작된다(최대 5회 수정). "AI에게 다 맡기되 중요한 갈림길에선 사람이 확인"하는 실전 패턴의 좋은 예다.

5디렉토리 구조 해부

215개 파일, 어디부터 봐야 하나.

파일이 많지만 최상위 폴더 6덩어리로 묶으면 길이 보인다. ★ 표시한 gpt_researcher/가 두뇌(라이브러리)이고, backend/는 웹서버, multi_agents/는 LangGraph 협업 모드, frontend/는 화면이다.

6학습 포인트 (기술별)

이 레포에서 배울 만한 것 + 어느 파일을 펴면 되는지.

예컨대 검색 백엔드를 무료인 DuckDuckGo로 바꾸고, 웹+MCP를 동시에 쓰는 hybrid 모드를 켜는 건 환경변수 한 줄씩이다:

# 유료 Tavily 대신 무료 DuckDuckGo로 검색 / 웹+MCP 하이브리드
export RETRIEVER=duckduckgo          # 검색기 교체 (코드 수정 0줄)
export RETRIEVER=tavily,mcp           # 웹 검색 + MCP 데이터소스 동시

7시스템 요구사항

돌리려면 무엇이 필요한가.

무겁진 않다 — 일반 노트북에서 충분히 돈다. 진짜 관문은 컴퓨팅 파워가 아니라 API 키다. 기본 설정은 LLM에 OpenAI, 검색에 Tavily를 쓰므로 두 키가 필요하다(둘 다 무료 대안으로 교체 가능).

8직접 해볼 수 있는 실습 과제

읽기만 하지 말고 손에 익히는 단계.

pip install gpt-researcher
export OPENAI_API_KEY=...  &&  export TAVILY_API_KEY=...
python -c "import asyncio; from gpt_researcher import GPTResearcher; \
r=GPTResearcher(query='왜 전기차 배터리에 LFP가 늘어나나?'); \
asyncio.run(r.conduct_research()); print(asyncio.run(r.write_report()))"

git clone https://github.com/assafelovic/gpt-researcher && cd gpt-researcher
# .env에 OPENAI_API_KEY / TAVILY_API_KEY 채운 뒤
docker-compose up --build

export RETRIEVER=duckduckgo   # tavily → 무료 DuckDuckGo
python -m uvicorn main:app --reload

9관련 기술 심화 학습 로드맵

한 주씩 따라가는 6주 계획.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• GitHub 저장소: assafelovic/gpt-researcher
• 공식 문서: docs.gptr.dev · 공식 사이트 gptr.dev
• PyPI 패키지: pip install gpt-researcher
• Claude 스킬: skills.sh — npx skills add assafelovic/gpt-researcher
• 핵심 의존성: LangGraph · 검색 Tavily
• 이론적 뿌리: Plan-and-Solve (arXiv 2305.04091) · RAG (arXiv 2005.11401)