Dexter 배포 및 실전 가이드: AI로 SEC 공시 분석과 DCF 기업 가치 평가하기

개요

Dexter는 터미널에서 실행되는 자율형 금융 연구 에이전트입니다. 복잡한 질문을 던지면 에이전트가 스스로 작업을 분해하고, 여러 데이터 도구를 호출하며, 결과를 교차 검증하여 데이터에 기반한 결론을 도출합니다. 마치 지치지 않는 시니어 분석가를 곁에 둔 것과 같습니다.

핵심 기능은 다음과 같습니다:

• SEC 공시 읽기: 10-K, 10-Q, 8-K 등 공시 문서를 자동으로 크롤링
• 실시간 시세 조회: 주가, 재무 지표, 현금 흐름, 대차대조표 확인
• DCF 내재 가치 추정: SKILL.md 기반의 DCF 스킬이 내장되어 직접 현금 흐름 할인 모델 실행
• 자가 검증 루프: 중간 결과를 스스로 점검하고 결론이 도출될 때까지 반복
• 루프 보호: 단계 제한(Step Limit) 기능으로 에이전트의 무한 루프 방지

전체 프로젝트는 TypeScript로 작성되었으며, LangChain + Ink(React for CLI)를 핵심으로 Bun 1.0+ 환경에서 작동합니다. 더 낮은 비용으로 이러한 기능을 최대한 활용하고 싶다면 LLM 제공자를 Defapi로 전환하여 공식 가격의 절반 수준으로 API를 이용할 수 있습니다.

---

대상 독자

• AI 에이전트 아키텍처(도구 호출, 에이전트 루프)에 대한 기초 지식이 있는 1~5년 차 개발자
• AI 도구를 활용해 펀더멘털 분석을 보조받고 싶은 개인 투자자 또는 핀테크 종사자
• 실제 프로젝트에서 다양한 데이터 소스(SEC, Financial Datasets, Exa)를 통합하는 방법을 알고 싶은 엔지니어
• 금융 퀀트 연구에 관심이 있어 로컬 연구 파이프라인을 구축하려는 사용자

---

핵심 의존성 및 환경

---

전체 프로젝트 구조

dexter/
├── .dexter/
│   └── settings.json          # 에이전트 실행 설정 (모델/제공자 선택)
├── src/
│   ├── agent/                  # 에이전트 핵심: 루프 로직, 프롬프트, scratchpad
│   │   ├── agent.ts           # 에이전트 루프 메인 루프
│   │   ├── prompts.ts         # 시스템 프롬프트
│   │   └── scratchpad.ts      # 도구 호출 히스토리 기록
│   ├── cli.tsx                # Ink/React CLI 렌더링 엔트리
│   ├── index.tsx              # 프로그램 엔트리
│   ├── components/            # CLI UI 컴포넌트 (Ink)
│   ├── hooks/                 # React 훅 (AgentRunner, ModelSelector)
│   ├── model/
│   │   └── llm.ts            # 다중 제공자 LLM 추상화 계층
│   ├── tools/
│   │   ├── registry.ts       # 도구 등록부
│   │   ├── finance/          # 금융 도구: 시세, 재무, 공시, 내부자 거래
│   │   ├── search/           # 웹 검색 도구 (Exa / Tavily)
│   │   ├── browser/          # Playwright 브라우저 자동화
│   │   └── descriptions/     # 도구 설명 (시스템 프롬프트 주입용)
│   ├── skills/               # SKILL.md 스킬 디렉토리
│   │   └── dcf/
│   │       └── SKILL.md     # DCF 내재 가치 추정 스킬
│   ├── evals/               # LangSmith 평가 프레임워크
│   └── utils/               # 환경 변수, 설정, 캐시
├── scripts/
│   └── release.sh
├── .env                     # API 키 (gitignored)
└── package.json

---

단계별 가이드

Step 1: Bun 설치 및 프로젝트 클론

시스템에 Bun이 없다면 먼저 설치하세요. Windows/macOS/Linux 공통:

# macOS / Linux
curl -fsSL https://bun.com/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1|iex"

설치 확인:

