Agent Treatment Flow Agent 메시지 유형

개요

Agent Treatment Flow는 A-H-I-R 순환 모델을 통한 핵심 Agent 메시지 외에도, 사용자의 치료 여정 전반에서 필요한 다양한 메시지를 생성하고 관리합니다. 이 문서는 치료 여정의 각 단계에서 생성되는 메시지 유형과 그 생성 조건을 정의합니다.

1. 메시지 카테고리

1.1 치료 여정 단계별 분류

• Onboarding Content: 서비스 시작 시 필요한 메시지
• Daily Management Content: 일상적인 치료 활동 관련 메시지
• Treatment Content: 핵심 치료 프로세스 메시지
• Progress Content: 치료 진행 상황 관련 메시지
• Analysis Content: 평가 및 분석 결과 메시지
• Service Management Content: 서비스 관리 관련 메시지

1.2 우선순위별 분류

• Critical: 반드시 확인해야 하는 메시지 (슬립큐 소개, 서비스 만료 안내)
• High: 치료 효과에 직접적인 영향을 미치는 메시지
• Medium: 치료 보조 및 동기부여 메시지
• Low: 참고 정보 및 부가적인 메시지

enum ContentType {
  TASK = 'TASK',
  MESSAGE = 'MESSAGE',
  QUESTION = 'QUESTION',
  INSIGHT = 'INSIGHT',
  ALERT = 'ALERT',
  PRESCRIPTION = 'PRESCRIPTION',
  // 10가지 구체적인 메시지 유형
  SLEEPQ_INTRO = 'SLEEPQ_INTRO', // 슬립큐 소개
  SLEEP_LOG_PROMPT = 'SLEEP_LOG_PROMPT', // 수면로그 작성하기
  SLEEP_PRESCRIPTION_GUIDE = 'SLEEP_PRESCRIPTION_GUIDE', // 권장 취침시간 처방 안내
  WAKE_TIME_ALERT = 'WAKE_TIME_ALERT', // 기상 시각 안내
  BEDTIME_PREPARATION = 'BEDTIME_PREPARATION', // 취침 준비 안내
  DAILY_CONTENT_GUIDE = 'DAILY_CONTENT_GUIDE', // 오늘의 치료 프로그램 안내
  TREATMENT_PROGRESS = 'TREATMENT_PROGRESS', // 나의 치료 현황
  FINAL_ANALYSIS_RESULT = 'FINAL_ANALYSIS_RESULT', // 최종 설문 분석 결과 안내
  SERVICE_EXPIRATION = 'SERVICE_EXPIRATION', // 서비스 사용 만료 안내
  THERAPEUTIC_TASK = 'THERAPEUTIC_TASK', // 치료적 Task 메시지
}

enum MessagePriority {
  CRITICAL = 'CRITICAL',
  HIGH = 'HIGH',
  MEDIUM = 'MEDIUM',
  LOW = 'LOW',
}

2. 10가지 핵심 Agent 메시지

2.1 슬립큐 소개 (Onboarding Content)

생성 조건

• 사용자가 처음 슬립큐 서비스에 가입하고 홈 화면에 진입할 때
• 온보딩 프로세스가 미완료 상태일 때

메시지 구성

interface SleepQIntroContent {
  type: 'sleepq_intro';
  title: '슬립큐에 오신 것을 환영합니다';
  content: {
    description: string; // 슬립큐 서비스 소개
    treatmentApproach: string; // CBT-I 기반 치료 접근법
    expectedBenefits: string[]; // 기대 효과 목록
    duration: string; // 치료 기간
  };
  actions: [
    {
      type: 'primary';
      label: '슬립큐 시작하기';
      target: 'onboarding_complete';
    }
  ];
  rules: {
    mandatory: true; // 필수 확인
    dismissible: false; // 닫기 불가
    priority: 'critical';
    persistUntilCompleted: true; // 완료까지 계속 표시
  };
}

비즈니스 로직

• 사용자는 반드시 이 메시지를 확인해야 함
• 다른 스케줄 이벤트로 인한 메시지가 표시되더라도, 해당 액션 완료 후 다시 표시
• 슬립큐 서비스의 전반적인 소개와 기대 효과를 전달

