딥 리서치 파이프라인

구조화된 시장 보고서를 생성하는 독립적인 6단계 파이프라인

딥 리서치 (Deep Research)는 메인 에이전트 루프와 병렬로 실행되지만, 이와 분리된 특수 파이프라인입니다. 에이전트 루프가 대화형이고 권한 게이트 방식인 데 비해, 딥 리서치 파이프라인은 단일 구조화 보고서를 생성하는 6단계 상태 머신입니다. 구현체는 apps/agent/src/deep-research/pipeline.ts에 위치합니다.

별도 파이프라인을 사용하는 이유는 무엇입니까? 다중 소스 리서치는 병렬 데이터 수집(팬아웃 후 병합), LLM-as-judge 품질 검사, 그리고 plan → call → observe 형태의 대화 흐름에는 맞지 않는 재시도 로직이 필요합니다. 전용 파이프라인을 사용하면 리서치 결과를 결정론적으로 유지하고 출처를 명시할 수 있으며, 대화 루프만으로는 이를 보장할 수 없습니다.

사용 예시: 기능 → 딥 리서치에서 사용자 관점의 설명과 보고서 출력 예시를 확인할 수 있습니다.

사용 시점

목표가 채팅 답변이 아닌 문서화된 결과물인 경우 이 파이프라인을 사용합니다.

특정 자산 또는 테마에 대한 장문의 시장 분석.
각 주장에 출처를 명시해야 하는 다중 소스 종합 분석.
나중에 id로 참조할 수 있는 결과물이 필요한 정기 리서치 실행.

"BTC 가격이 얼마야", "여기서 롱을 잡아야 할까" 같은 빠른 대화형 질문에는 에이전트 루프를 사용하십시오. 딥 리서치 파이프라인은 지연 시간이 더 길고, 도구 예산이 고정되어 있으며, 진행 중인 대화의 메모리가 없습니다.

6단계 구성

collectData 단계는 모든 목표에 대해 툴 레지스트리 대상 서브 에이전트 루프를 실행하며, 나머지 단계는 각각 단일 LLM 호출입니다.

메인 에이전트 루프로부터의 격리

파이프라인은 의도적으로 격리되어 있습니다.

채팅의 대화 기록을 참조하지 않습니다.
스킬 시스템의 활성화 상태를 소비하지 않습니다.
현재 활성화된 스킬을 사용하는 대신, 데이터 수집을 위한 자체적인 좁은 툴 서브셋을 구성합니다.
학습을 트리거하지 않습니다(review-engine은 파이프라인 턴에서 실행되지 않습니다).

이 격리는 두 가지 이점을 제공합니다. 결정론(모든 리서치 실행이 동일한 상태에서 시작됨)과 비용 제어(대화가 길어진 세션에서 기록이 리서치 비용으로 누출되지 않음)입니다.

모드

interface ResearchRequest {
  chatId: string;
  userMessage: string;
  mode?: "light" | "heavy";
  language?: string;
}

light (기본값). 병렬 수집 목표 2개, 더 작은 최대 반복 횟수, 단일 패스 보고서. 일반적인 지연 시간: 30~60초.
heavy. 병렬 수집 목표 4개, 더 큰 반복 예산, 더 철저한 종합 분석. 일반적인 지연 시간: 2~5분.

정기/크론 리서치에는 light를, 사용자가 철저한 보고서를 명시적으로 요청할 때는 heavy를 선택하십시오.

시나리오

보고서는 시나리오 중심으로 구성됩니다. 시나리오란 "강세 케이스", "약세 케이스", "기본 케이스", "규제 리스크", "매크로 배경" 등 사전 정의된 분석 관점입니다. metaPlan 단계는 apps/agent/src/deep-research/scenarios.ts의 카탈로그에서 주제에 따라 1~4개를 선택합니다.

시나리오 선택은 보고서 품질을 좌우합니다. BTC 리서치 보고서에 "macro" 시나리오가 없으면 가장 중요한 맥락을 놓치는 경우가 많고, "약세 케이스"가 없으면 확증 편향이 발생합니다. LLM의 시나리오 선택기가 신뢰도 있게 작동하도록 카탈로그는 의도적으로 작게 유지됩니다.

출력 아티팩트

결과는 ArtifactStore에 report 아티팩트로 저장됩니다.

interface ResearchResult {
  report_id: string;
  status: "completed" | "error" | "waiting_for_input";
  title: string | null;
  research_topic: string | null;
  scenarios: string[];
  summary: string | null;
  key_findings: string[];
  report_markdown: string | null;
  error?: string;
  tokens: { input: number; output: number };
}

