Aprenda

Crie um agente de voz com Pipecat e Cartesia

Rene 
Crie um agente de voz com Pipecat e Cartesia

Pipecat é um framework Python de código aberto para agentes de voz em tempo real. A Cartesia oferece serviços de fala integrados a ele: Sonic para síntese de voz em streaming e Ink para reconhecimento de fala. Neste guia, você executará um agente de voz no navegador com os dois serviços conectados. Depois, usará as previsões antecipadas de fim de turno do Ink para reduzir cada resposta em cerca de meio segundo.

Basta clonar o repositório e definir duas variáveis de ambiente para começar. O agente resultante escuta, determina quando você terminou de falar, pensa e responde em voz alta.

Visão geral

Um agente de voz com Pipecat é um fluxo de processadores. O áudio entra por um transporte, é transcrito, passa por um LLM e sai como fala:

transport.input() → STT → LLM → TTS → transport.output()

Duas etapas determinam se a conversa parece humana ou uma troca por rádio: saber quando o usuário realmente parou de falar e produzir a resposta falada sem demora. É aí que entram os serviços da Cartesia. CartesiaTurnsSTTService executa Ink 2, o modelo de STT em streaming da Cartesia, e deixa o servidor decidir quando um turno terminou, em vez de estimar isso localmente. CartesiaTTSService transmite o áudio do Sonic enquanto ele é gerado, com marcações de tempo por palavra se você precisar.

A documentação do Pipecat indica de 500 a 800 milissegundos para um ciclo típico do fluxo. As etapas abaixo ajudam a gastar esse tempo com o modelo em vez de com silêncios.

Pré-requisitos

  1. Python 3.11 ou posterior. O README do repositório do Pipecat informa a versão mínima atual.
  2. Uma chave de API da Cartesia. Crie uma no painel.
  3. Uma chave de API de LLM para gerar as respostas. O exemplo usa OpenAI (OPENAI_API_KEY); Pipecat também inclui serviços para Anthropic, Gemini, Groq, Ollama e outros, caso você prefira outro modelo.

Uma observação sobre o escopo: atualmente, Ink 2 reconhece apenas inglês, então este agente escuta em inglês. Sonic fala mais de 40 idiomas, portanto a geração das respostas faladas não é a limitação.

1. Instale os extras importados pelo exemplo

O repositório do Pipecat inclui um agente da Cartesia pronto em examples/voice/voice-cartesia-turns.py:

git clone https://github.com/pipecat-ai/pipecat.git
cd pipecat
uv sync --extra cartesia --extra daily --extra websocket --extra runner --extra webrtc

Executar apenas uv sync instala o framework, mas não os extras importados por esse exemplo. O arquivo importa os transportes Daily e FastAPI WebSocket e o executor do Pipecat no início, mesmo quando você usa -t webrtc. Por isso, esses extras precisam estar instalados, ou a importação falha com No module named 'daily'. cartesia e webrtc são os componentes efetivamente usados.

Se estiver criando seu próprio projeto em vez de trabalhar no repositório do Pipecat, instale o mesmo conjunto:

pip install "pipecat-ai[cartesia,daily,websocket,runner,webrtc]"

Depois, copie examples/voice/voice-cartesia-turns.py do repositório para seu projeto. O exemplo precisa de CARTESIA_API_KEY e OPENAI_API_KEY. Coloque as duas em um arquivo .env ao lado do script:

CARTESIA_API_KEY=your-key-here
OPENAI_API_KEY=your-key-here

2. Execute o agente

uv run examples/voice/voice-cartesia-turns.py -t webrtc

O executor inicia um servidor local e exibe uma URL, por padrão http://localhost:7860. Abra a página, permita o acesso ao microfone e fale. Por trás da conversa:

  1. O navegador envia seu áudio por WebRTC.
  2. CartesiaTurnsSTTService o transcreve com Ink 2. O servidor acompanha os limites dos turnos e emite os eventos turn.start, turn.update, turn.eager_end e turn.end.
  3. O LLM escreve uma resposta.
  4. CartesiaTTSService transmite a resposta pelo Sonic, e o transporte reproduz o áudio à medida que ele chega.

A etapa 2 é a diferença importante. Configurações mais antigas adicionam um detector de atividade de voz ao áudio para estimar quando uma frase terminou. A detecção de turnos do Ink 2 acontece no servidor, o que permite a próxima etapa.

3. Escolha a voz e o LLM

O exemplo inclui um ID de voz e um prompt de sistema simples. Você pode alterar os dois:

tts = CartesiaTTSService(
    api_key=os.environ["CARTESIA_API_KEY"],
    settings=CartesiaTTSService.Settings(
        voice="86e30c1d-714b-4074-a1f2-1cb6b552fb49",
    ),
)

