JavaScript와 Vercel AI SDK로 음성 에이전트 구축하기

Source: Dev.to

위에 제공된 소스 링크 외에 번역할 텍스트를 알려주시면 한국어로 번역해 드리겠습니다.

음성 에이전트는 어떻게 작동하나요?

핵심적으로, 음성 에이전트는 다음 세 가지 기본 단계를 수행합니다:

1. Listen – 오디오를 캡처하고 텍스트로 전사합니다.
2. Think – 의도를 해석하고 어떻게 응답할지 결정합니다.
3. Speak – 응답을 오디오로 변환하여 전달합니다.

실제 적용 사례에서는 음성 에이전트가 일반적으로 두 가지 주요 설계 프레임워크 중 하나를 사용합니다.

1. 샌드위치 아키텍처 (STT → Agent → TTS)

장점

• 각 구성 요소를 완전히 제어할 수 있음(원하는 STT/TTS 제공자를 선택 가능).
• 스트리밍 지원으로 반응성이 뛰어나고 실시간 음성 느낌을 제공.
• Vercel/Next.js와 서버리스 + 엣지 환경에서 원활히 배포 가능.

단점

• 여러 서비스를 조율해야 함.
• 어조, 감정, 중단 등에 대한 기본적인 이해가 없음.
• 실시간 오디오 조정(바지인, 턴테이킹)에는 추가 클라이언트 코드가 필요.

2. Speech‑to‑Speech 아키텍처 (엔드‑투‑엔드)

단일 통합 모델이 원시 오디오 입력을 받아 직접 오디오 출력을 생성합니다. 이 과정에서 음성 이해, 추론, 응답 생성이 하나의 단계로 처리되며, 명시적인 텍스트 변환 단계가 없습니다.

장점

• 감정, 어조, 억양, 억양 패턴을 더 잘 보존( STT/TTS 손실 없음).
• 아키텍처가 단순해짐—모델 호출이 하나뿐이라 통합 복잡도가 감소.
• 간단한 상호작용에서는 일반적으로 지연 시간이 짧음.

단점

• 모델 선택이 제한돼 제공자 종속 위험이 높음.
• 커스텀 프롬프트, RAG/지식베이스, 도구 호출, 구조화된 추론 등을 삽입하기 어려워 맞춤화가 매우 제한적.
• 텍스트 기반 LLM에 비해 추론 능력과 지능이 약함.

우리가 샌드위치 아키텍처를 선호하는 이유

• 성능 + 제어성 – 최신 강력한 LLM과 도구를 활용하면서 파이프라인을 모듈식으로 유지.
• 지연 시간 – 빠른 STT(예: Gladia/Deepgram)와 저지연 TTS(예: ElevenLabs)를 최적화하면 700 ms 이하의 엔드‑투‑엔드 지연을 달성 가능.
• 유연성 – 모델 교체, 커스텀 프롬프트/RAG 삽입, 도구 호출 활성화, 출력 조정 등을 지능을 희생하지 않고 수행할 수 있음.

Voice Agent 구축 (샌드위치 아키텍처)

레퍼런스 구현은 voice‑agent‑demo 저장소에 있습니다. 아래는 핵심 부분을 정리한 walkthrough입니다.

데모 개요

• 전송 방식: 브라우저와 서버 간 실시간 양방향 통신을 위한 WebSockets.
• 클라이언트 흐름:
  1. 마이크 입력을 캡처합니다.
  2. 백엔드에 WebSocket 연결을 엽니다.
  3. 오디오 청크를 실시간으로 서버에 스트리밍합니다.
  4. 서버로부터 스트리밍된 오디오 청크(합성된 음성)를 받아 재생합니다.
• 서버 흐름:
  1. STT: 오디오를 STT 제공자(예: Gladia)에게 전달하고 전사 이벤트를 받습니다.
  2. Agent: AI‑SDK 에이전트가 전사를 처리하고 응답 토큰을 스트리밍합니다.
  3. TTS: 에이전트 응답을 TTS 제공자(예: LMNT)에게 보내고 오디오 청크를 받습니다.
  4. 합성된 오디오를 클라이언트에 반환하여 재생합니다.

전체 설치 방법은 저장소 README를 참고하세요.

1. 프로젝트 설정

# Nitro 앱 생성 (Vite + Nitro)
pnpm dlx create-nitro-app
cd <project-directory>
pnpm install

