telegram-bot-workers/docs/plans/2026-02-05-agent-refactoring-design.md

도메인/예치금 에이전트 리팩토링 설계

작성일: 2026-02-05 상태: 설계 완료, 구현 대기

개요

기존 직접 코드 처리 방식의 domain-tool.ts와 deposit-agent.ts를 server-agent.ts 패턴의 세션 기반 AI 에이전트로 리팩토링한다.

요구사항

항목	도메인 에이전트	예치금 에이전트
트리거	모든 도메인 요청	모든 예치금 요청
의도 파악	AI가 판단	AI가 판단
세션	작업 단위 (추천/등록/NS변경)	입금 신고만
즉시 응답	가격, WHOIS, 목록 조회	잔액, 내역 조회
리팩토링	domain-tool.ts 통합	deposit-agent.ts 통합

아키텍처

메인 AI (openai-service.ts)
    │
    ├─ 도메인 키워드 감지 → Domain Agent (domain-agent.ts)
    │   ├─ 세션 있음? → 세션 컨텍스트로 처리
    │   ├─ 세션 필요? → 세션 생성 후 상담
    │   └─ 즉시 응답 가능? → 바로 실행
    │
    └─ 예치금 키워드 감지 → Deposit Agent (deposit-agent.ts)
        ├─ 세션 있음? → 입금 신고 흐름 계속
        ├─ 입금 신고? → 세션 생성 후 정보 수집
        └─ 조회 요청? → 바로 실행

__PASSTHROUGH__: 무관한 메시지는 메인 AI로 반환

도메인 에이전트 상세

세션 상태

type DomainSessionStatus =
  | 'gathering'    // 정보 수집 중 (추천용 키워드, 용도)
  | 'suggesting'   // 추천 결과 표시 중
  | 'confirming'   // 등록 확인 대기
  | 'setting_ns'   // 네임서버 변경 확인 대기
  | 'completed';   // 완료

작업별 흐름

작업	세션	흐름
추천	✅	gathering → suggesting → confirming → completed
등록	✅	confirming → completed (잔액 확인 → 결제)
NS 변경	✅	setting_ns → completed (위험 작업이라 확인)
가격 조회	❌	즉시 응답
WHOIS	❌	즉시 응답
내 도메인 목록	❌	즉시 응답
도메인 정보	❌	즉시 응답

AI 페르소나

"10년 경력의 도메인 컨설턴트. 브랜딩, SEO, 가격 대비 가치를 고려한 조언 제공.
불필요한 프리미엄 도메인 추천 자제, 실용적인 선택 유도."

전용 도구

• check_domain: 가용성 + 가격 확인
• search_suggestions: 키워드 기반 도메인 추천
• get_whois: WHOIS 조회
• get_price: TLD별 가격 조회
• register_domain: 도메인 등록 (잔액 차감)
• set_nameservers: 네임서버 변경

예치금 에이전트 상세

세션 상태

type DepositSessionStatus =
  | 'collecting_amount'    // 금액 수집 중
  | 'collecting_name'      // 입금자명 수집 중
  | 'confirming'           // 입금 신고 확인 대기
  | 'completed';           // 완료

작업별 흐름

작업	세션	흐름
입금 신고	✅	collecting_amount → collecting_name → confirming → completed
잔액 조회	❌	즉시 응답
계좌 안내	❌	즉시 응답
거래 내역	❌	즉시 응답
거래 취소	❌	즉시 응답 (본인 pending만)
관리자 기능	❌	즉시 응답 (pending/confirm/reject)

스마트 파싱

"홍길동 5만원 입금" → 금액 + 입금자명 한번에 파싱 → confirming 직행
"충전할게" → "얼마를 충전하시겠어요?" → collecting_amount
"3만원" → "입금자명을 알려주세요" → collecting_name
"홍길동" → confirming → 자동매칭 시도

AI 페르소나

"친절한 금융 상담사. 입금 절차를 명확하게 안내하고,
자동 매칭 결과를 즉시 알려줌. 오입금 방지를 위해 확인 절차 진행."

전용 도구

• get_balance: 잔액 조회
• get_account_info: 계좌 안내
• request_deposit: 입금 신고 및 자동 매칭
• get_transactions: 거래 내역
• cancel_transaction: 대기 중 거래 취소

데이터베이스 스키마

domain_sessions

CREATE TABLE domain_sessions (
  user_id TEXT PRIMARY KEY,
  status TEXT NOT NULL,
  collected_info TEXT,
  target_domain TEXT,
  messages TEXT,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL,
  expires_at INTEGER NOT NULL
);

CREATE INDEX idx_domain_sessions_expires ON domain_sessions(expires_at);

deposit_sessions

CREATE TABLE deposit_sessions (
  user_id TEXT PRIMARY KEY,
  status TEXT NOT NULL,
  collected_info TEXT,
  messages TEXT,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL,
  expires_at INTEGER NOT NULL
);

CREATE INDEX idx_deposit_sessions_expires ON deposit_sessions(expires_at);

파일 구조 변경

Before

src/
├── openai-service.ts
├── deposit-agent.ts
├── server-agent.ts
├── tools/
│   ├── domain-tool.ts
│   ├── deposit-tool.ts
│   ├── server-tool.ts
│   └── ...

After

src/
├── openai-service.ts
├── agents/
│   ├── domain-agent.ts
│   ├── deposit-agent.ts
│   └── server-agent.ts
├── tools/
│   ├── search-tool.ts
│   ├── weather-tool.ts
│   └── utility-tools.ts

구현 순서

Phase 1: 기반 작업

1. migrations/006_add_agent_sessions.sql 작성
2. src/agents/ 디렉토리 생성
3. server-agent.ts → src/agents/로 이동
4. 타입 정의 (types.ts에 세션 타입 추가)

Phase 2: 도메인 에이전트

1. src/agents/domain-agent.ts 생성
2. 기존 domain-tool.ts 로직 통합
3. openai-service.ts 수정
4. tools/domain-tool.ts 삭제

Phase 3: 예치금 에이전트

1. src/agents/deposit-agent.ts 리팩토링
2. openai-service.ts 수정
3. tools/deposit-tool.ts 삭제

Phase 4: 정리

1. tools/server-tool.ts → agents/ 통합
2. import 경로 정리
3. 테스트 및 문서 업데이트

테스트 계획

도메인 에이전트

시나리오	예상 결과
"도메인 추천해줘"	세션 시작 → 용도 질문
"커피숍 도메인"	키워드 수집 → 추천 결과
"1번 등록"	잔액 확인 → 등록 확인
".com 가격"	즉시 응답 (세션 없음)
"example.com WHOIS"	즉시 응답 (세션 없음)
세션 중 "날씨 알려줘"	__PASSTHROUGH__ → 메인 AI

예치금 에이전트

시나리오	예상 결과
"충전할게"	세션 시작 → 금액 질문
"5만원"	입금자명 질문
"홍길동"	확인 → 자동매칭 시도
"홍길동 5만원 입금"	한번에 파싱 → 바로 확인
"잔액"	즉시 응답 (세션 없음)
"내역"	즉시 응답 (세션 없음)

위험 요소 및 대응

위험	대응
기존 기능 회귀	기존 테스트 유지 + 세션 테스트 추가
세션 충돌	user_id 기반 단일 세션 보장
AI 오판단	__PASSTHROUGH__ 폴백, 명확한 시스템 프롬프트
마이그레이션 실패	로컬 테스트 후 프로덕션 적용