English Speaking Practice — CSCL TBLT

LiveKit 기반 AI 영어 대화 실습 시스템. TBLT(Task-Based Language Teaching) 방식으로, AI 캐릭터 Kate와 과업 기반 영어 대화를 수행하는 실시간 음성 대화 에이전트. 대상: 한국어권 학생.

관리자는 /admin에서 수업 운영 모드를 선택할 수 있다.

그룹 대화 모드 (pipeline): 학생 n명 + 에이전트 1명의 STT → LLM → TTS 파이프라인. 에이전트 이름: pipeline-agent
개별 대화 모드 (realtime): 학생 1명 + 에이전트 1명의 OpenAI Realtime speech-to-speech 파이프라인. 에이전트 이름: realtime-agent, role: dominant 또는 collaborative

프로젝트 구조

CSCL_TBLT/
├── .env                  # API 키 (직접 입력 필요, git 추적 안 됨)
├── .env.example          # 환경변수 템플릿
├── .github/
│   └── workflows/
│       ├── agent-tests.yml            # agent/ 테스트 CI
│       └── client-build-and-test.yaml # client/ 빌드/린트 CI
│
├── agent/                # AI 음성 에이전트 (LiveKit Agents Python SDK)
│   ├── main.py           # 에이전트 진입점 (CLI 지원)
│   ├── prompt_pipeline.py # 그룹 대화 모드 시스템 프롬프트
│   ├── prompt_realtime.py # 개별 대화 모드 시스템 프롬프트
│   ├── logger.py         # 대화 JSON 로거
│   ├── pyproject.toml
│   ├── uv.lock
│   └── tests/
│       └── test_conversation.py  # LLM 단독 대화 흐름 테스트
│
├── server/               # legacy static 클라이언트용 토큰 발급 서버 (FastAPI)
│   ├── main.py           # GET /token, POST /dispatch
│   ├── pyproject.toml
│   └── uv.lock
│
├── client/               # Next.js 브라우저 클라이언트
│   ├── app/              # Next.js App Router + API routes
│   ├── components/       # 로비, 관리자, LiveKit UI 컴포넌트
│   ├── static/           # legacy 심플 클라이언트 (HTML/JS)
│   │   ├── index.html
│   │   ├── app.js
│   │   └── style.css
│   └── .env.local        # Next.js용 환경변수 (git 추적 안 됨)
│
├── config.example.json   # 로컬 fallback/import용 운영 설정 예시
├── config.json           # 로컬 fallback 운영 설정 (git 추적 안 됨)
└── logs/                 # 대화 로그 JSON (자동 생성, git 추적 안 됨)

브랜치 전략

이 저장소는 main / develop 기준으로 운영한다.

브랜치	역할	운영 원칙
`main`	실제 서버 배포와 연결되는 안정 브랜치	배포 가능한 상태만 유지한다. 검증된 변경만 병합하고, 미완성 실험은 올리지 않는다.
`develop`	기능 개발과 실험 통합 브랜치	새 기능, UI/프롬프트 실험, 검증 전 변경의 기본 합류 지점으로 사용한다.

기본 흐름:

새 작업은 develop에서 feature/..., issue-..., experiment/... 브랜치를 만든다.
일반 변경은 작업 브랜치에서 develop으로 PR을 열어 합친다.
배포할 묶음이 안정화되면 develop에서 main으로 PR을 열어 합친 뒤 실제 서버에 배포한다.
운영 장애나 긴급 수정은 main에서 hotfix/... 브랜치를 만들고, 배포 후 같은 수정이 develop에도 반영되도록 한다.

아키텍처

현재 기본 구조: Next.js 클라이언트

브라우저 클라이언트 (client/ Next.js)
    │
    ├─[GET /api/rooms]──────────────► Supabase app_settings + LiveKit room 조회
    ├─[POST /api/admin/config]──────► Supabase app_settings에 운영 설정 저장
    ├─[POST /api/token]─────────────► LiveKit 참가자 토큰 발급
    │                                  room_config.agents로 agent 자동 배치
    │
    └─[WebRTC 연결]────────────────► LiveKit Cloud
                                      │
                                      ├─ pipeline-agent: STT → LLM → TTS
                                      └─ realtime-agent: OpenAI Realtime

