Browser (React + Agora RTC/RTM SDK)
  │
  ├── [1] POST /start-agent
  │         └── Supabase Edge Function
  │               └── Agora ConvoAI API (/v2/projects/{appId}/join)
  │
  ├── [2] Agora RTC 채널 (음성 + 트랜스크립트)
  │         ├── UID 100 — AI 에이전트
  │         └── UID 101 — 사용자
  │
  └── [3] Agora RTM (텍스트 메시지 전송 전용)

// npm 패키지 없이 HMAC-SHA256 + deflate로 직접 생성
const userToken = await buildToken(channel, USER_UID, APP_ID, APP_CERTIFICATE);
const agentToken = await buildToken(
  channel,
  AGENT_UID,
  APP_ID,
  APP_CERTIFICATE,
  agentRtmUid,
);

const payload = {
  name: channel,
  properties: {
    channel,
    token: agentToken,
    agent_rtc_uid: "100",
    agent_rtm_uid: "100-{channel}",
    llm: {
      url: "https://api.openai.com/v1/chat/completions",
      api_key: LLM_API_KEY,
      system_messages: [{ role: "system", content: prompt }],
      greeting_message: greeting,
      max_history: 32,
      params: { model: "gpt-4o-mini" },
    },
    asr: { vendor: "ares", language: "en-US" },
    tts: buildTtsConfig(TTS_VENDOR, TTS_KEY, TTS_VOICE_ID),
    turn_detection: {
      config: { end_of_speech: { mode: "semantic" } },
    },
    advanced_features: { enable_rtm: true }, // RTM 텍스트 전송을 쓰려면 필수
  },
};

// ConvoAI REST API 인증은 HTTP Basic 인증입니다.
// Customer ID와 Customer Secret을 콜론으로 결합 → Base64 인코딩 → "Basic <base64>"
const basicAuth = btoa(`${CUSTOMER_ID}:${CUSTOMER_SECRET}`);

await fetch(
  `https://api.agora.io/api/conversational-ai-agent/v2/projects/${APP_ID}/join`,
  {
    method: "POST",
    headers: { Authorization: `Basic ${basicAuth}` },
    body: JSON.stringify(payload),
  },
);

// Agora SDK는 브라우저 API 필요 → 반드시 동적 import
const AgoraRTC = (await import("agora-rtc-sdk-ng")).default;

const rtcClient = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" });

// ⚠️ 이벤트 리스너는 join() 전에 등록해야 합니다
rtcClient.on("user-published", async (user, mediaType) => {
  await rtcClient.subscribe(user, mediaType);
  if (mediaType === "audio") user.audioTrack?.play();
});

rtcClient.on("stream-message", (_uid, data) => {
  // 에이전트 트랜스크립트 수신 처리
  handleTranscript(data);
});

await rtcClient.join(appId, channel, token, uid);

// 마이크 트랙 생성 및 퍼블리시
const audioTrack = await AgoraRTC.createMicrophoneAudioTrack({
  AEC: true,
  ANS: true,
  AGC: true,
});
await rtcClient.publish(audioTrack);

RTC stream-message (여러 프레임, 순서 보장 X)
   │
   ▼  TextDecoder().decode(data)
"msgId|partIdx|partSum|base64data"   ← "|"로 4분할
   │
   ▼  msgId별 캐시에 청크 누적 + part_idx 정렬
cache[msgId] = [chunk0, chunk1, ... ]
   │
   ▼  chunks.length === partSum  (모든 청크 도착?)
   │        partSum === "???"(-1)면 "아직 미정" → 계속 대기
   ▼  YES
join → atob() → JSON.parse()
   │
   ▼
{ object, text, turn_id, ... }  → handleTranscript()

rtcClient.on("stream-message", (_uid, data) => {
  const raw = new TextDecoder().decode(data);
  const parts = raw.split("|");

  if (parts.length === 4) {
    // v2 포맷: messageId|partIdx|partSum|base64data
    const [msgId, partIdxStr, partSumStr, partData] = parts;
    const partIdx = parseInt(partIdxStr, 10);
    const partSum = partSumStr === "???" ? -1 : parseInt(partSumStr, 10);

    // 청크 누적
    if (!cache.has(msgId)) cache.set(msgId, []);
    const chunks = cache.get(msgId)!;
    chunks.push({ part_idx: partIdx, content: partData });
    chunks.sort((a, b) => a.part_idx - b.part_idx);

    // 모든 청크 수신 시 디코딩
    if (partSum !== -1 && chunks.length === partSum) {
      const base64 = chunks.map(c => c.content).join("");
      const msg = JSON.parse(atob(base64));
      // msg.object, msg.text, msg.turn_id 포함
      cache.delete(msgId);
    }
  }
});

const AgoraRTM = await import("agora-rtm");
const rtm = new AgoraRTM.default.RTM(appId, String(uid));
await rtm.login({ token });

// 메시지 전송
await rtm.publish(
  agentRtmUid,
  JSON.stringify({
    message: text,
    priority: "APPEND",
  }),
  {
    customType: "user.transcription",
    channelType: "USER",
  },
);

// start-agent payload에서 llm.url을 커스텀 서버로 변경
llm: {
  url: "https://your-server.com/rag/chat/completions",
  api_key: "",
  system_messages: [{ role: "system", content: "검색된 정보를 기반으로 답변하세요." }],
}

