DeerFlow 2.1 실습: 팝업 기획서·제품 표·체험 페이지 만들기

가상 문구 브랜드의 제품안 한 장을 DeerFlow에 넣고 팝업 기획서, 제품 비교 CSV, 브라우저에서 여는 체험 페이지를 만들었습니다. 아래 화면은 실제로 내려받은 index.html입니다. 제품 세 개의 크기와 가격을 보고, 관심 있는 색상을 누르면 선택 결과가 바뀝니다. 코드를 직접 작성하지 않고 자료와 요청문을 준비해 만든 예제입니다.

이 예제의 출발점은 작은 팀에서 흔히 생기는 일입니다. 제품 목록은 표로, 운영 계획은 문서로, 사람들에게 보여줄 내용은 페이지로 필요합니다. 세 파일을 따로 부탁하면 제품 이름이나 가격을 여러 번 옮겨 적게 됩니다. 같은 자료와 조건을 프로젝트에 넣어두고 필요한 파일을 함께 만들면, 이후 변경할 때도 어느 자료에서 출발했는지 찾기 쉽습니다.

한 프로젝트에 자료와 파일을 모으는 이유

DeerFlow는 ByteDance가 공개한 오픈소스 에이전트 도구입니다. 모델에게 답변을 받는 대화창에 파일 작업, 스킬, 프로젝트 공간이 연결돼 있습니다. v2.1.0은 2026년 9월 24일 공개됐고, 이 글에서는 그 태그를 고정해 사용했습니다. 버전을 적어두는 이유는 화면과 설정 항목이 바뀌었을 때 같은 조건으로 다시 확인하기 위해서입니다.

이번 작업에서는 프로젝트의 Instructions에 브랜드 조건을 저장하고, Documents에 제품안을 넣었습니다. 실제 파일 제작은 그 프로젝트 안의 새 대화에서 진행했습니다. 결과도 대화 아래에 파일 카드로 남아서, 문서 내용을 복사해 저장할 필요 없이 Markdown·CSV·HTML을 내려받을 수 있었습니다.

HTML 한 장만 빨리 만들려면 익숙한 코딩 에이전트로 시작해도 됩니다. DeerFlow는 브리프와 여러 종류의 파일을 같은 프로젝트에서 이어 만들고 싶을 때 검토할 만합니다. 대신 첫 모델 연결과 실행 환경은 직접 준비해야 합니다. 이미 운영 중인 DeerFlow를 사용하는 사람은 다음 설치 부분을 건너뛰고 프로젝트 생성부터 따라가면 됩니다.

실행 환경과 Gemini 연결을 준비합니다

처음 시작한다면 Docker가 실행되는 컴퓨터, Git, 사용할 모델의 API 키가 필요합니다. API 키는 채팅 서비스에 로그인하는 것과 별개입니다. 이번에는 사용 가능한 모델 목록을 확인한 Gemini 무료 프로젝트에서 gemini-3.5-flash-lite를 사용했습니다. 모델 이름과 무료 한도는 프로젝트에 따라 달라질 수 있으므로 본인 AI Studio에서 먼저 확인합니다.

git clone --branch v2.1.0 --depth 1 https://github.com/bytedance/deer-flow.git deerflow-lab
cd deerflow-lab
make config
make docker-init

위 명령은 공식 Install.md의 Docker 준비 순서에 버전 고정을 더한 것입니다. make docker-init은 실행 준비이며, 웹 화면까지 켜는 단계는 아닙니다. 저장소 루트의 .env에 모델 이름과 키를 적고, config.yaml의 models 항목에 사용할 모델을 연결합니다. 이미 만들어둔 config.yaml이 있다면 전체를 덮어쓰지 말고 해당 항목을 수정합니다.

GEMINI_MODEL=gemini-3.5-flash-lite
GEMINI_API_KEY=여기에_본인의_API_키
NEXT_TELEMETRY_DISABLED=1

models:
  - name: gemini-hands-on
    display_name: Gemini 3.5 Flash Lite
    use: langchain_google_genai:ChatGoogleGenerativeAI
    model: $GEMINI_MODEL
    google_api_key: $GEMINI_API_KEY
    vertexai: false
    timeout: 90
    max_retries: 1
    max_tokens: 8192
    supports_vision: false
    request_admission:
      requests_per_minute: 10
      max_wait_seconds: 90
      max_queue_size: 10