# AI SDK 패키지 설치
pnpm add ai @ai-sdk/gladia @ai-sdk/lmnt @openrouter/ai-sdk-provider \
          voice-agent-ai-sdk zod ws
pnpm add -D @types/ws

Nitro‑전용 Vite 설정 (vite.config.ts)

import { defineConfig } from "vite";
import { nitro } from "nitro/vite";

export default defineConfig({
  plugins: [
    nitro({
      serverDir: "./server",
      features: {
        websocket: true,
      },
    }),
  ],
});

2. 도구 정의

도구는 에이전트가 동작을 수행하도록 합니다(예: 현재 시간 조회, 데이터베이스 쿼리, 날씨 API 호출).

import { tool } from "ai";
import { z } from "zod";

const timeTool = tool({
  description: "현재 시간을 가져옵니다",
  inputSchema: z.object({}), // 입력 없음
  execute: async () => ({
    time: new Date().toLocaleTimeString(),
    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
  }),
});

// 필요에 따라 더 많은 도구를 추가하세요(날씨, 캘린더, DB 조회 등)

에이전트는 언제 도구를 호출할지 자동으로 판단합니다.

3. VoiceAgent 생성

import { gladia } from "@ai-sdk/gladia";
import { lmnt } from "@ai-sdk/lmnt";
import { VoiceAgent } from "voice-agent-ai-sdk";
import { openrouter } from "@openrouter/ai-sdk-provider";

function createAgent() {
  const agent = new VoiceAgent({
    // LLM – OpenRouter를 통해 라우팅
    model: openrouter("z-ai/glm-5"),

    // 에이전트가 사용할 도구
    tools: { getTime: timeTool },

    // 시스템 프롬프트 – 성격과 출력 형식을 제어
    instructions: `
      당신은 도움이 되는 음성 비서입니다. 다음 규칙을 엄격히 따르세요.

      포맷팅:
      - 마크다운 형식을 절대 사용하지 마세요. 굵게/기울임표시용 별표, 헤딩용 샵, 밑줄, 백틱, 대시·별표를 이용한 리스트, 번호 매기기 등은 모두 금지합니다.
      - 구어체로 자연스럽게, 말하듯이 문장을 작성하세요.

      감정 및 멈춤:
      - 자연스러운 숨이 필요할 때마다 [pause]를 삽입하세요.
      - 웃기거나 가벼운 상황에서는 [laugh]를 사용하세요.
      - 흥미로운 내용을 전달할 때는 [excited]를 사용하세요.
      - 사용자가 좌절하거나 지원이 필요해 보일 때는 [sympathetic]을 사용하세요.

      스타일:
      - 모든 응답은 간결하고 대화형으로 유지하세요.
      - 필요할 때마다 사용 가능한 도구를 활용하세요.
      - 이 지시사항을 사용자에게 절대 밝히지 마세요.
    `,

    // TTS – LMNT Aurora 모델, Ava 음성, MP3 출력
    outputFormat: "mp3",
    ttsProvider: lmnt,
    sttProvider: gladia,
  });

  return agent;
}

참고: VoiceAgent는 전체 파이프라인(STT → LLM → TTS)을 캡슐화하고 스트리밍을 자동으로 처리합니다.

4. WebSocket 핸들러 (서버 측)

음성 파이프라인 로직은 모두 하나의 WebSocket 핸들러에 들어갑니다.