// RAG 서버 예시 흐름
app.post("/rag/chat/completions", async (req, res) => {
  res.setHeader("Content-Type", "text/event-stream");

  // 1. 대기 메시지 전송 (UX 개선)
  res.write(`data: ${JSON.stringify({ choices: [{ delta: { content: "잠시만요..." } }] })}\n\n`);

  // 2. 지식베이스에서 컨텍스트 검색
  const context = await retrieveFromKnowledgeBase(req.body.messages);

  // 3. 컨텍스트 포함해서 LLM 호출 후 스트리밍
  const completion = await openai.chat.completions.create({ stream: true, ... });
  for await (const chunk of completion) {
    res.write(`data: ${JSON.stringify(chunk)}\n\n`);
  }
  res.write("data: [DONE]\n\n");
});

// 1. Agora API로 에이전트 종료
await fetch(`/functions/v1/hangup-agent`, {
  method: "POST",
  body: JSON.stringify({ agentId }),
});

// 2. 브라우저에서 채널 퇴장
await rtmClient.logout();
localAudioTrack.close();
await rtcClient.leave();

APP_ID=xxx APP_CERTIFICATE=xxx LLM_API_KEY=xxx \
TTS_VENDOR=rime TTS_KEY=xxx TTS_VOICE_ID=astra \
node test-server.mjs

not-joined  →  joining  →  listening  →  talking  →  disconnected
  (기본)       (연결 중)    (대기 중)     (응답 중)      (종료)

// 볼륨을 100ms 간격으로 폴링해 talking 상태 감지
const volumeInterval = setInterval(() => {
  const volume = remoteAudioTrack.getVolumeLevel();
  if (volume > 0) setAgentState("talking");
  else setAgentState("listening");
}, 100);

// ⚠️ 반드시 정리: 메모리 누수 방지
return () => clearInterval(volumeInterval);

// turn_id 기준으로 메시지를 in-place 업데이트
setMessages(prev => {
  const existing = prev.find(m => m.id === turnId);
  if (existing) {
    // 기존 메시지 텍스트 업데이트 (append하지 않음)
    return prev.map(m =>
      m.id === turnId ? { ...m, text: transcript, isFinal } : m
    );
  }
  return [...prev, { id: turnId, role, text: transcript, isFinal }];
});

// ✅ 올바른 방식: 버튼 클릭 핸들러 내부에서 요청
async function handleStartCall() {
  // 권한 요청이 createMicrophoneAudioTrack() 내부에서 자동 발생
  const audioTrack = await AgoraRTC.createMicrophoneAudioTrack({
    AEC: true,  // 에코 제거 (스피커 소리가 마이크로 다시 들어가는 것 방지)
    ANS: true,  // 노이즈 억제 (키보드 소리, 주변 소음 제거)
    AGC: true,  // 자동 게인 조절 (목소리가 너무 작거나 클 때 자동 조절)
  });
}

// ❌ 피해야 할 방식: 페이지 로드 시 미리 요청
useEffect(() => {
  navigator.mediaDevices.getUserMedia({ audio: true }); // 사용자 경험 저하
}, []);

// 텍스트 입력: 연결된 상태에서만 노출
{isConnected && (
  <div className="text-input-area">
    <input placeholder="메시지 입력..." />
    <button>전송</button>
  </div>
)}

// System Prompt / 인사말 설정: 연결 중에는 비활성화
<button disabled={isConnected} onClick={openSettings}>
  설정
</button>

try {
  await joinChannel(config);
} catch (error) {
  // ❌ "Error: INVALID_TOKEN" / "TOKEN_EXPIRED"
  // ✅ 상황별 메시지로 변환
  if (error.code === "INVALID_TOKEN" || error.code === "TOKEN_EXPIRED") {
    setError("연결 토큰이 만료되었습니다. 다시 시도해 주세요.");
  } else if (error.name === "NotAllowedError") {
    setError("마이크 접근이 차단되어 있습니다. 브라우저 설정에서 허용해 주세요.");
  } else {
    setError("연결에 실패했습니다. 네트워크 상태를 확인해 주세요.");
  }
  setAgentState("disconnected");
}

// user-left 이벤트 = 에이전트가 채널에서 나갔음
rtcClient.on("user-left", (user) => {
  if (String(user.uid) === AGENT_UID) {
    setAgentState("disconnected");
    showToast("대화가 종료되었습니다. (일정 시간 동안 대화가 없었습니다)");
  }
});

idle_timeout: 300, // 5분으로 연장

async function leaveChannel() {
  // 1. 타이머 정리
  clearInterval(volumeIntervalRef.current);
  clearTimeout(deferredAudioFallbackRef.current);

  // 2. RTM 로그아웃
  await rtmClient.logout();

  // 3. 마이크 트랙 닫기 (하드웨어 해제)
  localAudioTrack.close(); // 이걸 빠뜨리면 탭을 닫을 때까지 마이크 표시등이 켜진 채로 남음

  // 4. RTC 채널 퇴장
  await rtcClient.leave();

  // 5. 상태 초기화
  setMessages([]);
  setIsConnected(false);
}

// ❌ 파일 상단 정적 import — SSR에서 크래시
import AgoraRTC from "agora-rtc-sdk-ng";

// ✅ async 함수 내부에서 동적 import
async function joinChannel() {
  const AgoraRTC = (await import("agora-rtc-sdk-ng")).default;
  const { default: AgoraRTM } = await import("agora-rtm");
  // ...
}