여기서는 Google의 네이티브 연결인 ChatGoogleGenerativeAI를 사용합니다. 처음에는 Gemini의 OpenAI 호환 주소로 연결했지만, 파일을 읽은 뒤 이어지는 요청에서 thought_signature 누락 오류가 났습니다. 네이티브 연결로 바꾸고 새 대화에서 다시 요청하자 파일 쓰기가 진행됐습니다. 같은 모델 이름을 적어도 연결 방식에 따라 도구 호출 대화의 처리가 달라질 수 있습니다.

실제 파일 생성 때는 GEMINI_API_KEY 환경변수로 인증됐습니다. 그 과정에서 설정에 넣었던 gemini_api_key라는 필드는 지원하지 않는다는 경고가 나와, 위 예제에는 패키지가 사용하는 google_api_key로 바로잡았습니다. 수정한 설정으로 서버가 시작되는 것은 확인했지만 추가 모델 호출은 하지 않았습니다. 사용 중인 패키지 버전에서는 이 필드명도 공식 문서와 맞춰 확인합니다.

make docker-start

공식 기본 실행 주소는 http://localhost:2026입니다. 이번 실습에서는 컴퓨터에 다른 Docker 작업이 있어 전용 Compose 프로젝트와 별도 로컬 포트를 사용했습니다. 컨테이너 이름, 네트워크, 작업 폴더도 분리했습니다. 회사 서버에 이미 여러 서비스가 있다면 기본 실행 명령을 그대로 넣기보다 포트와 저장 위치부터 분리하는 편이 좋습니다.

첫 화면에서 로컬 계정을 만들고 들어간 뒤 대화 입력창의 모델 목록에 Gemini 3.5 Flash Lite가 보이는지 확인합니다. 키 오류가 나면 모델 이름부터 바꾸기보다 .env가 실행 환경에 전달됐는지와 API 사용 가능 상태를 봅니다. 키 값은 프롬프트나 업로드 문서에 넣지 않습니다.

SOFT TABLE 프로젝트와 제품안을 만듭니다

예제 브랜드는 작은 책상에서 쓰는 자석 메모보드를 판매한다고 가정했습니다. 제품 세 개의 이름·크기·가격, 짧은 가상 고객 발언만 입력했습니다. 시장 규모나 방문객 수는 준비하지 않았습니다. 정하지 않은 조건은 미정으로 남겨두면, 나중에 실제 장소와 예산이 생겼을 때 그 부분부터 이어 작업할 수 있습니다.

1. 01

   New project에서 프로젝트 만들기

   프로젝트 이름을 SOFT TABLE · 팝업 준비로 지정합니다. 왼쪽 메뉴에서 프로젝트가 보이지 않는다면 Group chats by project 설정을 확인합니다.

2. 02

   Instructions에 프로젝트 조건 저장

   가상 자료로 연습한다는 점, 한국어 작성, 장소·기간·예산은 미정이라는 점을 저장합니다. 매번 새 대화에 반복해서 적을 공통 조건입니다.

3. 03

   Documents에 popup-brief.md 업로드

   아래 제품안을 텍스트 파일로 저장해 올립니다. 문서 목록에 파일명이 표시되면 보관된 상태입니다.

4. 04

   New chat에서 자료를 첨부하고 요청

   실습에서는 Documents에 올린 것만으로 끝내지 않고, 프로젝트 안의 새 대화에서 같은 popup-brief.md를 다시 첨부했습니다. 입력창에 첨부 파일이 보이는 상태에서 요청문을 보냈습니다.

SOFT TABLE이라는 가상 브랜드의 팝업 준비 자료를 만듭니다.
제품과 고객 발언은 모두 가상 데이터입니다.
제공 자료만 사용하고 실제 웹 조사나 판매 실적이 있다고 쓰지 않습니다.
한국어로 작성하고 모르는 장소·기간·예산은 미정으로 남깁니다.
파일은 프로젝트 출력 공간에 저장합니다.
외부 API 호출, 결제, 실제 가입, 이메일 발송, 프로젝트 밖 파일 읽기는 하지 않습니다.