bun --version
# 출력 예시: Bun v1.2.x

그 다음 Dexter 저장소를 클론합니다:

git clone https://github.com/virattt/dexter.git
cd dexter

Step 2: .env 환경 변수 설정

환경 변수 템플릿 파일을 복사합니다:

cp env.example .env

에디터로 .env를 열고 키를 입력합니다. Defapi 연동 방식에 대해 설명하자면, OpenAI 대신 Defapi를 사용하여 비용을 50% 절감하고 싶다면 다음과 같이 설정하세요:

# .env

# ── LLM 제공자 ──────────────────────────────────────
# 방안 A: OpenAI 직접 사용 (기본)
OPENAI_API_KEY=sk-your-openai-key

# 방안 B: Defapi를 통해 OpenAI 연동 (추천, 50% 절감)
# OPENAI_API_KEY=sk-your-defapi-key
# OPENAI_BASE_URL=https://api.defapi.com/v1

# 기타 선택 가능한 LLM 제공자
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
GOOGLE_API_KEY=your-google-key
XAI_API_KEY=your-xai-key
OPENROUTER_API_KEY=your-openrouter-key

# 로컬 모델 (OLLAMA)
OLLAMA_BASE_URL=http://127.0.0.1:11434

# ── 금융 데이터 ───────────────────────────────────────
# 기관급 시장 데이터, AAPL/NVDA/MSFT 무료
FINANCIAL_DATASETS_API_KEY=your-financial-datasets-key

# ── 웹 검색 ───────────────────────────────────────
# Exa 우선 사용, Tavily는 백업용
EXASEARCH_API_KEY=your-exa-key
TAVILY_API_KEY=your-tavily-key

의존성 설치:

bun install

Step 3: Dexter 대화형 모드 실행

대화형 CLI를 시작합니다:

bun start

터미널에 Ink로 렌더링된 컬러풀한 화면이 나타납니다. 금융 관련 질문을 직접 입력하세요:

AAPL의 지난 5년간 매출 성장세는 어땠어? 현재 DCF 내재 가치는 얼마야?

Dexter가 자동으로 작업을 시작합니다: 작업 분해 → 재무 데이터 조회 → SEC 공시 읽기 → DCF 스킬 실행 → 결론 요약. 각 도구 호출 과정이 화면에 실시간으로 표시됩니다.

코드를 수정하면서 디버깅하고 싶다면 watch 모드를 사용하세요:

bun dev

Step 4: 모델 / 제공자 전환

CLI 내에서 /model 명령어를 입력해 LLM 제공자와 모델을 전환할 수 있습니다. Dexter는 다음 접두사를 자동 인식합니다:

예를 들어 Claude로 전환하려면:

/model claude-sonnet-4-7

Step 5: 금융 도구로 주식 조회

Dexter의 핵심은 financial_search 도구입니다. 질문에 따라 가장 적합한 하위 도구에 작업을 위임합니다. 전형적인 쿼리 예시는 다음과 같습니다:

매출 및 이익 조회:

TSLA의 최근 3년 매출, 순이익, 잉여현금흐름(FCF)을 조회해줘

Dexter는 get_income_statements(손익계산서)와 get_cash_flow_statements(현금흐름표)를 호출하여 표 형태로 정리해 반환합니다.

대차대조표 조회:

NVDA의 최신 부채 비율은 얼마야? 현금 및 현금성 자산은 얼마나 있어?

SEC 공시 읽기:

AAPL 최신 10-K 보고서의 "Risk Factors" 섹션을 읽어줘

Dexter는 read_filings 도구를 호출해 10-K 내용을 가져오고 해당 섹션을 찾아냅니다.

내부자 거래 조회:

최근 분기 FAANG 주식의 내부자 거래 현황은 어때?

모든 도구 호출의 원본 데이터는 .dexter/scratchpad/ 디렉토리의 JSONL 파일에 기록되어 사후 검토가 가능합니다.

Step 6: DCF 가치 평가 스킬 실행

DCF(현금 흐름 할인) 평가는 Dexter의 내장 스킬 중 하나입니다. 질문에 "내재 가치" 또는 "가치 평가"가 포함되면 에이전트가 자동으로 skill 도구를 통해 src/skills/dcf/SKILL.md를 로드하고 다음 단계를 실행합니다:

1. 회사의 과거 잉여현금흐름(FCF) 획득
2. 향후 5~10년 성장률 가정치 추정
3. 가중평균자본비용(WACC) 계산
4. 현재 가치로 할인
5. 최종 가치 범위 + 민감도 분석 출력

예시 쿼리:

MSFT의 DCF 내재 가치는 얼마야? 보수적, 기본, 낙관적 세 가지 시나리오별 결과를 알려줘

Step 7: 디버깅 및 Scratchpad 로그 확인

Dexter의 모든 쿼리는 .dexter/scratchpad/에 JSONL 파일로 생성됩니다. 파일명 형식은 다음과 같습니다:

YYYY-MM-DD-HHMMSS_<session_id>.jsonl

각 줄은 구조화된 레코드입니다:

{"type":"init","timestamp":"2026-03-27T10:00:00.000Z","query":"AAPL의 DCF 내재 가치는 얼마야?"}
{"type":"tool_start","timestamp":"2026-03-27T10:00:01.000Z","toolName":"get_cash_flow_statements","args":{"ticker":"AAPL","period":"annual","limit":5}}
{"type":"tool_result","timestamp":"2026-03-27T10:00:03.000Z","toolName":"get_cash_flow_statements","result":{"freeCashFlow":[67800000000, 73000000000, ...]},"llmSummary":"AAPL의 지난 5년간 잉여현금흐름은 지속 성장했으며, 연평균 성장률은 약 9.2%입니다."}
{"type":"thinking","timestamp":"2026-03-27T10:00:05.000Z","content":"FCF 데이터를 확보했습니다. 이제 애널리스트 예상 성장률과 WACC 파라미터가 필요합니다..."}

특정 도구의 호출 결과가 이상하다면 이 파일을 열어 즉시 문제를 진단할 수 있습니다. jq를 사용해 빠르게 필터링할 수도 있습니다:

# 도구 호출 결과만 보기
cat .dexter/scratchpad/2026-03-27-*.jsonl | jq 'select(.type == "tool_result")'

# 에이전트의 추론 과정 보기
cat .dexter/scratchpad/2026-03-27-*.jsonl | jq 'select(.type == "thinking")'

---

자주 발생하는 문제 해결(FAQ)

1. OPENAI_API_KEY not found 메시지 발생

가장 흔한 오류입니다. .env 파일이 존재하는지, 경로가 올바른지 확인하세요:

ls -la .env

파일 안에 OPENAI_API_KEY=... 또는 OPENAI_API_KEY + OPENAI_BASE_URL 조합이 있는지 확인하세요. Defapi를 사용한다면 두 항목이 모두 있어야 합니다.

2. 금융 데이터 결과가 비어 있음

Financial Datasets의 무료 데이터는 AAPL, NVDA, MSFT로 제한됩니다. 다른 종목을 조회하면 빈 결과가 반환될 수 있습니다. 다음을 확인하세요:

• financialdatasets.ai에서 구독 플랜 확인
• FINANCIAL_DATASETS_API_KEY가 .env에 올바르게 입력되었는지 확인

3. 모델 호출 타임아웃

Anthropic 및 Google API의 기본 타임아웃은 60초입니다. 해외 서비스 네트워크가 불안정하다면 src/model/llm.ts에서 maxAttempts와 재시도 대기 시간을 조정하세요. 장기적으로 사용한다면 Defapi를 통해 국내 최적화 라우트를 이용하는 것이 더 안정적입니다.

4. 에이전트가 무한 루프에 빠짐

Dexter는 maxIterations(기본 10단계) 보호 기능이 내장되어 있습니다. 더 많은 단계가 필요한 작업이라면 src/agent/agent.ts에서 파라미터를 조정하세요. 단계가 소진되면 에이전트는 현재까지의 중간 결론을 최종 결과로 반환합니다.

5. 도구 호출 데이터가 불완전함