2.2 수면기록 작성하기 (Daily Management Content)

생성 조건

• 오늘의 수면기록이 아직 작성되지 않은 상태
• '슬립큐 소개' 완료 후
• 현재 시각이 오전 6시 ~ 오후 10시 사이

메시지 구성

interface SleepRecordPromptContent {
  type: 'sleep_log_prompt';
  title: '오늘의 수면은 어떠셨나요?';
  content: {
    promptMessage: string; // 수면기록 작성 유도 메시지
    lastRecordInfo?: {
      date: Date;
      daysAgo: number;
    };
    streakInfo?: {
      currentStreak: number;
      message: string;
    };
  };
  actions: [{
    type: 'primary';
    label: '수면기록 작성하기';
    target: 'sleep_record_form';
  }];
  rules: {
    priority: 'high';
    displayTimeWindow: {
      start: '06:00',
      end: '22:00'
    };
    reappearInterval: 4 * 60 * 60 * 1000; // 4시간마다 재표시
  };
}

비즈니스 로직

• 사용자가 깨어있을 가능성이 높은 시간대에만 표시
• 수면기록 작성 완료 시까지 주기적으로 재표시
• 연속 작성 일수(streak) 정보를 포함하여 동기부여

2.3 권장 취침시간 처방 안내 (Treatment Content)

생성 조건

• 자정에 RTIB 계산으로 새로운 취침시간 처방이 발생
• 이전 처방과 다른 새로운 처방이 생성됨

메시지 구성

interface SleepPrescriptionContent {
  type: 'sleep_prescription_update';
  title: '새로운 수면 처방이 준비되었습니다';
  content: {
    prescription: {
      previousBedTime: string;
      newBedTime: string;
      previousWakeTime: string;
      newWakeTime: string;
      effectiveDate: Date;
    };
    rationale: string; // 처방 변경 이유
    expectedBenefit: string; // 기대 효과
  };
  actions: [
    {
      type: 'primary';
      label: '알람 설정하기';
      target: 'alarm_settings';
    },
    {
      type: 'secondary';
      label: '자세히 보기';
      target: 'prescription_details';
    }
  ];
  rules: {
    priority: 'high';
    queueForNextSession: true; // 자정 생성 시 큐에 저장
    avoidNightNotification: true; // 야간 푸시 알림 방지
  };
}

비즈니스 로직

• 자정에는 사용자 수면 방해 방지를 위해 푸시 알림 대신 큐에 저장
• 다음날 아침 앱 실행 시 즉시 표시
• 처방 변경 이유와 기대 효과를 명확히 전달

2.4 기상 시각 안내 (Daily Management Content)

생성 조건

• 사용자가 설정한 기상 목표 시각 도달
• 기상 알람과 동시에 생성

메시지 구성

interface WakeTimeReminderContent {
  type: 'wake_time_reminder';
  title: '좋은 아침입니다! 🌅';
  content: {
    wakeTimeInfo: {
      targetWakeTime: string;
      currentTime: string;
      bedTime: string; // 어제 설정한 취침 시각
    };
    encouragement: string; // 격려 메시지
    tip: string; // 기상 후 권장 활동
  };
  actions: [{
    type: 'primary';
    label: '수면 기록하기';
    target: 'sleep_record_form';
  }];
  rules: {
    priority: 'high';
    autoDismissAfter: 30 * 60 * 1000; // 30분 후 자동 해제
    canReappear: true;
  };
}

2.5 취침 준비 안내 (Daily Management Content)

생성 조건

• 권장 취침시간 1시간 전
• 취침 준비 알림 설정이 활성화된 경우

메시지 구성

interface BedtimePreparationContent {
  type: 'bedtime_preparation';
  title: '취침 준비 시간입니다 🌙';
  content: {
    bedtimeInfo: {
      targetBedTime: string;
      timeUntilBed: string;
      wakeTime: string; // 내일 기상 시각
    };
    preparations: string[]; // 취침 준비 체크리스트
    relaxationTip: string; // 이완 활동 제안
  };
  actions: [{
    type: 'primary';
    label: '오늘의 프로그램 확인';
    target: 'program_view';
  }];
  rules: {
    priority: 'medium';
    displayDuration: 2 * 60 * 60 * 1000; // 최대 2시간 표시
  };
}

