Browser (React + Agora RTC/RTM SDK)
  │
  ├── [1] GET /session-config (사용자 RTC+RTM 토큰)
  │         └── Supabase Edge Function
  │
  ├── [2] RTC/RTM 연결 + transcript 구독
  │
  ├── [3] POST /start-agent
  │         └── Supabase Edge Function
  │               └── Agora ConvoAI API (/v2/projects/{appId}/join)
  │
  ├── [4] Agora RTC 채널 (양방향 음성)
  │         ├── UID 100 — AI 에이전트
  │         └── UID 101 — 사용자
  │
  └── [5] Agora Signaling/RTM (텍스트 입력 + 트랜스크립트·에이전트 이벤트)

// Agora 공식 AccessToken2(v007) 구현과 동일한 검증된 builder 사용
const userToken = await buildToken(
  channel,
  USER_UID,
  APP_ID,
  APP_CERTIFICATE,
  String(USER_UID),
);
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}",
    remote_rtc_uids: [String(USER_UID)],
    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 },
    parameters: { data_channel: "rtm" }, // 공식 Web transcript toolkit 경로
  },
};

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

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

const { agent_id: agentId } = await agoraResponse.json();

import {
  ConversationalAIAPI,
  EConversationalAIAPIEvents,
  ETranscriptHelperMode,
} from "@/conversational-ai-api";

// 클라이언트 경계에서 SDK 로드
const AgoraRTC = (await import("agora-rtc-sdk-ng")).default;
const AgoraRTM = (await import("agora-rtm-sdk")).default;
const { RTM } = AgoraRTM;

const rtcClient = AgoraRTC.createClient({ mode: "rtc", codec: "vp8" });
const rtmClient = new RTM(appId, String(uid));

ConversationalAIAPI.init({
  rtcEngine: rtcClient,
  rtmEngine: rtmClient,
  renderMode: ETranscriptHelperMode.TEXT,
});
const conversationalAIAPI = ConversationalAIAPI.getInstance();

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

await rtmClient.login({ token });
await rtcClient.join(appId, channel, token, uid);

conversationalAIAPI.subscribeMessage(channel);
conversationalAIAPI.on(
  EConversationalAIAPIEvents.TRANSCRIPT_UPDATED,
  (messages) => setMessages(messages),
);

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

const startResponse = await fetch("/functions/v1/start-agent", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ channel }),
});
if (!startResponse.ok) throw new Error(await startResponse.text());
const { agentId } = await startResponse.json();

const AgoraRTM = (await import("agora-rtm-sdk")).default;
const { RTM } = AgoraRTM;
const rtm = new 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, final } : m
    );
  }
  return [...prev, { id: turnId, role, text: transcript, final }];
});

// 버튼 클릭 핸들러 내부에서 요청
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) {
  // 원시 오류 문자열 대신 상황별 메시지로 변환
  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
async function joinChannel() {
  const AgoraRTC = (await import("agora-rtc-sdk-ng")).default;
  const { default: AgoraRTM } = await import("agora-rtm-sdk");
  // ...
}