Un receptionist che risponde
a ogni chiamata

Q: Altre persone possono vedere le mie chiamate quando è online?

No, se imposti DASHBOARD_PASSWORD. Allora ogni pagina della dashboard e ogni registrazione chiedono quella password, e l'app si rifiuta di partire su un indirizzo pubblico senza.

Un receptionist con IA open source per una piccola attività. Un Managed Agent di Cartesia risponde al telefono. Un piccolo server Python gli dà gli strumenti per prenotare appuntamenti su Cal.com o su un calendario integrato, prendere messaggi e passare la chiamata a una persona.

Vedi su GitHub

Pagina di dettaglio di una chiamata in modalità chiara: una telefonata simulata da +14155550123 segnata come Booked, le latenze mediane (trascrizione vocale 178 ms, sintesi vocale 88 ms) e una trascrizione che si apre con "I'm an AI assistant, and this call may be recorded", con le chiamate ai tool check_availability e book_appointment in linea

Screenshot. Il template in esecuzione in locale.

Modelli: ink-2, sonic-3.6
Lingue: Inglese
Licenza: Apache-2.0
Stack: PythonFastAPIhtmxSQLiteuv
Prodotti Cartesia: Managed AgentsInk 2Sonic 3.6Phone numbers

Cosa fa

Ogni chiamata finisce in una dashboard con la trascrizione, la registrazione e la velocità con cui l'agente ha risposto a ogni turno. Puoi provare tutto nel browser con la sola chiave API di Cartesia. Una volta fatto il deploy, puoi dargli un numero di telefono.

Eseguilo tu

1
Installa e crea l'agente
Esegui i comandi qui sotto con Python 3.12 o successivo e uv. setup_agent.py crea l'agente e i suoi quattro tool.
npx degit cartesia-ai/cookbook/examples/front-desk front-desk cd front-desk # put your key in CARTESIA_API_KEY cp .env.example .env uv sync # creates the agent and its tools, writes CARTESIA_AGENT_ID uv run scripts/setup_agent.py uv run uvicorn front_desk.main:app --port 8000
Variabili d'ambiente
CARTESIA_API_KEY
play.cartesia.ai/keys
CARTESIA_AGENT_ID
Scritta da scripts/setup_agent.py
BUSINESS_NAME
Opzionale, con le altre impostazioni BUSINESS_. Di default un parrucchiere a Los Angeles
PUBLIC_BASE_URL
Per le telefonate. L'indirizzo HTTPS pubblico del server
DASHBOARD_PASSWORD
Obbligatoria dopo il deploy. Password HTTP Basic per la dashboard e le route delle chiamate
UVICORN_HOST
Opzionale. L'indirizzo su cui uvicorn ascolta senza --host
TRUST_PROXY
Opzionale. 1 dietro un proxy come Render, Fly o Railway
CALCOM_API_KEY
Opzionale, con CALCOM_EVENT_TYPE_ID. Prenota su Cal.com
Chiamalo dal browser
Apri http://localhost:8000/try, premi Start call e chiedi un appuntamento. Usa le cuffie, altrimenti l'agente sente sé stesso.
Collegalo a un numero di telefono
Fai il deploy su un host con HTTPS, imposta PUBLIC_BASE_URL e DASHBOARD_PASSWORD ed esegui di nuovo la configurazione. Poi collega all'agente un numero Cartesia, un numero Twilio o un trunk SIP.

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 an AI phone receptionist on a Cartesia Managed Agent. Start from https://github.com/cartesia-ai/cookbook/tree/main/examples/front-desk and follow its AGENTS.md for the commands, files and rules. scripts/setup_agent.py creates the agent with POST /v1/agents and its tools with POST /v1/agents/tools. Without PUBLIC_BASE_URL the tools are client tools for browser calls; with it they become webhook tools and a call webhook is registered. The browser gets a 60 second access token with only the agent grant. Check x-webhook-secret in constant time, as front_desk/webhooks.py does. If I don't have a Cartesia API key yet, follow https://www.cartesia.ai/agent-quickstart.md to get one.

Come funziona

ChiamanteUna chiamata dal browser su /try, oppure un numero di telefono

Ink 2Ascolta chi chiama

LLMChiama check_availability, book_appointment, take_message e transfer_call

Sonic 3.6Pronuncia la risposta

DashboardChiamate, trascrizioni, registrazioni e latenza in SQLite

Perché funziona così

Un solo elenco di tool per chiamate dal browser e al telefono

I quattro tool sono definiti una sola volta, in front_desk/tools.py. Sul tuo portatile, la chiamata dal browser passa ogni richiesta di tool al tuo server. Dopo il deploy con un indirizzo pubblico, Cartesia chiama direttamente il tuo server, sia per le chiamate al telefono sia per quelle dal browser.

Le richieste di Cartesia portano un segreto condiviso

Cartesia rimanda il segreto che hai registrato con ogni richiesta, nell'header x-webhook-secret. Il server lo confronta in tempo costante, ignora gli eventi destinati a un altro agente e salta i tentativi ripetuti già gestiti.

La latenza viene dai dati della chiamata

Cartesia salva con ogni chiamata i tempi per turno di trascrizione vocale, LLM e sintesi vocale. La dashboard li legge da lì invece di misurare qualcosa da sola.

Personalizzalo

La tua attività

Imposta BUSINESS_NAME, BUSINESS_SERVICES, BUSINESS_TIMEZONE, BUSINESS_HOURS e APPOINTMENT_MINUTES, poi esegui di nuovo la configurazione.

Cosa dice il receptionist

Modifica front_desk/prompt.py, poi esegui di nuovo la configurazione. Lascia nel saluto l'avviso che si tratta di un'IA e che la chiamata è registrata.

Un altro tool

Aggiungi una specifica e un metodo in front_desk/tools.py. La configurazione crea il tool Cartesia, ed entrambe le route dei tool lo usano.

Unisciti ai team che passano a Cartesia

Al primo posto

nelle classifiche Speech Arena e Speech to Text di Artificial Analysis

Domande

Posso usare il mio numero di telefono?

Sì. Importa un numero Twilio che hai già, collega il tuo operatore via SIP o prendi un numero USA gratuito da Cartesia. I trasferimenti a una persona funzionano solo sulle chiamate Twilio o SIP.

La mia chiave API di Cartesia è al sicuro quando le persone chiamano dal browser?

Sì. La chiave resta sul tuo server. Il browser riceve un token che dura 60 secondi e funziona solo per le chiamate agli agenti.

Altre persone possono vedere le mie chiamate quando è online?

No, se imposti DASHBOARD_PASSWORD. Allora ogni pagina della dashboard e ogni registrazione chiedono quella password, e l'app si rifiuta di partire su un indirizzo pubblico senza.

Dice a chi chiama che sta parlando con un'IA?

Sì. Il saluto predefinito dice a chi chiama che sta parlando con un assistente IA e che la chiamata potrebbe essere registrata.

Le chiamate vengono registrate?

Sì. Cartesia registra per impostazione predefinita l'audio e la trascrizione di ogni chiamata dell'agente, e la dashboard riproduce le registrazioni da lì. Il tuo server conserva i dati delle chiamate e le trascrizioni ma non l'audio, e niente viene cancellato finché non lo cancelli tu.

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 dei tool di Managed Agents spiega la parte di Cartesia.