Una chat vocale
che puoi interrompere

Un'app web per una chiamata vocale dal vivo con un Managed Agent di Cartesia. Se parli sopra l'agente si ferma, e la trascrizione tiene solo le parole che ha detto davvero.

Distribuisci su Vercel Vedi su GitHub

Una chiamata in corso: l'agente ha salutato l'utente, l'utente ha chiesto perché le maree cambiano due volte al giorno, e la risposta dell'agente arriva in streaming sotto un badge verde Speaking, con i pulsanti Mute e End call sotto

Screenshot. Il template in esecuzione in locale.

Modelli: ink-2, sonic-3.6
Lingue: Inglese
Licenza: Apache-2.0
Stack: Next.js 16React 19shadcn/uiagents-web
Prodotti Cartesia: Managed AgentsInk 2Sonic 3.6

Cosa fa

Cartesia gestisce l'intero agente, quindi il tuo server ha un solo compito. Dà al browser un token di breve durata, e la tua chiave API non arriva mai alla pagina. Lo stesso agente può anche rispondere alle telefonate, come fa il template di receptionist Front desk.

Eseguilo tu

1
Installa
Esegui i comandi qui sotto con Node 22.22 o successivo. Funziona anche pnpm. npm run setup:agent crea l'agente con POST /v1/agents e non fa nulla se l'agente salvato esiste ancora. Vuoi fare il deploy? Eseguilo prima in locale, perché il pulsante di Vercel chiede l'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
Variabili d'ambiente
CARTESIA_API_KEY
play.cartesia.ai/keys
CARTESIA_AGENT_ID
Scritta da npm run setup:agent
AGENT_MODEL_ID
Opzionale. L'LLM dell'agente, da GET /v1/agents/models
CARTESIA_VOICE_ID
Opzionale. Una voce da play.cartesia.ai/voices
APP_PASSWORD
Opzionale in locale. Obbligatoria su Vercel, oppure none per rendere l'app pubblica
TRUST_PROXY
Opzionale. 1 se sei dietro un tuo reverse proxy
Avvia una chiamata
Apri http://localhost:3000 e premi Start call. Usa le cuffie. La cancellazione dell'eco è attiva, ma gli altoparlanti di un portatile finiscono comunque nel microfono e l'agente si interrompe da solo.

Crealo con il tuo agente di programmazione

Un prompt che dice al tuo agente di programmazione da dove partire e cosa leggere per primo.

Prompt

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.

Come funziona

MicrofonoPCM a 16 kHz sul WebSocket dell'agente, con la cancellazione dell'eco attiva

Ink 2Ti ascolta e decide quando il tuo turno è finito

LLMclaude-haiku-4.5 di default, si imposta con AGENT_MODEL_ID

Sonic 3.6Pronuncia la risposta mentre viene scritta

AltoparlanteScarta l'audio in coda quando interrompi

Perché funziona così

Interrompere svuota la coda audio

Quando parli sopra l'agente, Cartesia invia un evento audio_output_clear. L'app butta l'audio che aveva in coda e taglia l'ultimo messaggio dell'agente alle parole che ha detto davvero.

Il browser riceve un token da 60 secondi, non la tua chiave

Il server crea un token che funziona solo per le chiamate agli agenti e scade dopo 60 secondi. La route del token risponde 503 se manca la chiave API, e 429 dopo 10 token al minuto dallo stesso indirizzo.

Personalizzalo

Cambia cosa dice

Modifica le istruzioni e il saluto in scripts/prompt.ts, poi esegui npm run setup:agent -- --force.

Usa un'altra voce o un altro LLM

Imposta CARTESIA_VOICE_ID o AGENT_MODEL_ID ed esegui npm run setup:agent -- --force.

Parla in un'altra lingua

Imposta language.primary in buildBody in scripts/setup-agent.ts, scrivi il prompt in quella lingua e scegli una voce che la parli.

Unisciti ai team che passano a Cartesia

Al primo posto

nelle classifiche Speech Arena e Speech to Text di Artificial Analysis

Domande

Come tengo la mia chiave API Cartesia fuori dal browser?

Il tuo server crea un token di breve durata e dà al browser solo quello. Il token dura 60 secondi e funziona solo per le chiamate agli agenti, non per sintesi o trascrizione vocale. Il server ne distribuisce al massimo 10 al minuto per indirizzo.

Perché le mie parole compaiono solo dopo che ho smesso di parlare?

L'agente rimanda le tue parole alla fine del tuo turno, non mentre parli, quindi il tuo messaggio mostra dei puntini fino ad allora. Le parole dell'agente compaiono mentre parla. La ricetta mostra anche una versione in cui usi il tuo LLM, e lì le tue parole compaiono dal vivo mentre parli.

Quanto costa una chiamata?

Le chiamate con un Managed Agent costano 0,06 $ al minuto più i token dell'LLM. Sono fatturate in dollari, non sul tuo saldo di crediti Cartesia, e ogni LLM ha il suo prezzo per token.

Le chiamate vengono registrate?

Sì. Cartesia registra per impostazione predefinita l'audio e la trascrizione di ogni chiamata dell'agente. Avvisa i tuoi utenti e cancella le chiamate che non ti servono con l'API di Cartesia.

Esiste una guida passo passo per questo template?

Sì. La ricetta spiega il codice, il README copre configurazione, variabili d'ambiente e deploy, e la documentazione di Managed Agents spiega la parte di Cartesia.