2.6 오늘의 치료 프로그램 안내 (Treatment Content)

생성 조건

• 수면기록 작성 완료 시
• 오늘의 프로그램이 미완료 상태
• 권장 취침시간 처방이 나오기 전

메시지 구성

interface DailyProgramContent {
  type: 'daily_program';
  title: '오늘의 치료 프로그램';
  content: {
    programInfo: {
      phase: string; // 현재 치료 단계
      dayIndex: number;
      modules: Array<{
        name: string;
        duration: string;
        status: 'pending' | 'in_progress' | 'completed';
      }>;
    };
    totalDuration: string; // 예상 총 소요시간
    completionBenefit: string; // 완료 시 기대 효과
  };
  actions: [{
    type: 'primary';
    label: '프로그램 시작하기';
    target: 'program_start';
  }];
  rules: {
    priority: 'medium';
    reappearIfIncomplete: true;
    reappearInterval: 6 * 60 * 60 * 1000; // 6시간마다
  };
}

2.7 나의 치료 현황 (Progress Content)

생성 조건

• 2주차부터 활성화
• 수면기록 작성 완료 시
• 매주 첫 수면기록 작성 시 -->

메시지 구성

interface TreatmentProgressContent {
  type: 'treatment_progress';
  title: '이번 주 치료 현황';
  content: {
    weekNumber: number;
    progressSummary: {
      sleepEfficiency: {
        current: number;
        change: number;
        trend: 'improving' | 'stable' | 'declining';
      };
      totalSleepTime: {
        average: string;
        change: string;
      };
      consistency: number; // 수면 규칙성 점수
    };
    achievements: string[]; // 이번 주 성과
    nextWeekFocus: string; // 다음 주 집중 영역
  };
  actions: [
    {
      type: 'primary';
      label: '상세 리포트 보기';
      target: 'progress_report';
    }
  ];
  rules: {
    priority: 'low';
    frequency: 'weekly';
    triggerDay: 'first_record_of_week';
  };
}

2.8 최종 설문 분석 결과 안내 (Analysis Content)

생성 조건

• 4회차 설문 응답 제출 완료
• 분석 결과 생성 완료

메시지 구성

interface FinalAnalysisContent {
  type: 'final_analysis';
  title: '치료 결과가 준비되었습니다';
  content: {
    treatmentSummary: {
      duration: string; // 총 치료 기간
      completionRate: number; // 프로그램 완료율
      overallImprovement: string; // 전반적 개선도
    };
    keyFindings: Array<{
      metric: string;
      before: string;
      after: string;
      improvement: string;
    }>;
    recommendations: string[]; // 향후 권장사항
  };
  actions: [
    {
      type: 'primary';
      label: '전체 리포트 확인';
      target: 'final_report';
    }
  ];
  rules: {
    priority: 'high';
    oneTimeDisplay: false; // 재확인 가능
    accessibleFrom: 'treatment_progress'; // 치료 현황에서 재접근 가능
  };
}

2.9 서비스 사용 만료 안내 (Service Management Content)

생성 조건

• 치료 주기 만료 시점 (자정)
• 서비스 종료 D-day

메시지 구성

interface ServiceExpirationContent {
  type: 'service_expiration';
  title: '서비스 이용 기간이 만료되었습니다';
  content: {
    expirationInfo: {
      startDate: Date;
      endDate: Date;
      totalDays: number;
    };
    treatmentSummary: {
      completedModules: number;
      totalModules: number;
      keyAchievements: string[];
    };
    options: {
      renewal: {
        available: boolean;
        discount?: number;
        benefits: string[];
      };
      export: {
        dataTypes: string[]; // 내보낼 수 있는 데이터
      };
    };
  };
  actions: [
    {
      type: 'primary';
      label: '서비스 연장하기';
      target: 'service_renewal';
      condition: 'renewal.available';
    },
    {
      type: 'secondary';
      label: '데이터 내보내기';
      target: 'data_export';
    }
  ];
  rules: {
    priority: 'critical';
    mandatory: true; // 필수 확인
    queueForNextSession: true; // 자정 생성 시 큐에 저장
  };
}