# SOFT TABLE · 팝업 예제 자료

이 문서의 브랜드·상품·고객·수치는 모두 DAYABLE 실습용 가상 설정이다. 시장 조사나 실제 판매 실적이 아니다.

## 프로젝트
- 가상 브랜드: SOFT TABLE
- 제품: 작은 책상에서 쓰는 자석 메모보드
- 팝업 목표: 방문자가 자신의 책상 사진 없이도 배치를 그려보고, 관심 있는 색상 한 개를 선택하도록 한다.
- 운영 장소·기간은 아직 결정하지 않았다. 실제 예약이나 구매 기능은 넣지 않는다.

## 입력으로 제공하는 제품안
| 제품 | 가격(가정) | 색상 | 방문객에게 보여줄 점 |
|---|---:|---|---|
| Desk Mini | 29000원 | 라벤더 | 작은 책상에 놓는 폭 18cm 보드 |
| Desk Wide | 39000원 | 크림 | 메모 6장을 놓는 폭 28cm 보드 |
| Travel Card | 15000원 | 민트 | 가방에 넣는 폭 10cm 보드 |

## 가상 고객 발언
- 참여자 A: “모니터 아래에 메모를 붙이면 떼면서 자꾸 구겨져요.”
- 참여자 B: “노트북 옆에 놓을 자리가 작아서 큰 소품은 못 사요.”
- 참여자 C: “선물하기 전에 포장 모양을 보고 싶어요.”

## 원하는 산출물
1. 위 자료만 이용한 팝업 준비 브리프 Markdown: 목표, 방문객 동선 3단계, 아직 정하지 않은 항목.
2. 제품 비교표 CSV: 제품, 가정 가격, 색상, 크기.
3. 브라우저로 여는 index.html: 브랜드 제목, 제품 3개, 3단계 체험 순서, 관심 색상 선택 UI. 크림·보라·민트, 외부 이미지/패키지/스크립트 없이 단일 파일.

사진을 찍었다거나 고객을 조사했다고 쓰지 않는다. 실제 상품은 없으며 결제·신청·이메일 전송 기능도 없다. 이 자료에 없는 방문객 수·예산·시장 크기·판매 효과는 만들지 않는다.

입력 자료에 제품별 가격과 크기를 붙여둔 점이 중요했습니다. “예쁜 팝업 페이지를 만들어줘”라고만 하면 어떤 제품을 어떤 기준으로 비교할지 모델이 정하게 됩니다. 이 파일에는 가격이 가정이라는 표시와 고객 발언이 가상이라는 설명까지 들어 있습니다. 실제 업무에서는 이 자리에 확정한 상품 정보와 공유 가능한 고객 메모를 넣으면 됩니다.

문서·CSV·HTML을 파일명까지 지정해 요청합니다

요청은 파일 세 개로 나눴습니다. 계획은 짧게 읽는 문서, 제품 목록은 수정하기 쉬운 표, 체험 동선은 눌러볼 수 있는 페이지로 정했습니다. 결과의 형식이 다르면 에이전트가 무엇을 어디에 저장할지도 적어주는 편이 작업을 확인하기 쉽습니다.

이 프로젝트에 첨부한 popup-brief.md를 읽고 가상 브랜드 SOFT TABLE의 팝업 준비 파일을 만들어줘.
실제 조사를 수행하지 말고 제공한 가상 자료만 사용해.
1. popup-plan.md: 팝업 목표, 동선 3단계, 미정 항목을 500자 안팎으로 정리.
2. products.csv: 제품 3개의 제품명, 가정 가격, 색상, 크기.
3. index.html: 제품 비교와 체험 동선을 보여주는 단일 HTML 페이지. 크림·보라·민트 색상, 제품 3개를 CSS 도형으로 표현, 관심 색상 선택 버튼과 현재 선택 안내. 외부 이미지·라이브러리·API 호출·결제·실제 가입은 쓰지 마.
모든 파일은 이 프로젝트의 출력 공간에 저장하고 결과물 링크를 알려줘. 파일 쓰기 도구를 사용하고, 셸 실행·웹 검색·외부 파일 읽기는 하지 마. 가능한 한 6회 안팎의 도구 호출로 끝내. 보이는 상품은 실습용 가상 설정임을 HTML에도 표시해줘.