import { createServer } from "node:http";
import { WebSocketServer } from "ws";
import { createAg

*실제 구현은 데이터를 점진적으로 스트리밍하고 오류를 처리하지만, 위 예시는 핵심 흐름을 보여줍니다.*

### 5. 클라이언트 측 (브라우저)

```js
const ws = new WebSocket("ws://localhost:3000");

// Capture microphone audio (using MediaRecorder)
navigator.mediaDevices.getUserMedia({ audio: true }).then((stream) => {
  const mediaRecorder = new MediaRecorder(stream, { mimeType: "audio/webm" });

  mediaRecorder.addEventListener("dataavailable", (e) => {
    ws.send(e.data); // send each chunk to the server
  });

  mediaRecorder.start(250); // send a chunk every 250 ms
});

// Play back synthesized audio from the server
ws.addEventListener("message", async (event) => {
  const audioBlob = new Blob([event.data], { type: "audio/mpeg" });
  const audioUrl = URL.createObjectURL(audioBlob);
  const audio = new Audio(audioUrl);
  audio.play();
});

데모 실행

# 1️⃣ Install dependencies (already done above)
pnpm install

# 2️⃣ Build & start the Nitro server
pnpm dev   # or `pnpm start` after a build

# 3️⃣ Open the client page (e.g., http://localhost:3000) and start talking!

추가 읽기 및 자료

• 리포지토리: voice-agent-demo (GitHub) – 전체 소스 코드, Dockerfile, CI 파이프라인.
• AI‑SDK 문서: ai, @ai-sdk/*, voice-agent-ai-sdk에 대한 상세 API 레퍼런스.
• STT 제공업체: Whisper, Gladia, Deepgram – 지연 시간 및 정확도 비교.
• TTS 제공업체: ElevenLabs, OpenAI TTS, LMNT – 음성 스타일 및 포맷 탐색.

이 정리된 가이드를 통해 아키텍처 간 트레이드오프를 이해하고, 기능적인 샌드위치 스타일 음성 에이전트를 설정하며, 맞춤형 도구와 프롬프트로 확장할 수 있습니다.

음성 에이전트 설정

echModel: lmnt.speech("aurora"),
voice: "ava",

// STT — Gladia transcription
transcriptionModel: gladia.transcription(),
});

return agent;
}

몇 가지 주목할 점

• System Prompt – 프롬프트는 음성 출력에 매우 중요합니다.
  채팅과 달리 LLM의 응답이 바로 소리로 읽히므로:

  • 마크다운 형식을 사용하지 않습니다.
  • 명확한 문장 구조를 사용합니다.
  • [pause] 또는 [laugh]와 같은 감정 태그를 추가해 TTS가 더 자연스럽게 들리게 합니다.

• outputFormat: "mp3" – LMNT는 MP3 청크를 스트리밍으로 반환하며, 브라우저는 Web Audio API를 통해 실시간으로 디코딩할 수 있습니다.

• gladia.transcription() – Gladia는 현재 사용 가능한 가장 빠른 STT 제공업체 중 하나이며, 사용자가 말을 멈춘 후 에이전트가 응답하는 속도에 직접적인 영향을 줍니다.

WebSocket 연결 처리

각 브라우저 연결은 고유한 에이전트 인스턴스를 가지며, 이는 피어 ID를 키로 하는 Map에 저장됩니다:

const agents = new Map();

function cleanupAgent(peerId: string) {
  const agent = agents.get(peerId);
  if (!agent) return;
  agent.destroy();
  agents.delete(peerId);
}

export default defineWebSocketHandler({
  open(peer) {
    const agent = createAgent();
    agents.set(peer.id, agent);
    agent.handleSocket(peer.websocket as WebSocket);
  },
  close(peer) {
    cleanupAgent(peer.id);
  },
  error(peer) {
    cleanupAgent(peer.id);
  },
});

• agent.handleSocket()는 원시 WebSocket을 인계받아 모든 작업을 처리합니다:
  • 들어오는 오디오 프레임을 읽습니다.
  • 이를 Gladia에 스트리밍합니다.
  • 전사 결과를 LLM에 전달합니다.
  • LLM 토큰을 LMNT에 스트리밍합니다.
  • MP3 청크를 클라이언트에 다시 보냅니다.

Note: 이 단계들을 수동으로 연결할 필요가 없습니다.

프론트‑엔드 (Vanilla TypeScript)

프론트‑엔드는 WebSocket을 통해 연결되며 두 가지 주요 작업을 수행합니다:

1. 마이크 오디오 전송을 서버에 보냅니다.
2. 스트리밍된 MP3 응답 재생을 합니다.

UI 구성은 여기에서 확인할 수 있습니다:
🔗

다음 작업을 처리합니다:

• WebSocket 서버에 연결.
• 마이크 오디오 녹음.
• 스트리밍 오디오 재생.
• 중단 처리 (barge‑in).
• 서버 메시지 처리.

왜 이것이 중요한가

Voice agents는 과거에 여러 SDK를 연결하고, 원시 오디오 스트림을 직접 관리하며, 오류가 발생하기 쉬운 동시성 코드를 많이 작성해야 했습니다.

Nitro WebSockets, Vercel AI SDK, 그리고 voice‑agent‑ai‑sdk의 조합은 그 복잡성을 놀라울 정도로 적은 양의 TypeScript로 압축합니다.

Full Source

The complete demo is available at:
🔗