Next.js 클라이언트 (client/): 학생 로비, 관리자 설정, 관리자 대시보드, 토큰 발급 API를 포함한다.
AI 에이전트 (agent/): 같은 코드에서 pipeline-agent, realtime-agent worker를 실행한다. Realtime role은 dominant 또는 collaborative로 선택한다.
legacy 토큰 서버 (server/): client/static HTML 클라이언트용이다. 현재 Next.js 앱 실행에는 필요하지 않다.

수업 운영 모드

모드	UX 표시명	Room 정책	Agent	음성 처리
`pipeline`	그룹 대화 모드	`12반-1그룹` 같은 그룹 room	`pipeline-agent`	STT `deepgram/nova-3` → LLM `openai/gpt-4.1-mini` → TTS `cartesia/sonic-3`
`realtime`	개별 대화 모드	`realtime-{반}-{학생명}-{suffix}` 자동 생성	`realtime-agent`	OpenAI Realtime speech-to-speech

사전 준비

1. uv 설치 (없는 경우)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. `.env` 작성

cp .env.example .env
cp config.example.json config.json

config.json은 Supabase가 설정되지 않은 로컬 개발 fallback 및 초기 import 참고용이다. Production 운영 설정은 Supabase app_settings에 저장된다.

.env 파일에 값 입력:

# LiveKit Cloud (https://cloud.livekit.io → 프로젝트 생성 후 발급)
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_api_key
LIVEKIT_API_SECRET=your_api_secret

# 채팅방 및 에이전트 이름
ROOM_NAME=english-practice
AGENT_NAME=pipeline-agent
AGENT_WORKER_MODE=pipeline
AGENT_ROLE=dominant

# Realtime 모드에는 OPENAI_API_KEY가 필요
# Pipeline 모드는 LiveKit Inference를 사용하면 OPENAI_API_KEY / DEEPGRAM_API_KEY 없이도 동작
OPENAI_API_KEY=
DEEPGRAM_API_KEY=

Next.js 앱의 운영 모드는 .env가 아니라 Supabase app_settings.agent_mode로 결정되며, /admin에서 변경한다. Supabase가 없는 로컬 개발 환경에서는 config.json fallback을 사용할 수 있다. Realtime 상호작용 role은 관리자 전용 agentRole 설정으로만 노출된다.

3. 에이전트 모델 파일 다운로드 (최초 1회)

cd agent
uv sync
uv run python main.py download-files

실행 방법

현재 Next.js 앱 실행

최초 1회 의존성을 설치한다.

pnpm setup

루트에서 다음 명령 하나로 agent worker와 Next.js 클라이언트를 함께 실행한다. pnpm dev의 auto 모드는 로컬 프로세스 선택을 위해 config.json의 agentMode/agentRole을 읽는다. 앱 route의 런타임 운영 설정은 Supabase app_settings를 사용하며, Supabase가 없는 로컬 fallback 환경에서는 config.json 값을 사용한다.

pnpm dev

브라우저에서:

학생 로비: http://localhost:3000
관리자 설정: http://localhost:3000/admin
관리자 대시보드: http://localhost:3000/admin/dashboard

Next.js 클라이언트는 자체 /api/token 라우트를 가지므로 server/ FastAPI 토큰 서버가 필요 없다.

개별 대화 모드 worker로 실행하려면 다음 명령을 사용한다.

pnpm dev:realtime

collaborative 조건으로 실행하려면 다음 명령을 사용한다.

pnpm dev:realtime:collaborative

pipeline, realtime dominant, realtime collaborative worker를 모두 함께 띄우려면 다음 명령을 사용한다.

pnpm dev:all

/admin에서 개별 대화 모드와 상호작용 방식을 선택하면 학생은 조건명을 보지 않고 개별 room으로 입장한다.

기존처럼 터미널을 나눠 실행해야 할 때는 다음 개별 명령을 사용할 수 있다.

pnpm dev:agent:pipeline
pnpm dev:client

legacy static 클라이언트 실행 (선택)

client/static을 사용할 때만 FastAPI 토큰 서버가 필요하다.

# 터미널 1 — legacy 토큰 서버
cd server
uv sync
uv run python -m uvicorn main:app --port 8000 --reload