이 실행에서는 파일 읽기·쓰기 도구만 연결했습니다. 사용 가능 도구는 ls, read_file, glob, grep, write_file, str_replace였고, 웹 검색이나 셸 실행은 켜지 않았습니다. 그래서 공간 후보를 찾아주거나 제품 사진을 만들어준 결과는 없습니다. 이미지도 요청에 적은 대로 CSS 사각형으로 표현됐습니다. 파일 제작만 확인할 첫 작업으로 범위를 줄인 것입니다.

프롬프트의 “6회 안팎”은 희망하는 도구 호출 수이지 강제 실행 한도가 아닙니다. 실제 앱의 내부 그래프 단계와도 일치하지 않습니다. 여기서는 내부 한도를 너무 낮게 설정해, 파일 쓰기가 끝난 뒤 마지막 설명 단계에서 Recursion limit 오류가 났습니다. 파일 카드가 이미 만들어져 있었기 때문에 각각 내려받아 확인할 수 있었습니다.

생성된 세 파일을 직접 열어봅니다

products.csv에는 헤더와 제품 세 줄이 들어 있었습니다. 제품 이름, 가격, 색상, 크기는 입력 자료와 같았습니다. CSV는 Excel이나 스프레드시트에서 열 수 있고, 인코딩 선택 창이 뜬다면 UTF-8을 선택합니다. 파일을 연 뒤 열이 한 칸에 몰리면 구분 기호를 쉼표로 지정합니다.

제품명,가정 가격,색상,크기
Desk Mini,29000원,라벤더,폭 18cm
Desk Wide,39000원,크림,폭 28cm
Travel Card,15000원,민트,폭 10cm

기획서는 탐색, 비교, 선택 순으로 방문객 동선을 적었습니다. 장소·기간·예산에는 모두 미정이라고 남겼습니다. 입력에 없는 운영 수치를 채우지 않은 상태라, 실제 팝업을 준비할 때 정해야 할 항목이 바로 보입니다. 다만 운영 인력이나 물류 계획까지 들어간 행사 실행안은 아닙니다.

# SOFT TABLE 팝업 기획서

## 팝업 목표
방문자가 자신의 책상 사진 없이도 배치 공간을 그려보고, 라벤더·크림·민트 색상 중 관심 있는 색상 한 개를 편안하게 둘러보며 선택하도록 유도합니다.

## 방문객 체험 동선 3단계
1. **1단계 (탐색)**: 모니터 아래나 노트북 옆 공간에 자석 메모보드가 놓이는 방식을 눈으로 확인합니다.
2. **2단계 (비교)**: Desk Mini, Desk Wide, Travel Card 세 가지 크기와 색상(라벤더, 크림, 민트)을 살펴봅니다.
3. **3단계 (선택)**: 마음에 드는 색상 버튼을 눌러보며 나의 책상 취향을 가볍게 확인합니다.

## 미정 항목
- 운영 장소: 미정
- 운영 기간: 미정
- 예산: 미정

index.html은 설치할 패키지가 없는 단일 파일입니다. 내려받은 파일을 브라우저로 열어도 되고, 이 글 상단의 공개 예제에서 바로 확인해도 됩니다. 실제로 민트 버튼을 누르자 “현재 선택된 색상: 민트 (Travel Card)”라는 문구가 표시됐습니다. 선택 결과는 화면에만 보이며 서버에 수집되거나 새로고침 뒤 보존되지는 않습니다.

첫 화면은 제품을 비교하기에 충분히 읽히지만, 실제 상품 페이지로 쓰려면 더 작업해야 합니다. 지금 보이는 도형은 상품 사진이 아니고, 첫 데스크톱 시안입니다. 390px 모바일 화면에서는 가로 넘침이 확인돼 카드 배치를 후속 수정해야 합니다. 이번에는 원본을 그대로 공개했습니다. 독자가 첫 결과의 수준을 보고 무엇을 더 요청할지 판단할 수 있도록 하기 위해서입니다.

