Uma recepcionista que atende
todas as ligações

Q: Outras pessoas podem ver minhas ligações quando estiver online?

Não, se você definir DASHBOARD_PASSWORD. Aí cada página do painel e cada gravação pedem essa senha, e o app se recusa a iniciar em um endereço público sem ela.

Um recepcionista com IA de código aberto para um pequeno negócio. Um Managed Agent da Cartesia atende o telefone. Um pequeno servidor em Python dá a ele ferramentas para marcar horários no Cal.com ou em um calendário integrado, anotar recados e passar a ligação para uma pessoa.

Ver no GitHub

Página de detalhes de uma ligação no modo claro: uma ligação simulada de +14155550123 marcada como Booked, medianas de latência (fala para texto 178 ms, texto para fala 88 ms) e uma transcrição que começa com "I'm an AI assistant, and this call may be recorded", com as chamadas de ferramenta check_availability e book_appointment no meio

Captura de tela. O template rodando localmente.

Modelos: ink-2, sonic-3.6
Idiomas: Inglês
Licença: Apache-2.0
Stack: PythonFastAPIhtmxSQLiteuv
Produtos da Cartesia: Managed AgentsInk 2Sonic 3.6Phone numbers

O que ele faz

Cada ligação aparece em um painel com a transcrição, a gravação e a rapidez com que o agente respondeu em cada turno. Você pode testar tudo no navegador só com uma chave de API da Cartesia. Depois do deploy, você pode dar a ele um número de telefone.

Rode você mesmo

1
Instale e crie o agente
Rode os comandos abaixo com o Python 3.12 ou mais recente e o uv. setup_agent.py cria o agente e as quatro ferramentas dele.
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
Variáveis de ambiente
CARTESIA_API_KEY
play.cartesia.ai/keys
CARTESIA_AGENT_ID
Gravado por scripts/setup_agent.py
BUSINESS_NAME
Opcional, junto com as outras configurações BUSINESS_. O padrão é um salão de cabeleireiro em Los Angeles
PUBLIC_BASE_URL
Para ligações telefônicas. O endereço HTTPS público do servidor
DASHBOARD_PASSWORD
Obrigatória depois da implantação. Senha HTTP Basic para o painel e as rotas de chamada
UVICORN_HOST
Opcional. O endereço em que o uvicorn escuta sem --host
TRUST_PROXY
Opcional. 1 atrás de um proxy como Render, Fly ou Railway
CALCOM_API_KEY
Opcional, junto com CALCOM_EVENT_TYPE_ID. Marca os horários no Cal.com
Ligue pelo navegador
Abra http://localhost:8000/try, clique em Start call e peça um horário. Use fones de ouvido, senão o agente ouve a si mesmo.
Coloque em um número de telefone
Implante em um host com HTTPS, defina PUBLIC_BASE_URL e DASHBOARD_PASSWORD e rode a configuração de novo. Depois vincule ao agente um número da Cartesia, um número da Twilio ou um tronco SIP.

Crie com seu agente de programação

Um prompt que diz ao seu agente de programação por onde começar e o que ler primeiro.

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.

Como funciona

ClienteUma chamada pelo navegador em /try, ou um número de telefone

Ink 2Ouve quem liga

LLMChama check_availability, book_appointment, take_message e transfer_call

Sonic 3.6Fala a resposta

PainelLigações, transcrições, gravações e latência em SQLite

Por que funciona assim

Uma só lista de ferramentas para ligações pelo navegador e por telefone

As quatro ferramentas são definidas uma vez só, em front_desk/tools.py. No seu notebook, a ligação pelo navegador repassa cada pedido de ferramenta ao seu servidor. Depois do deploy com um endereço público, a Cartesia chama seu servidor diretamente, tanto em ligações telefônicas quanto pelo navegador.

As requisições da Cartesia levam um segredo compartilhado

A Cartesia devolve o segredo que você registrou em cada requisição, no cabeçalho x-webhook-secret. O servidor compara o valor em tempo constante, ignora eventos de outro agente e pula novas tentativas que já tratou.

A latência vem dos dados da chamada

A Cartesia guarda com cada ligação os tempos por turno da transcrição de voz, do LLM e da síntese de voz. O painel lê esses números de lá em vez de medir algo por conta própria.

Deixe com a sua cara

O seu negócio

Defina BUSINESS_NAME, BUSINESS_SERVICES, BUSINESS_TIMEZONE, BUSINESS_HOURS e APPOINTMENT_MINUTES e rode a configuração de novo.

O que a recepcionista diz

Edite front_desk/prompt.py e rode a configuração de novo. Mantenha na saudação o aviso de que é uma IA e de que a ligação é gravada.

Outra ferramenta

Adicione uma especificação e um método em front_desk/tools.py. A configuração cria a ferramenta na Cartesia, e as duas rotas de ferramentas passam a usá-la.

Junte-se às equipes que estão migrando para a Cartesia

Em 1º lugar

nos rankings Speech Arena e Speech to Text da Artificial Analysis

Perguntas

Posso usar meu próprio número de telefone?

Sim. Importe um número da Twilio que você já tem, conecte sua própria operadora por SIP ou pegue um número gratuito dos EUA na Cartesia. Transferências para uma pessoa só funcionam em ligações pela Twilio ou por SIP.

Minha chave de API da Cartesia fica segura quando as pessoas ligam pelo navegador?

Sim. A chave fica no seu servidor. O navegador recebe um token que dura 60 segundos e só funciona para ligações com agentes.

Outras pessoas podem ver minhas ligações quando estiver online?

Não, se você definir DASHBOARD_PASSWORD. Aí cada página do painel e cada gravação pedem essa senha, e o app se recusa a iniciar em um endereço público sem ela.

Ela avisa a quem liga que está falando com uma IA?

Sim. A saudação padrão diz que a pessoa está falando com uma assistente de IA e que a ligação pode ser gravada.

As ligações são gravadas?

Sim. Por padrão, a Cartesia grava o áudio e a transcrição de cada ligação de agente, e o painel toca as gravações a partir de lá. Seu servidor guarda os dados das ligações e as transcrições, mas não o áudio, e nada é apagado até você apagar.

Existe um guia passo a passo deste template?

Sim. A receita explica o código, o README cobre a configuração, as variáveis de ambiente e a implantação, e a documentação de ferramentas do Managed Agents explica o lado da Cartesia.