# 터미널 2 — pipeline-agent
cd agent
AGENT_WORKER_MODE=pipeline uv run python main.py dev

# 터미널 3 — static HTML 클라이언트
cd client/static
python -m http.server 3000

브라우저에서 http://localhost:3000 접속 → 이름 입력 → 입장 → 🤖 에이전트 생성 버튼 클릭.

CLI 단독 실험 (브라우저/프론트엔드 없이)

에이전트를 터미널에서 직접 실행해 백엔드만 빠르게 실험할 수 있습니다. 마이크와 스피커만 있으면 되고, 토큰 서버와 클라이언트는 불필요합니다.

cd agent

# 터미널 음성 대화 모드 (마이크로 말하고 스피커로 듣기)
uv run python main.py console

# 프론트엔드 연결 대기 모드 (토큰 서버·클라이언트와 함께 사용)
uv run python main.py dev

# 프로덕션 모드
uv run python main.py start

명령	설명	필요한 것
`console`	터미널 단독 음성 대화	마이크, 스피커
`dev`	프론트엔드 연결 대기 (자동 재시작)	Next.js 클라이언트
`start`	프로덕션 실행	Next.js 클라이언트
`download-files`	VAD 등 ML 모델 다운로드	—

Next.js 클라이언트

client/.env.local에 LiveKit 자격증명이 필요하다.

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_api_key
LIVEKIT_API_SECRET=your_api_secret

# Supabase admin auth / persistent state migration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
SUPABASE_SECRET_KEY=sb_secret_...

Next.js API routes:

Route	역할
`POST /api/token`	참가자 토큰 발급, 현재 운영 모드에 맞는 agent 자동 배치
`GET /api/rooms`	활성 반의 그룹 room과 realtime 개별 room 현황 조회
`GET/POST /api/admin/config`	Supabase `app_settings` 읽기/쓰기
`GET/POST /api/dispatch`	그룹 대화 모드에서 `pipeline-agent` 수동 배치/존재 확인
`POST /api/rooms/terminate`	room 강제 종료
`GET /api/logs`, `GET /api/logs/stream`	대화 로그 목록/스트리밍

주의: Production에서 /admin, /api/admin, 관리자성 API(/api/dispatch, /api/logs, /api/rooms/terminate)는 Supabase Auth session과 profiles.role = 'admin' 권한으로 보호된다. ADMIN_USERNAME/ADMIN_PASSWORD Basic Auth는 더 이상 사용하지 않는다.

Supabase runtime storage

Supabase 도입은 GitHub issue #4의 단계별 작업으로 진행한다. 현재 admin auth와 수업 운영 설정은 Supabase를 사용한다.

client/lib/supabase/client.ts: browser/client component용 Supabase client
client/lib/supabase/server.ts: server component, route handler, server action용 cookie-aware client
client/lib/supabase/admin.ts: 서버 전용 secret-key client
client/lib/supabase/proxy.ts: Auth session refresh와 admin route guard용 proxy/middleware helper
client/lib/settings-store.ts: app_settings 기반 운영 설정 store와 local fallback adapter
supabase/config.toml: 로컬 Supabase CLI 실행 포트와 migration 설정
supabase/migrations/20260611000000_foundation.sql: 초기 schema와 RLS policy
supabase/migrations/20260612000000_realtime_prompt_version_rpc.sql: active prompt version 교체 RPC

초기 schema는 다음 테이블을 만든다.

Table	역할
`profiles`	Supabase Auth 사용자별 앱 권한 및 표시명
`app_settings`	수업 운영 설정 저장소
`realtime_prompt_versions`	Realtime prompt override version 저장소

최초 admin은 Supabase Auth 사용자 생성 후 SQL 또는 dashboard에서 profiles.role = 'admin'으로 부여한다.

insert into public.profiles (user_id, role, display_name)
values ('<auth-user-id>', 'admin', 'Admin')
on conflict (user_id) do update
set role = 'admin',
    display_name = excluded.display_name;

SUPABASE_SECRET_KEY는 RLS를 우회할 수 있으므로 server-only 코드에서만 사용한다. Next.js API routes는 client/.env.local에서 이 값을 읽고, Python realtime agent는 root .env에서 같은 URL/secret을 읽어 promptVersionId에 해당하는 realtime_prompt_versions row를 가져온다.