Escolha uma voz no playground e cole o ID aqui, ou gere uma nova a partir de uma amostra curta com clonagem de voz. Como o modelo transforma o texto em fala, escreva o prompt de sistema pensando no áudio: o exemplo original instrui o LLM a evitar emojis, listas com marcadores e outras formatações que ninguém consegue ouvir.

Se quiser usar um modelo Sonic específico, informe-o no mesmo objeto de configurações. O serviço usa sonic-3.6 por padrão atualmente.

4. Ganhe meio segundo com a previsão antecipada de fim de turno

Ao final de uma frase, Ink prevê que você terminou antes do encerramento técnico do turno e emite turn.eager_end. Pipecat expõe isso como o evento on_turn_eager_end(service, transcript). Assim, você pode começar a gerar a resposta imediatamente e voltar a escutar caso o usuário continue falando:

stt = CartesiaTurnsSTTService(
    api_key=os.environ["CARTESIA_API_KEY"],
    enable_eager_end_of_turn=True,
)

@stt.event_handler("on_turn_eager_end")
async def on_turn_eager_end(service, transcript):
    # Ink predicted the user's turn is ending. Start the LLM now.
    ...

A opção enable_eager_end_of_turn=True é importante. Ela instrui Pipecat a agir sobre a previsão antecipada do servidor em vez de esperar pelo fim de turno confirmado. Pipecat publica um exemplo de agregador especulativo do usuário que implementa o fluxo completo: inicia o LLM na previsão antecipada e continua escutando caso você prossiga. A documentação da Cartesia estima uma economia de cerca de meio segundo, a diferença entre um agente que responde e outro que espera sua vez.

Se o agente interromper enquanto você pensa, ajuste os limiares em vez de desativar a previsão antecipada. Os quatro controles, com os valores padrão da Cartesia, são turn_start_threshold (0.8), turn_eager_end_threshold (0.4), turn_end_threshold (0.2) e turn_end_timeout_ms (5600). Um agente paciente espera mais antes de concluir que você terminou. Isso exige uma previsão mais confiável antes da interrupção: reduza o limiar de fim antecipado para perto de 0.3 e aumente o tempo limite para perto de 8000.

Coloque em Settings(keyterm=["Pipecat", "Ink 2"]) uma lista dos nomes que seus usuários realmente dirão, como produtos e termos internos da empresa. Isso ajuda a transcrição a reconhecê-los corretamente.

Próximos passos

  1. Conecte o agente a um número de telefone. Execute novamente o mesmo exemplo com -t twilio e um proxy público. O fluxo funciona em chamadas sem alterações.
  2. Se preferir não manter o fluxo, crie o mesmo agente em Managed Agents, que cuida da telefonia, das ferramentas e do conhecimento.
  3. Precisa de arquivos de áudio em vez de uma conversa ao vivo? Use CartesiaHttpTTSService do mesmo pacote para síntese em lote.

Documentação relacionada

Perguntas frequentes

Pipecat oferece suporte à Cartesia?

Sim. Cartesia tem serviços integrados ao repositório do Pipecat: um serviço de TTS em streaming, CartesiaTTSService, e dois serviços de STT, incluindo CartesiaTurnsSTTService, que executa Ink 2 e permite que o servidor da Cartesia determine os limites dos turnos. Instale pipecat-ai com o extra cartesia, além dos extras de transporte e execução importados pelo seu ponto de entrada, e configure CARTESIA_API_KEY.

Quais modelos a integração com a Cartesia usa?

O serviço de TTS transmite Sonic, o modelo de fala em tempo real da Cartesia, e usa sonic-3.6 por padrão nas versões atuais do Pipecat. O serviço de STT com turnos executa Ink 2 (ink-2), que detecta turnos no servidor e emite previsões turn.eager_end. Passe model= em Settings para escolher outra versão do Sonic.

Qual é a velocidade de um agente de voz com Pipecat?

A documentação do Pipecat indica de 500 a 800 milissegundos para um ciclo típico do fluxo. Duas etapas podem ser encurtadas: detecção de turnos e síntese de fala. A previsão antecipada de fim de turno do Ink pode reduzir o tempo de resposta em cerca de meio segundo ao iniciar a resposta antes do encerramento formal do turno do usuário.

O agente pode atender chamadas telefônicas?

Sim. Pipecat inclui transportes de telefonia para Twilio, Exotel e Plivo. O mesmo fluxo funciona em uma chamada com -t twilio e um proxy público. Se preferir não manter o fluxo, Cartesia Managed Agents permite criar agentes de voz para chamadas recebidas e de saída sem código.

Preciso usar OpenAI como LLM?

Não. O exemplo usa OpenAILLMService por ser curto, mas Pipecat tem implementações de serviço para vários provedores de LLM, incluindo Anthropic, Gemini, Groq e Ollama local. Troque o serviço no fluxo e mantenha os serviços de STT e TTS da Cartesia.