DeerFlow 2.0 입문 튜토리얼: 나만의 첫 번째 AI 에이전트 워크스테이션 구축하기 기초 가이드
DeerFlow 2.0 입문 튜토리얼: 나만의 첫 번째 AI Agent 워크스테이션 구축하기
난이도: 입문 | 소요 시간: 15분 | 목표: 기초 지식 없이도 실행 가능한 AI 어시스턴트 구축하기
질문에 답하는 것뿐만 아니라 실제로 컴퓨터를 조작하고, 코드를 작성하며, 정보를 검색하고, 나아가 완성된 리포트까지 생성해주는 AI 어시스턴트가 있다면 어떨까 생각해 보신 적이 있나요? 오늘 소개할 DeerFlow는 바로 여러분의 업무를 대신 수행해 줄 수 있는 AI Agent입니다.
대상 독자
- 1~3년 차 백엔드/풀스택 개발자
- AI Agent에 관심은 있지만 어디서부터 시작해야 할지 모르는 분
- AI 도구를 직접 호스팅하고 싶지만 비용이 걱정되는 분
핵심 의존성 및 환경
시작하기 전에 개발 환경이 다음 요구 사항을 충족하는지 확인하세요:
- Node.js: 22.x 이상 버전
- pnpm: 9.x 이상 버전
- Docker: 최신 안정판
- Git: 프로젝트 클론용
[!TIP]
Docker 방식을 통한 배포를 권장합니다. 클릭 한 번으로 실행 가능하며 Nginx 등의 서비스를 수동으로 설정할 필요가 없습니다.
전체 프로젝트 구조
설치가 완료되면 다음과 같은 프로젝트 구조를 확인할 수 있습니다:
deer-flow/
├── backend/ # 백엔드 서비스
│ ├── src/
│ │ ├── client.py # Python 클라이언트
│ │ ├── agent/ # Agent 코어
│ │ └── skills/ # 내장 스킬
│ └── docs/ # 설정 문서
├── frontend/ # Web 인터페이스
├── config.yaml # 모델 설정 파일
├── .env # 환경 변수
└── Makefile # 실행 명령
단계별 가이드
1단계: 프로젝트 클론
터미널을 열고 다음 명령어를 실행하세요:
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
[!TIP]
GitHub 접속이 원활하지 않은 경우, 미러 사이트를 이용하거나 Release 버전의 압축 파일을 직접 다운로드하세요.
2단계: 설정 파일 생성
DeerFlow는 템플릿을 기반으로 로컬 설정 파일을 생성하는 명령어를 제공합니다:
make config
실행 후 프로젝트 루트 디렉토리에 config.yaml과 .env 파일이 생성된 것을 볼 수 있습니다.
3단계: 모델 설정 (중요!)
가장 중요한 단계입니다. DeerFlow는 다양한 모델 공급업체를 지원하지만, 우리는 Defapi 사용을 강력히 권장합니다. 이유는 간단합니다. 가격이 공식 API의 절반 수준이기 때문입니다.
[!WARNING]
OpenAI 공식 API를 직접 사용할 경우 월 비용이 수백 달러를 쉽게 넘어설 수 있습니다. Defapi를 사용하면 이 비용을 절반 이하로 낮출 수 있습니다.
config.yaml 파일을 열고 다음과 같이 설정하세요:
models:
- name: gpt-4o-mini # 내부 식별자
display_name: GPT-4o Mini # 표시 이름
use: langchain_openai:ChatOpenAI
model: openai/gpt-4o-mini # Defapi 모델 식별자
api_key: $DEFAPI_API_KEY # 환경 변수 사용
base_url: https://api.defapi.org # Defapi 엔드포인트
max_tokens: 4096
temperature: 0.7
supports_vision: true
그 다음 .env 파일에 Defapi API Key를 입력하세요:
DEFAPI_API_KEY="dk-xxxxxxxxxxxxxxxx"
TAVILY_API_KEY="your-tavily-api-key" # 웹 검색용
[!TIP]
https://defapi.org 에 접속하여 계정을 등록하세요. 신규 사용자는 무료 크레딧으로 먼저 체험해 볼 수 있습니다.
Defapi에서 지원하는 인기 모델:
| 모델 | 식별자 | 권장 시나리오 |
|---|---|---|
| GPT-4o Mini | openai/gpt-4o-mini | 일상적인 대화, 높은 가성비 |
| GPT-4o | openai/gpt-4o | 복잡한 작업, 균형 잡힌 선택 |
| Claude Sonnet 4.5 | anthropic/claude-sonnet-4.5 | 강력한 코딩 능력 |
| DeepSeek V3 | deepseek/deepseek-v3 | 강력한 추론 능력, 저렴한 가격 |
4단계: 샌드박스 이미지 풀(Pull)
Docker 방식으로 실행하기 전에 샌드박스 이미지를 먼저 다운로드해야 합니다 (이 단계는 한 번만 수행하면 됩니다):
make docker-init
이미지 용량이 크므로 몇 분 정도 소요될 수 있습니다.
5단계: 서비스 시작
모든 준비가 끝났습니다. DeerFlow를 실행하세요:
make docker-start
다음과 같은 출력이 보이면 성공적으로 시작된 것입니다:
✔ Frontend started on http://localhost:2026
✔ Backend started on http://localhost:8000
6단계: 인터페이스 접속
브라우저를 열고 **http://localhost:2026**에 접속하면 현대적인 채팅 인터페이스를 볼 수 있습니다.
7단계: 첫 번째 미션
채팅창에 다음과 같이 입력해 보세요:
안녕하세요, 자신에 대해 소개해 주세요.
DeerFlow가 답변뿐만 아니라 자신이 가진 능력들을 알려줄 것입니다:
- 웹 검색
- 파일 읽기 및 쓰기
- 명령어 실행
- 리포트, 슬라이드, 웹페이지 생성
조금 더 도전적인 작업을 시도해 보세요:
현재 디렉토리의 파일 구조를 나열해 줘.
DeerFlow는 샌드박스 환경 내에서 명령어를 실행하고 결과를 반환합니다. 이것이 일반적인 챗봇과 DeerFlow의 본질적인 차이점입니다. 실제로 일을 대신 해준다는 것이죠.
자주 발생하는 문제 해결(FAQ)
Q1: 컨테이너 실행 실패, 포트 중복 오류
# 어떤 프로세스가 2026 포트를 사용 중인지 확인
lsof -i :2026
# 또는 (Windows)
netstat -ano | findstr 2026
해당 프로세스를 종료하거나 config.yaml에서 포트를 변경하세요.
Q2: API Key가 정확한데 오류가 발생함
.env 파일이 프로젝트 루트 디렉토리에 있는지 확인하고, source .env를 실행하거나 컨테이너를 재시작했는지 확인하세요.
Q3: 모델이 도구 호출(Tool Calling)을 지원하지 않음
일부 모델은 function calling을 지원하지 않습니다. GPT-4o, Claude, Gemini 등 도구 호출을 지원하는 모델을 사용 중인지 확인하세요. Defapi에서 제공하는 모델들은 OpenAI 프로토콜과 호환되므로 보통 문제가 없습니다.
Q4: 웹 검색 결과가 비어 있음
TAVILY_API_KEY가 올바르게 설정되었는지 확인하세요. Tavily는 DeerFlow의 기본 검색 engine입니다.
Q5: Docker 메모리 부족
Docker 기본 메모리 할당량이 부족할 수 있습니다. 4GB 이상으로 설정을 권장합니다:
// Docker Desktop -> Settings -> Resources
Q6: 로컬 개발 모드로 사용하고 싶음
Docker를 사용하고 싶지 않다면 로컬에서 직접 실행할 수도 있습니다:
make check # 환경 체크
make dev # 개발 서버 실행
심화 학습 방향
1. 커스텀 스킬 (Skills)
DeerFlow의 Skills 시스템은 매우 유연합니다. 나만의 스킬을 만들 수 있습니다:
/mnt/skills/custom/
└── my-awesome-skill/
└── SKILL.md
내장된 Skill의 형식을 참고하여 Markdown 파일을 작성하면 됩니다.
2. MCP 서버 확장
DeerFlow는 MCP 프로토콜을 지원하여 다양한 외부 도구와 연동할 수 있습니다. 자세한 내용은 공식 문서 MCP Server Guide를 참조하세요.
3. 다른 모델로 교체하기
DeepSeek이나 Claude를 사용해보고 싶다면 config.yaml만 수정하면 됩니다:
# DeepSeek 설정 예시
models:
- name: deepseek-v3
display_name: DeepSeek V3
use: langchain_openai:ChatOpenAI
model: deepseek/deepseek-v3
api_key: $DEFAPI_API_KEY
base_url: https://api.defapi.org
supports_thinking: true
4. 내장 Python 클라이언트 사용
DeerFlow는 여러분의 프로젝트에 직접 삽입할 수 있는 Python 라이브러리를 제공합니다:
from src.client import DeerFlowClient
client = DeerFlowClient()
response = client.chat("이 논문을 분석해 줘", thread_id="my-thread")
# 스트리밍 출력
for event in client.stream("hello"):
print(event.data)
요약
오늘 우리는 환경 준비부터 서비스 실행, 첫 번째 미션 수행까지 DeerFlow 2.0을 함께 구축해 보았습니다. 이것이 단순한 챗봇이 아니라, 실제로 여러분의 업무를 돕는 AI 워크스테이션이라는 점을 느끼셨을 것입니다.
DeerFlow의 핵심 장점은 다음과 같습니다:
- 확장성: Skills, MCP, Sub-Agents 모두 커스텀 가능
- 보안 및 제어: 샌드박스로 격리되어 Docker 컨테이너 내에서 안전하게 작업 실행
- 유연한 비용: Defapi를 통해 공식 비용의 절반 수준으로 운영 가능
지금 바로 시도해 보세요! 코드를 짜게 하고, 정보를 검색하게 하고, 리포트를 만들게 해보세요. AI를 이렇게도 활용할 수 있다는 것을 알게 될 것입니다.
구축 과정에서 문제가 발생하면 댓글로 남겨주세요. 최대한 답변해 드리겠습니다. 다음에는 특정 작업을 완수하기 위한 커스텀 Skills 제작법에 대해 깊이 있게 다뤄보겠습니다.
즐거운 개발 되세요!