2.10 치료적 Task 메시지 (Treatment Content)

생성 조건

• P4 일일 코칭 모듈에서 Task 생성 시
• 사용자의 현재 치료 단계와 컨텍스트에 맞는 Task 선정
• 이전 Task 완료 또는 스킵 후 새로운 Task 필요 시

메시지 구성

interface TherapeuticTaskMessage {
  type: 'therapeutic_task';
  title: string; // Task 유형에 따라 동적으로 변경
  content: {
    taskCategory: 'cognitive' | 'behavioral' | 'emotional' | 'monitoring';
    taskDefinition: {
      name: string;
      description: string;
      rationale: string; // 왜 이 Task를 하는지
      expectedOutcome: string;
    };
    // Task 유형별 특화 필드
    cognitiveTask?: {
      beliefToChallenge: string; // 도전할 신념
      reframePrompt: string; // 재구성 프롬프트
    };
    behavioralTask?: {
      actionSteps: string[]; // 구체적 행동 단계
      timeOfDay: string; // 권장 수행 시간
      duration: string; // 예상 소요 시간
    };
    emotionalTask?: {
      emotionToExplore: string; // 탐색할 감정
      supportiveMessage: string; // 지지적 메시지
    };
    monitoringTask?: {
      metricsToTrack: string[]; // 추적할 지표
      reflectionPrompts: string[]; // 성찰 프롬프트
    };
  };
  actions: Array<{
    type: 'primary' | 'secondary';
    label: string;
    target: string;
  }>;
  rules: {
    priority: 'high';
    validityPeriod: number; // Task 유효 기간 (일)
    reappearIfIncomplete: boolean;
    reminderSchedule?: string[]; // 리마인더 일정
  };
}

비즈니스 로직

• P4 모듈의 황금률에 따라 개인화된 Task 생성
• Task 유형별 특화된 UI/UX 제공을 위한 구조
• 사용자의 치료 진행도와 이전 Task 수행률 고려
• A-H-I-R 순환 모델의 일부로서 지속적인 피드백 수집

Task 유형별 예시

인지 접근형 (Cognitive)

{
  "type": "therapeutic_task",
  "title": "오늘의 수면 생각 점검하기",
  "content": {
    "taskCategory": "cognitive",
    "taskDefinition": {
      "name": "수면 기대치 재평가",
      "description": "매일 8시간을 자야 한다는 생각이 오히려 스트레스가 될 수 있어요.",
      "rationale": "비현실적인 수면 기대를 조정하면 수면 압박감이 줄어듭니다.",
      "expectedOutcome": "수면에 대한 유연한 관점 형성"
    },
    "cognitiveTask": {
      "beliefToChallenge": "나는 반드시 8시간을 자야 한다",
      "reframePrompt": "어제 6시간만 잤지만 오늘 하루를 잘 보냈다면, 그것은 무엇을 의미할까요?"
    }
  }
}

행동 유도형 (Behavioral)

{
  "type": "therapeutic_task",
  "title": "수면 환경 개선하기",
  "content": {
    "taskCategory": "behavioral",
    "taskDefinition": {
      "name": "침실 온도 조절",
      "description": "오늘 밤 침실 온도를 18-22도로 맞춰보세요.",
      "rationale": "적절한 온도는 깊은 수면을 돕습니다.",
      "expectedOutcome": "수면의 질 향상"
    },
    "behavioralTask": {
      "actionSteps": ["취침 30분 전 침실 온도 확인", "에어컨/히터 조절 또는 창문 열기", "필요시 가벼운 이불로 교체"],
      "timeOfDay": "21:30",
      "duration": "10분"
    }
  }
}

3. 메시지 우선순위 매트릭스

