말을 끊을 수 있는
음성 채팅

Q: 이 템플릿의 단계별 가이드가 있나요?

네. 레시피 에서 코드를 따라가며 설명하고, README 에서 설정, 환경 변수, 배포를 다루며, Managed Agents 문서 에서 Cartesia 쪽을 설명합니다.

Cartesia Managed Agent와 실시간 음성 통화를 하는 웹 앱입니다. 에이전트가 말할 때 끼어들면 멈추고, 대화 기록에는 실제로 말한 단어만 남습니다.

실시간 통화 화면. 에이전트가 인사했고, 사용자가 왜 하루에 두 번 밀물과 썰물이 바뀌는지 물었으며, 초록색 Speaking 배지 아래로 에이전트의 답변이 스트리밍되고 있습니다. 아래에 Mute와 End call 버튼이 있습니다

스크린샷. 로컬에서 실행 중인 템플릿입니다.

모델: ink-2, sonic-3.6
언어: 영어
라이선스: Apache-2.0
기술 스택: Next.js 16React 19shadcn/uiagents-web
Cartesia 제품: Managed AgentsInk 2Sonic 3.6

하는 일

에이전트 전체를 Cartesia가 실행하므로 서버가 하는 일은 하나입니다. 브라우저에 수명이 짧은 토큰을 건네며, API 키는 페이지에 닿지 않습니다. 같은 에이전트로 전화도 받을 수 있으며, 접수 담당 Front desk 템플릿에서 그 방법을 보여 줍니다.

직접 실행하기

1
설치
Node 22.22 이상에서 아래 명령어를 실행하세요. pnpm도 쓸 수 있습니다. npm run setup:agent가 POST /v1/agents로 에이전트를 만들며, 저장된 에이전트가 아직 있으면 아무것도 하지 않습니다. 배포한다면 먼저 로컬에서 실행하세요. Vercel 버튼이 이 id를 묻기 때문입니다.
npx degit cartesia-ai/cookbook/examples/voice-chat voice-chat cd voice-chat # add CARTESIA_API_KEY cp .env.example .env.local npm install # creates the agent, writes CARTESIA_AGENT_ID npm run setup:agent npm run dev
환경 변수
CARTESIA_API_KEY
play.cartesia.ai/keys
CARTESIA_AGENT_ID
npm run setup:agent가 기록
AGENT_MODEL_ID
선택 사항. 에이전트의 LLM, GET /v1/agents/models에서 확인
CARTESIA_VOICE_ID
선택 사항. play.cartesia.ai/voices의 음성
APP_PASSWORD
로컬에서는 선택 사항. Vercel에서는 필수이며, none으로 두면 앱이 공개됨
TRUST_PROXY
선택 사항. 자체 리버스 프록시 뒤에서는 1
통화 시작
http://localhost:3000을 열고 Start call을 누르세요. 헤드폰을 쓰세요. 에코 제거가 켜져 있지만 노트북 스피커 소리는 여전히 마이크로 들어가 에이전트가 스스로 말을 끊습니다.

코딩 에이전트로 만들기

어디서 시작하고 무엇을 먼저 읽어야 하는지 코딩 에이전트에게 알려 주는 프롬프트입니다.

프롬프트

Claude Code Cursor Codex

Build a browser voice chat with a Cartesia Managed Agent. Start from https://github.com/cartesia-ai/cookbook/tree/main/examples/voice-chat and follow its AGENTS.md for the commands, files and rules. The server route mints a 60 second access token with only the agent grant through @cartesia/cartesia-js (client.accessToken.create), and the browser opens wss://api.cartesia.ai/v1/agents/websocket/{agent_id} with useCartesiaAgent from lib/agents-web. Create the agent once with npm run setup:agent, which calls POST /v1/agents. The agent runs Ink 2 and Sonic 3.6 for you, so do not add TTS or STT model fields to its config. If I don't have a Cartesia API key yet, follow https://www.cartesia.ai/agent-quickstart.md to get one.

작동 방식

마이크에코 제거를 켠 상태로 에이전트 WebSocket을 통해 16 kHz PCM 전송

Ink 2내 말을 듣고 차례가 언제 끝났는지 판단

LLM기본값은 claude-haiku-4.5, AGENT_MODEL_ID로 변경

Sonic 3.6답변이 작성되는 대로 말함

스피커내가 끼어들면 대기 중인 오디오를 버림

이렇게 만든 이유

끼어들면 오디오 대기열이 비워집니다

에이전트가 말할 때 끼어들면 Cartesia가 audio_output_clear 이벤트를 보냅니다. 앱은 대기 중이던 오디오를 버리고, 에이전트의 마지막 메시지를 실제로 말한 단어까지로 자릅니다.

브라우저는 키가 아니라 60초짜리 토큰을 받습니다

서버는 에이전트 통화에만 쓸 수 있고 60초 뒤 만료되는 토큰을 만듭니다. 토큰 경로는 API 키가 없으면 503을, 한 주소에서 1분에 10개를 넘으면 429를 반환합니다.

원하는 대로 바꾸기

하는 말 바꾸기

scripts/prompt.ts의 지침과 인사말을 수정한 뒤 npm run setup:agent -- --force를 실행하세요.

다른 음성이나 LLM 사용

CARTESIA_VOICE_ID나 AGENT_MODEL_ID를 설정하고 npm run setup:agent -- --force를 실행하세요.

다른 언어로 대화

scripts/setup-agent.ts의 buildBody에서 language.primary를 설정하고, 그 언어로 프롬프트를 쓴 뒤 그 언어를 말하는 음성을 고르세요.

Cartesia로 전환하는 팀들과 함께하세요

1위

Artificial Analysis의 Speech Arena 및 Speech to Text 리더보드에서

자주 묻는 질문

Cartesia API 키를 브라우저에 노출하지 않으려면 어떻게 하나요?

서버에서 수명이 짧은 토큰을 만들어 브라우저에는 그것만 건네세요. 토큰은 60초 뒤 만료되고 에이전트 통화에만 쓸 수 있으며, 음성 합성이나 음성 인식에는 쓸 수 없습니다. 서버는 주소당 1분에 최대 10개까지만 발급합니다.

왜 말을 멈춘 뒤에야 내 말이 나타나나요?

에이전트는 내가 말하는 동안이 아니라 내 차례가 끝났을 때 내 말을 돌려주므로, 그때까지 내 메시지에는 점이 표시됩니다. 에이전트의 말은 말하는 대로 나타납니다. 레시피에는 내 LLM을 직접 쓰는 버전도 있으며, 그 버전에서는 말하는 동안 내 말이 실시간으로 나타납니다.

통화 비용은 얼마인가요?

Managed Agent 통화는 분당 $0.06에 LLM 토큰 비용이 더해집니다. Cartesia 크레딧 잔액이 아니라 달러로 청구되며, 토큰 가격은 LLM마다 다릅니다.

통화가 녹음되나요?

네. Cartesia는 기본으로 모든 에이전트 통화의 오디오와 기록을 녹음합니다. 사용자에게 알리고, 필요 없는 통화는 Cartesia API로 삭제하세요.

이 템플릿의 단계별 가이드가 있나요?

네. 레시피에서 코드를 따라가며 설명하고, README에서 설정, 환경 변수, 배포를 다루며, Managed Agents 문서에서 Cartesia 쪽을 설명합니다.