두 번째 요청에서는 바꿀 부분을 좁힙니다

다음 작업은 “더 예쁘게”보다 실제 페이지에서 아쉬운 부분을 지정하는 편이 낫습니다. 예를 들어 휴대폰에서 카드가 좁게 보이면 세로 배치, 제품의 쓰임새가 잘 드러나지 않으면 카드마다 사용 장면, 고객에게 보여주려면 실제 제품 사진이 필요합니다. 이 가운데 한 가지를 먼저 바꾸고 같은 파일을 다시 열어봅니다.

방금 만든 index.html을 수정해줘.
휴대폰에서는 제품 카드 3개를 세로로 쌓아줘.
각 카드의 가격·폭·색상은 현재 값을 그대로 유지해.
색상 버튼은 높이 44px 이상으로 만들고, 선택된 버튼 테두리를 진하게 표시해.
popup-plan.md와 products.csv는 이번에는 수정하지 마.
수정한 파일을 같은 출력 위치에 저장해줘.

이 요청은 후속 연습용입니다. 공개한 결과 파일에는 적용하지 않았습니다. 실제 제품 사진을 붙일 때도 먼저 사진을 프로젝트 자료에 올리고, 어느 제품 카드에 쓸지 파일명을 연결해서 요청하면 됩니다. 이미지 생성 모델을 새로 쓰는 작업과 이미 있는 이미지를 배치하는 작업은 준비물과 비용이 다릅니다.

비용과 오류에서 실제로 확인한 것

DeerFlow 코드 자체를 실행하는 것과 연결한 모델을 사용하는 것은 별개입니다. 이번에는 무료 Gemini 프로젝트에서 호출했고 새 결제를 활성화하지 않았습니다. 화면에는 이 대화 사용량이 입력 약 57.8K, 출력 2,267, 합계 약 60.1K 토큰으로 표시됐습니다. 짧은 요청문보다 사용량이 큰 이유를 볼 때는 대화에 포함되는 시스템 지시, 도구 설명, 읽은 자료와 반복 호출도 함께 생각해야 합니다.

화면에 표시된 29초는 이 실행의 대화 처리 기록입니다. Docker 설치, 이미지 빌드, 모델 연결을 포함한 전체 준비 시간이 아닙니다. 또한 파일 생성 뒤 실행 한도 오류가 있었으므로, 이 숫자를 작업 전체가 오류 없이 끝났다는 근거로 사용하지 않았습니다. 모델 요금과 무료 한도는 실행 전 본인 프로젝트에서 확인해야 합니다.

그래프 한도는 토큰 예산과 다른 설정입니다. 파일을 몇 번 쓸지만 세어 임의로 낮추면 내부 단계에서 먼저 멈출 수 있습니다. 우리는 실습 후 recursion_limit을 200, max_recursion_limit을 256으로 정리했습니다. 이 변경으로 같은 요청을 다시 완주했는지는 확인하지 않았으므로, 해결 완료로 기록하지 않았습니다.

같은 프로젝트에서 다음 자료를 붙일 수 있습니다

팝업 장소와 날짜가 정해지면 Instructions의 미정 조건을 바꾸고, 제품이 추가되면 Documents의 브리프를 갱신합니다. 그다음 “새 제품을 CSV와 HTML에 함께 추가하고 운영 문서는 유지해줘”처럼 수정 범위를 지정할 수 있습니다. 한 파일의 이름을 바꿨다면 다른 파일에서도 같은 이름을 쓰도록 요청합니다.

DeerFlow의 기본 스킬에는 조사나 발표자료 제작처럼 더 큰 작업도 있습니다. 이번 예제에서는 실행하지 않았습니다. 제공 자료만으로 세 파일을 만든 다음, 실제로 필요한 순간에 검색 도구나 추가 스킬을 연결하는 순서로 확장할 수 있습니다. 지금 남은 것은 팝업 기획서 한 장, 수정 가능한 제품 표, 색상을 눌러볼 수 있는 페이지입니다.