메시지 유형	우선순위	생성 시점	재표시	필수 확인
슬립큐 소개	Critical	첫 가입 시	O	O
서비스 사용 만료 안내	Critical	만료 시점	X	O
수면기록 작성하기	High	매일 오전	O	X
권장 취침시간 처방 안내	High	처방 변경 시	X	X
기상 시각 안내	High	기상 시각	O	X
최종 설문 분석 결과 안내	High	분석 완료 시	X	X
치료적 Task 메시지	High	P4 Task 생성 시	O	X
취침 준비 안내	Medium	취침 1시간 전	X	X
오늘의 치료 프로그램 안내	Medium	수면기록 후	O	X
나의 치료 현황	Low	주 1회	X	X

4. 메시지 생성 규칙

4.1 시간대 고려

• 야간 시간(오후 11시 ~ 오전 6시)에는 즉시 알림 대신 큐에 저장
• 사용자의 수면을 방해하지 않도록 조심스럽게 처리

4.2 개인화

• 모든 메시지는 사용자의 치료 단계와 진행 상황에 맞춰 개인화
• 이전 상호작용 이력을 고려하여 메시지 톤 조정

4.3 컨텍스트 연속성

• 각 메시지는 이전 메시지와의 연결성 유지
• 치료 여정의 연속성을 강조하는 메시지 구성

4.4 동기부여 요소

• 긍정적인 변화와 성과를 강조
• 작은 성취도 인정하고 격려

4.5 템플릿 변수 사용 가이드

변수가 없는 템플릿 (예: SLEEPQ_INTRO)

-- DB 템플릿 정의
INSERT INTO message_templates (template_id, variables)
VALUES ('SLEEPQ_INTRO_TITLE', '{}'::jsonb);

INSERT INTO message_template_translations (template_id, language, template)
VALUES ('템플릿ID', 'ko', '슬립큐에 오신 것을 환영합니다');

// 코드에서 사용
const template = await contextProvider.getMessageTemplate('SLEEPQ_INTRO_TITLE');
const rendered = contextProvider.renderTemplate(template); // 변수 없이 호출
// 결과: "슬립큐에 오신 것을 환영합니다"

변수가 있는 템플릿 (예: SLEEP_RECORD_REMINDER)

-- DB 템플릿 정의
INSERT INTO message_templates (template_id, variables)
VALUES ('SLEEP_RECORD_REMINDER',
  '{"userName": "string", "daysSince": "number"}'::jsonb);

INSERT INTO message_template_translations (template_id, language, template)
VALUES ('템플릿ID', 'ko',
  '{{userName}}님, 오늘의 수면은 어떠셨나요? 마지막 기록이 {{daysSince}}일 전입니다.');

// 코드에서 사용
const template = await contextProvider.getMessageTemplate('SLEEP_RECORD_REMINDER');
const variables = { userName: '홍길동', daysSince: 3 };
const rendered = contextProvider.renderTemplate(template, variables);
// 결과: "홍길동님, 오늘의 수면은 어떠셨나요? 마지막 기록이 3일 전입니다."

변수 처리 규칙

• 템플릿에 변수가 없으면 원본 그대로 반환
• 변수가 null/undefined면 빈 문자열로 치환
• 모든 변수 값은 문자열로 변환되어 치환됨

5. Agent Board와의 인터페이스

Agent Treatment Flow는 이러한 메시지를 생성하여 Agent Board에 전달합니다:

interface TreatmentMessageDelivery {
  message: TreatmentMessage; // 위에서 정의한 메시지 중 하나
  deliveryInstructions: {
    targetUserId: string;
    deliveryTime: 'immediate' | 'queued';
    displayRules: DisplayRules;
  };
  metadata: {
    generatedAt: Date;
    generatedBy: string; // 생성 모듈
    triggerEvent: string; // 생성 트리거
    version: string;
  };
}

Agent Board는 이 메시지를 받아 사용자에게 효과적으로 표시하고, 상호작용 결과를 다시 Agent Treatment Flow에 피드백합니다.

6. 변경 이력

버전	날짜	작성자	변경 내용
1.0.0	2025-01-03	bok@weltcorp.com	최초 작성 - 9가지 Agent 메시지 유형 정의
1.1.0	2025-01-03	bok@weltcorp.com	치료적 Task 메시지 추가 - 총 10가지 메시지 유형