Financial Datasets의 limit 파라미터는 반환되는 연도 수를 제어하며 기본값은 1년일 수 있습니다. 조회 시 Dexter에게 limit=5 또는 limit=10을 명시적으로 지정하도록 요청하세요.

6. Scratchpad 파일이 비어 있거나 생성되지 않음

Scratchpad는 src/agent/scratchpad.ts에서 관리합니다. SKIP_SCRATCHPAD=true 환경 변수가 설정되어 있다면 파일이 기록되지 않습니다. 또한 새로운 쿼리마다 새 파일이 생성되며 이전 파일에 덧붙여지지 않습니다.

---

심화 학습 및 확장 방향

WhatsApp 연동으로 모바일 연구 비서 구현

Dexter는 WhatsApp Gateway를 통한 메시지 수신을 지원합니다. 모바일 기기와 Dexter가 동일 네트워크에 있다면:

# QR 코드로 WhatsApp 계정 연동
bun run gateway:login

# 게이트웨이 실행
bun run gateway

그 후 WhatsApp으로 메시지를 보내면 Dexter가 답장합니다. 출퇴근 길에도 보유 종목의 최신 재무 데이터를 조회할 수 있습니다.

자세한 설정은 src/gateway/channels/whatsapp/README.md를 참고하세요.

평가 스위트로 에이전트 정확도 검증

Dexter에는 LangSmith 기반의 평가 프레임워크가 내장되어 있습니다:

# 전체 테스트 셋에 대해 평가 실행
bun run src/evals/run.ts

# 무작위 10개 문항만 실행
bun run src/evals/run.ts --sample 10

평가는 LLM-as-Judge 방식으로 점수가 매겨지며 결과는 LangSmith 대시보드에 업로드됩니다. 재무 지표 계산 로직을 수정했다면 이 평가 도구로 품질을 검증하세요.

Ollama로 로컬 모델 사용

외부 API에 전혀 의존하고 싶지 않다면:

# Ollama 실행 (사전 설치 필요)
ollama serve

# .env 설정
OLLAMA_BASE_URL=http://127.0.0.1:11434

그 후 CLI에서 ollama:qwen2.5나 다른 로컬 모델로 전환하세요. 단, 로컬 모델의 도구 호출 능력은 GPT-5.4나 Claude Sonnet보다 불안정할 수 있으므로 저지연, 저비용이 필요한 시나리오에서 권장합니다.

SKILL.md 커스텀으로 새 스킬 작성

Dexter의 스킬은 SKILL.md로 정의됩니다. 각 스킬은 YAML frontmatter(이름, 설명)와 마크다운 형식의 지침으로 구성됩니다. 새 스킬을 만드는 방법:

1. src/skills/ 아래에 새 디렉토리 생성 (예: src/skills/dupont/)
2. SKILL.md 작성:

---
name: dupont-analysis
description: 듀퐁 분석 - ROE를 순이익률, 자산회전율, 재무레버리지로 분해
---

# 듀퐁 분석 스킬

당신은 재무 분석가입니다. 입력된 티커(ticker)에 대해 다음 단계를 수행하세요:

1. 회사의 순이익, 영업수익, 총자산 및 자기자본 확보
2. 세 가지 분해 지표 계산:
   - 순이익률 = 순이익 / 영업수익
   - 자산회전율 = 영업수익 / 총자산
   - 재무레버리지 = 총자산 / 자기자본
3. ROE 계산 = 세 지표의 곱
4. 산업 평균과 비교하여 점수 부여 (1-10)

1. Dexter 재시작 시 새 스킬이 자동으로 감지되어 시스템 프롬프트에 주입됩니다.

Defapi 연동으로 API 비용 절감

자동 모니터링이나 정기 보고서 생성 등 LLM 호출 빈도가 높은 경우 API 비용이 부담될 수 있습니다. Defapi를 연동하면 비용을 약 50% 절감할 수 있습니다:

# .env
OPENAI_API_KEY=your-defapi-api-key
OPENAI_BASE_URL=https://api.defapi.com/v1

Defapi는 모든 v1/chat/completions 인터페이스 모델과 호환되므로 Dexter의 코드 수정 없이 키와 base URL만 교체하면 됩니다.