관리자 로그인 화면은 /admin/login이다. 로그인은 Supabase email/password 계정을 사용하며, 계정의 profiles.role이 admin이어야 /admin 및 관리자성 API를 사용할 수 있다.

기존 config.json 값을 Supabase로 옮길 때는 다음 형태로 app_settings 기본 row를 seed한다.

insert into public.app_settings (
  id,
  num_classes,
  num_groups_per_class,
  class_start,
  active_class,
  agent_mode,
  agent_role,
  feedback_condition_id,
  realtime_resetting
)
values (
  'default',
  4,
  12,
  9,
  9,
  'realtime',
  'collaborative',
  'explicit_correction',
  false
)
on conflict (id) do update
set num_classes = excluded.num_classes,
    num_groups_per_class = excluded.num_groups_per_class,
    class_start = excluded.class_start,
    active_class = excluded.active_class,
    agent_mode = excluded.agent_mode,
    agent_role = excluded.agent_role,
    feedback_condition_id = excluded.feedback_condition_id,
    realtime_resetting = excluded.realtime_resetting;

Production에서는 client/.env.local과 root .env에 Supabase 연결값이 필요하다. Next.js에는 NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, SUPABASE_SECRET_KEY가 필요하고, Python realtime agent에는 NEXT_PUBLIC_SUPABASE_URL 또는 SUPABASE_URL과 SUPABASE_SECRET_KEY 또는 SUPABASE_SERVICE_ROLE_KEY가 필요하다. Supabase가 미설정이거나 DB 장애가 있으면 운영 설정 route는 setup/runtime error를 반환한다. 로컬 개발에서는 Supabase가 없거나 일시적으로 실패할 때 config.json fallback을 사용한다.

기존 prompt_config.json override는 supabase/README.md의 realtime_prompt_versions Migration 절차로 한 번만 active version row로 이관한다. 이관 후 Realtime custom prompt source of truth는 Supabase prompt version row다. /api/token은 active row의 promptVersionId를 LiveKit metadata에 넣고, Python realtime agent는 그 id로 같은 row를 fetch한다. promptVersionId가 없는 default session은 tracked markdown prompt를 사용한다.

로컬 Supabase CLI는 기존 프로젝트와 기본 포트가 충돌하지 않도록 5532x 대역을 사용한다.

supabase start
supabase db reset --no-seed
supabase status

client/.env.local에서 로컬 Supabase를 사용할 때는 supabase status 출력의 key를 넣는다.

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:55321
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<publishable-key-from-supabase-status>
SUPABASE_SECRET_KEY=<secret-key-from-supabase-status>

Studio는 http://127.0.0.1:55323, Postgres는 postgresql://postgres:postgres@127.0.0.1:55322/postgres에서 열린다.

관리자 설정

/admin에서 다음 값을 관리한다.

설정	저장 위치	설명
수업 운영 모드	`app_settings.agent_mode`	`pipeline` 또는 `realtime`
현재 수업 중인 반	`app_settings.active_class`	학생 로비에 표시되는 반
반 번호 시작	`app_settings.class_start`	반 번호 범위의 시작
전체 학급 수	`app_settings.num_classes`	관리자 화면에 표시할 반 개수
반당 그룹 수	`app_settings.num_groups_per_class`	그룹 대화 모드에서 표시할 그룹 수

예시:

{
  "numClasses": 4,
  "numGroupsPerClass": 12,
  "classStart": 9,
  "activeClass": 12,
  "agentMode": "pipeline"
}

테스트

에이전트 LLM 동작 테스트

마이크·브라우저 없이 LLM만 사용해 대화 흐름을 자동 검증합니다.

cd agent
uv run pytest tests/ -v

테스트 내용 (tests/test_conversation.py):

5턴 대화 흐름 검증 (주말 약속 만들기 태스크)
문법 오류 발화에 대한 Kate의 자연스러운 반응 확인
역질문(주말 활동)에 대한 응답 확인

관리자 모니터링

Next.js 클라이언트가 실행 중일 때 브라우저에서 아래 주소에 접속하면 세션 로그를 확인할 수 있습니다.

http://localhost:3000/admin/dashboard