메인 Agent는 report://{id} URI 스킴을 통해 완성된 보고서를 사용자에게 인용할 수 있습니다. 이것이 리서치와 대화를 결합하는 방식입니다. 사용자가 리서치를 요청하면 report_id를 받고, 이후 채팅에서 해당 보고서를 참조하는 후속 질문을 할 수 있습니다.

보고서 본문은 마크다운 형식입니다. 시나리오 헤더, 인라인 출처 표기([text](url) 방식), 그리고 summarize 단계에서 생성되는 "Key Findings" 불릿 목록이 포함됩니다.

실행 방법

REPL에서 실행

메인 Agent가 deep-research 도메인 스킬을 활성화하고 deep_research_run 도구를 호출합니다.

> write me a report on ETH staking yields this quarter
assistant: [activates deep-research skill]
assistant: [calls deep_research_run with mode=heavy]
assistant: ✓ report_id: r_abc123, here's the summary…

CLI 서브커맨드에서 실행

REPL을 완전히 우회합니다.

minara research "BTC ETF flows this quarter"
minara research "macro risks for Solana" --mode heavy

전체 플래그 목록은 서브커맨드 → minara research를 참조하십시오.

HTTP 요청에서 실행

curl -X POST http://localhost:8080/research \
  -H 'content-type: application/json' \
  -d '{"topic": "BTC ETF flows", "mode": "light"}'

요청 및 응답 스키마는 API → /research를 참조하십시오.

비용 및 관찰 가능성

각 단계는 {provider, model, tokens}를 source: "deep-research" 항목으로 감사 로그에 기록합니다. ResearchResult의 tokens 필드는 빠른 비용 파악을 위한 최선형 집계값입니다. 정확한 비용 귀속을 위해서는 감사 로그를 직접 조회하십시오.

SELECT model, SUM(input_tokens), SUM(output_tokens), COUNT(*)
  FROM audit
 WHERE source = 'deep-research'
   AND trace_id = ?
 GROUP BY model;

딥 리서치 파이프라인은 대부분의 Minara 배포에서 단일 LLM 비용 항목 중 가장 큽니다. 청구 금액이 예상보다 높다면, 일반적으로 이 쿼리를 가장 먼저 실행해야 합니다.

파이프라인 확장

파이프라인은 의도적으로 짧게 유지됩니다(pipeline.ts 기준 약 700줄). 일반적인 확장 방법은 다음과 같습니다.

시나리오 추가: scenarios.ts의 카탈로그에 항목을 추가합니다. 메타 플랜 프롬프트가 런타임에 카탈로그를 읽으므로 프롬프트 변경은 필요하지 않습니다.
수집 동시성 변경: PipelineConfig에서 collectConcurrency를 설정합니다. 기본값은 4이며, v1 상한값과 일치합니다.
목표별 최대 반복 횟수 변경: collectMaxIterations를 설정합니다. 기본값은 8입니다. 이 값은 각 데이터 수집 서브 에이전트의 LLM 턴 예산입니다.
후처리 단계 추가: 파이프라인 클래스에 새 메서드를 추가하고 summarize와 반환 사이에서 호출합니다. 기존 단계에 로직을 인라인으로 추가하지 마십시오. 단계 경계가 파이프라인을 디버그 가능하게 만드는 핵심입니다.

파이프라인을 메인 에이전트 루프의 기록에 연결하지 마십시오. 격리는 설계상 의도된 기능입니다. 이를 깨면 채팅 비용이 리서치 비용으로 누출됩니다.

리서치에 포함하지 말아야 할 것

실시간 가격 의존 결정. 파이프라인은 수 분이 걸리며 그 사이 가격은 변동합니다. 현재 실행 조건에 의존하는 작업에는 에이전트 루프를 사용하십시오.
자금 이동 도구 호출. 데이터 수집은 자금 이동 도구를 모두 제외한 좁은 툴 서브셋을 사용합니다. 툴 서브셋에 자금 이동 도구가 실수로 포함된 경우 파이프라인은 실행을 거부합니다.
사용자 개인 컨텍스트. 파이프라인은 사용자의 지갑 잔액이나 거래 기록을 읽지 않으며, 공개 시장 데이터만 활용합니다. 보고서에 사용자의 특정 포지션을 반영해야 한다면, bootstrap 시점에 사용자 메시지에 해당 포지션을 포함시키십시오. 파이프라인이 이를 후속 단계에 반영합니다.

딥 리서치 파이프라인

목차