저장된 세션 목록 확인
세션별 대화 로그 확인
참가자 이름, 발화 시각, 역할(User/Agent) 표시

legacy static 클라이언트를 사용할 때는 client/static/admin.html을 사용할 수 있다.

대화 로그

대화가 끝나면 logs/ 폴더에 JSON 파일로 자동 저장됩니다. root .env에서 LOG_PROMPT_STACK=true를 설정하면 각 Realtime 세션의 전체 resolved prompt stack이 metadata.prompt_stack에 함께 저장되고 /admin/dashboard에서 접어서 확인할 수 있습니다. 기본값은 off입니다.

logs/
└── RM_9GkS7d8BWCsf--260409_14:23.json

파일명 형식: {session_id}_{started_at}.json

{
  "session_id": "RM_9GkS7d8BWCsf",
  "room": "english-practice",
  "entries": [
    {
      "timestamp": "2026-04-09T14:23:05",
      "role": "user",
      "text": "Hello!",
      "participant_identity": "user_1234",
      "participant_name": "고준보"
    },
    {
      "timestamp": "2026-04-09T14:23:07",
      "role": "agent",
      "text": "Hi! How are you today?"
    }
  ]
}

주요 설정

항목	위치
Realtime AI 시스템 프롬프트 수정	기본값은 `prompts/realtime/*.md`, 런타임 수정은 `/admin`에서 Supabase `realtime_prompt_versions`로 저장
기본 AI 시스템 프롬프트 fallback	그룹 대화는 `agent/prompt_pipeline.py`, 개별 대화는 `prompts/realtime/*.md`
그룹 대화 모드 모델 변경	`agent/main.py` (STT `deepgram/nova-3`, LLM `openai/gpt-4.1-mini`, TTS `cartesia/sonic-3`)
개별 대화 모드 모델 변경	`agent/main.py` (`openai.realtime.RealtimeModel`)
실행할 worker 모드	`AGENT_WORKER_MODE=pipeline` 또는 `AGENT_WORKER_MODE=realtime` + `AGENT_ROLE=dominant/collaborative`
수업 운영 모드 변경	`/admin` 또는 Supabase `app_settings.agent_mode`
Realtime 상호작용 role 변경	`/admin` 또는 Supabase `app_settings.agent_role`
토큰 서버 포트 변경	`server/main.py` + `client/static/app.js` 상단 `SERVER` 변수
legacy static Room 이름 변경	`.env` → `ROOM_NAME`
에이전트 이름 변경	`agent/main.py`, `client/lib/agent-role.ts` (`pipeline-agent`, `realtime-agent`)
로그 저장 위치 변경	`agent/logger.py` → `LOGS_DIR`

Realtime 기본 프롬프트를 수정할 때는 prompts/realtime/ 아래의 문서형 프롬프트를 수정합니다. agent와 admin 기본값은 이 md 파일들을 직접 읽습니다.

pnpm prompts:check

원본 파일은 base.md, roles/dominant.md, roles/collaborative.md, condition-combinations/*.md, task-cards/*.md입니다. Realtime runtime stack은 base prompt, role prompt, role/feedback condition-combination prompt, task card 순서로 조합됩니다. task-cards/manifest.json에 등록된 주제별 task card 중 /admin에서 선택한 항목이 개별 Realtime 세션에 적용됩니다. pnpm prompts:check는 파일 누락이나 빈 파일 같은 기본 오류를 검사합니다.

/admin에서 프롬프트를 저장하면 Supabase realtime_prompt_versions에 새 version row가 생성되고 해당 row만 active가 됩니다. active custom version은 prompts/realtime/*.md 기본값보다 우선하며, base/role prompt와 함께 conditionCombinationPrompts, feedbackConditionId, taskCardId, taskCardPrompt snapshot을 보존합니다. feedbackPrompt는 legacy metadata로 남아 있지만 runtime stack에는 삽입되지 않습니다. md 기본값을 다시 쓰려면 /admin에서 "기본값으로 복원"을 실행해 active custom version을 비활성화합니다.

단일 문서에서 복사한 프롬프트를 한 파일로 검사기에 넘길 수도 있습니다. 이 경우 검사기는 # BASE PROMPT:, # INTERLOCUTOR ROLE PROMPT: Dominant, # INTERLOCUTOR ROLE PROMPT: Collaborative, # TASK CARD: 헤딩을 기준으로 네 구간을 나눕니다.

pnpm dev, pnpm build, pnpm start, pnpm dev:agent:*, 프로덕션 배포 스크립트는 실행 전에 prompts:check와 같은 검사를 수행합니다.

프로덕션 배포 (AWS EC2)

현재 production 기준값과 배포 절차는 docs/operations/를 따른다.

Production Environment: 현재 EC2, 서비스명, 운영 모드, 외부 서비스 기준값
Deployment Runbook: GitHub Actions 배포, 재시작, health check 절차
Capacity Plan: 평상시/실험일 인스턴스와 Realtime 동시 세션 기준
Incident Checklist: 장애 확인 순서와 주요 로그

요약:

항목	현재 기준
Production domain	`https://tblt-agent.net/`
App path	`/opt/cscl-tblt`
Client	PM2 `cscl-client`, port `3000`
Agent	systemd `cscl-agent.service`
Operation mode source of truth	Supabase `app_settings`
Current production mode	`realtime`
Deploy script	`scripts/deploy-production.sh`
Health check	`https://tblt-agent.net/api/health`

CI/CD 파이프라인

GitHub Actions는 세 종류로 구성한다.

Workflow	Trigger	역할
`pre-commit`	PR/push → `main`, `develop`, 수동 실행	공통 파일 형식 및 repo guardrail 검사
`CI`	PR → `main`, `develop`, 수동 실행	Client lint/format/build, Agent tests
`Deploy Production`	`main` push 또는 수동 실행	검증 후 EC2 production 배포

Production 배포는 GitHub Actions가 SSH로 EC2에 접속해 scripts/deploy-production.sh를 실행한다.

필요한 GitHub Environment/Secrets:

이름	종류	설명
`PROD_SSH_HOST`	Secret	EC2 host 또는 IP
`PROD_SSH_USER`	Secret	배포 SSH 사용자, 예: `ubuntu`
`PROD_SSH_KEY`	Secret	배포용 private key
`PROD_SSH_PORT`	Secret	SSH port, 기본값 `22`
`PROD_APP_DIR`	Environment variable	서버 repo 경로, 기본값 `/opt/cscl-tblt`

서버 조건:

/opt/cscl-tblt가 Git checkout이어야 한다.
배포 사용자가 systemctl restart/is-active cscl-agent를 password 없이 실행할 수 있어야 한다.
pnpm, uv, pm2, curl이 설치되어 있어야 한다.
서버의 .env, client/.env.local, config.json, prompt_config.json은 배포 중 백업 후 복원된다.
config.json은 git 추적 대상이 아니며, Supabase가 없는 로컬 fallback/import 용도로만 사용한다.
Production에서는 client/.env.local에 NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, SUPABASE_SECRET_KEY가 있어야 한다. Realtime custom prompt를 쓰는 agent host의 root .env에도 Supabase URL과 server-only secret이 있어야 한다.
Production 운영 설정은 Supabase app_settings(id = 'default') row에 저장된다.
최초 admin 계정은 Supabase Auth 사용자 생성 후 profiles.role = 'admin'으로 bootstrap해야 한다.

배포 후 health check:

cscl-agent active 확인
cscl-client PM2 process 확인 및 재시작
http://localhost:3000/api/health 응답 확인

main에 merge되면 배포가 바로 실행되므로, GitHub branch protection에서 pre-commit, CI / Client, CI / Agent를 required check로 설정한다.

서비스 상태 확인

# Agent 상태
sudo systemctl status cscl-agent
sudo journalctl -u cscl-agent --no-pager | tail -30

# Client 상태
pm2 list
pm2 logs cscl-client --lines 30

# nginx 상태
sudo systemctl status nginx
sudo nginx -t

현재 구현 메모

항목	내용
운영 모드 저장	Supabase `app_settings.agent_mode`에 `pipeline` 또는 `realtime` 저장
Realtime 상호작용 role 저장	Supabase `app_settings.agent_role`에 `dominant` 또는 `collaborative` 저장
Agent entrypoint	`agent/main.py`에 `pipeline-agent`, `realtime-agent` 등록
프롬프트 분리	그룹 대화는 `agent/prompt_pipeline.py`, 개별 대화 기본값은 `prompts/realtime/*.md`
Realtime 의존성	`livekit-agents[openai,silero,turn-detector]~=1.5`
Egress 업로드	`S3_ENDPOINT` 값이 `http`로 시작하는 경우만 endpoint로 사용

음성 녹음 (Egress)

세션 시작 시 자동으로 LiveKit Egress API가 호출되어 모든 참가자(학생 + AI) 음성이 혼합된 MP3 파일이 S3에 저장됩니다.

저장 경로: s3://tblt-agent-recordings/recordings/{룸명}-{LiveKit room SID}-{타임스탬프}.mp3
트리거: session.start() 직후 자동 시작
종료: 룸 disconnected 이벤트 발생 시 자동 종료
관련 코드: agent/egress_recorder.py

음성 녹음 (Egress) 다운로드 방법

로컬 다운로드: scripts/download_s3_recordings.sh [output_dir]
날짜 필터: SINCE_YYYYMMDD=20260701 scripts/download_s3_recordings.sh [output_dir]
삭제 dry run: BEFORE_YYYYMMDD=20260601 scripts/delete_s3_recordings.sh
실제 삭제: BEFORE_YYYYMMDD=20260601 APPLY=true scripts/delete_s3_recordings.sh
LastModified 기준 삭제: BEFORE_LAST_MODIFIED=2026-06-01T00:00:00Z scripts/delete_s3_recordings.sh

Egress는 LiveKit Cloud 인프라에서 실행되므로 서버 부하 없음. 단, S3 버킷 및 IAM 권한(s3:PutObject) 설정이 되어 있어야 함.

로컬 다운로드/삭제 스크립트 사용법

S3에 저장된 녹음 파일을 로컬로 받거나 정리할 때는 아래 스크립트를 사용한다.

사전 조건:

로컬에 AWS CLI(aws)가 설치되어 있어야 한다.
.env 또는 지정한 ENV_FILE에 최소한 다음 값이 있어야 한다.
- S3_BUCKET
- S3_REGION
- AWS_ACCESS_KEY 또는 AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
AWS IAM 권한:
- 다운로드: s3:ListBucket, s3:GetObject
- 삭제: s3:ListBucket, s3:DeleteObject

스크립트는 기본적으로 프로젝트 루트의 .env를 읽는다. 운영 서버의 값을 쓰고 싶으면 ENV_FILE=/opt/cscl-tblt/.env처럼 지정하면 된다.

`scripts/download_s3_recordings.sh`

전체 녹음 파일을 로컬 디렉터리로 다운로드한다.

scripts/download_s3_recordings.sh

기본 다운로드 경로는 ./downloads/recordings이다. 다른 경로로 받고 싶으면 첫 번째 인자로 넘긴다.

scripts/download_s3_recordings.sh ./tmp/recordings

파일명에 포함된 날짜 기준으로 특정 시점 이후만 받고 싶으면 SINCE_YYYYMMDD를 사용한다. 형식은 반드시 YYYYMMDD다.

SINCE_YYYYMMDD=20260701 scripts/download_s3_recordings.sh
SINCE_YYYYMMDD=20260601 scripts/download_s3_recordings.sh ./tmp/recordings

이 필터는 S3 LastModified가 아니라 파일명 규칙 recordings/{룸명}-{LiveKit room SID}-YYYYMMDD_HHMMSS.mp3의 날짜 부분을 기준으로 동작한다.

사용 가능한 환경변수:

ENV_FILE: 읽어올 env 파일 경로
S3_PREFIX: 기본값 recordings
SINCE_YYYYMMDD: 해당 날짜 이상인 파일만 다운로드
S3_ENDPOINT: Cloudflare R2, MinIO 같은 S3 호환 스토리지용 endpoint

`scripts/delete_s3_recordings.sh`

S3 객체 삭제는 실수 비용이 크므로 기본값이 dry run이다. APPLY=true를 주지 않으면 실제 삭제하지 않고 삭제 대상만 출력한다.

파일명 날짜 기준으로 특정 날짜 이전 파일을 확인:

BEFORE_YYYYMMDD=20260601 scripts/delete_s3_recordings.sh

파일명 날짜 기준으로 실제 삭제:

BEFORE_YYYYMMDD=20260601 APPLY=true scripts/delete_s3_recordings.sh

S3 객체의 LastModified 기준으로 특정 시각 이전 파일을 확인:

BEFORE_LAST_MODIFIED=2026-06-01T00:00:00Z scripts/delete_s3_recordings.sh

LastModified 기준 실제 삭제:

BEFORE_LAST_MODIFIED=2026-06-01T00:00:00Z APPLY=true scripts/delete_s3_recordings.sh

주의사항:

BEFORE_YYYYMMDD와 BEFORE_LAST_MODIFIED는 동시에 설정할 수 없다.
BEFORE_YYYYMMDD 형식은 YYYYMMDD다.
BEFORE_LAST_MODIFIED 형식은 UTC ISO-8601이어야 한다. 예: 2026-06-01T00:00:00Z
실제 삭제 전에 dry run 출력이 의도한 대상과 맞는지 먼저 확인하는 것이 좋다.

운영 서버 env를 직접 써서 삭제 대상을 확인하려면:

ENV_FILE=/opt/cscl-tblt/.env BEFORE_YYYYMMDD=20260601 scripts/delete_s3_recordings.sh

부하 및 사양 참고

그룹 대화 모드 기준: 동시 30명 = 약 15개 Agent 세션 (2인 1그룹)
그룹 대화 모드 병목: Silero VAD (10ms 단위 로컬 신경망 추론, 세션당 812% CPU)
그룹 대화 모드 STT/LLM/TTS: LiveKit Cloud inference에서 처리
개별 대화 모드: 학생 1명당 realtime Agent 세션 1개
개별 대화 모드에는 OpenAI Realtime 사용량과 동시 세션 한도 확인 필요
현재 production 기준은 Capacity Plan을 따른다.
t3 계열은 지속 고부하 수업 운영 시 CPU 크레딧 소진으로 스로틀링될 수 있다.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

English Speaking Practice — CSCL TBLT

프로젝트 구조

브랜치 전략

아키텍처

현재 기본 구조: Next.js 클라이언트

수업 운영 모드

사전 준비

1. uv 설치 (없는 경우)

2. `.env` 작성

3. 에이전트 모델 파일 다운로드 (최초 1회)

실행 방법

현재 Next.js 앱 실행

legacy static 클라이언트 실행 (선택)

CLI 단독 실험 (브라우저/프론트엔드 없이)

Next.js 클라이언트

Supabase runtime storage

관리자 설정

테스트

에이전트 LLM 동작 테스트

관리자 모니터링

대화 로그

주요 설정

프로덕션 배포 (AWS EC2)

CI/CD 파이프라인

서비스 상태 확인

현재 구현 메모

음성 녹음 (Egress)

음성 녹음 (Egress) 다운로드 방법

로컬 다운로드/삭제 스크립트 사용법

`scripts/download_s3_recordings.sh`

`scripts/delete_s3_recordings.sh`

부하 및 사양 참고

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

English Speaking Practice — CSCL TBLT

프로젝트 구조

브랜치 전략

아키텍처

현재 기본 구조: Next.js 클라이언트

수업 운영 모드

사전 준비

1. uv 설치 (없는 경우)

2. .env 작성

3. 에이전트 모델 파일 다운로드 (최초 1회)

실행 방법

현재 Next.js 앱 실행

legacy static 클라이언트 실행 (선택)

CLI 단독 실험 (브라우저/프론트엔드 없이)

Next.js 클라이언트

Supabase runtime storage

관리자 설정

테스트

에이전트 LLM 동작 테스트

관리자 모니터링

대화 로그

주요 설정

프로덕션 배포 (AWS EC2)

CI/CD 파이프라인

서비스 상태 확인

현재 구현 메모

음성 녹음 (Egress)

음성 녹음 (Egress) 다운로드 방법

로컬 다운로드/삭제 스크립트 사용법

scripts/download_s3_recordings.sh

scripts/delete_s3_recordings.sh

부하 및 사양 참고

2. `.env` 작성

`scripts/download_s3_recordings.sh`

`scripts/delete_s3_recordings.sh`