Ermis Voice SDK para Python

Prévia (0.2.0a1). A Voice API ainda está em desenvolvimento; nomes e campos podem mudar até o lançamento.

O SDK liga o seu backend à Ermis Voice API. Ele cria sessões, abre o canal de controle e entrega os eventos da ligação como objetos Python, com métodos para mandar o agente agir.

O que é de quem

Resumindo: a Voice API conduz a ligação; o SDK é o controle remoto; a inteligência do negócio é sua. Tudo o que o SDK faz também pode ser feito com HTTP e WebSocket puros, seguindo a documentação da API. O SDK só tira o trabalho repetitivo: autenticação, montagem do JSON, ids de correlação, tipos, erros e o TwiML.

Instalação

pip install ermis-voice    # Python 3.10+
export ERMIS_API_KEY=ek_test_...

O pacote se chama ermis-voice no pip e é importado como ermis:

from ermis import Ermis

Para instalar direto do GitHub (por exemplo, uma versão ainda não publicada no PyPI):

pip install "git+https://github.com/Ermisai/ermis-voice-sdk.git"

Durante a prévia, a chave e a URL da Voice API são entregues pela equipe da Ermis. Defina ERMIS_API_URL se ela for diferente de https://api.ermis.ai.

Chaves ek_test_… usam o Sandbox; ek_live_…, produção. Use a chave só no servidor.

Início rápido (Twilio)

import asyncio

from fastapi import FastAPI, Form, Response
from ermis import Ermis, SessionStarted, Decision

app = FastAPI()
ermis = Ermis()  # lê ERMIS_API_KEY

@app.post("/twilio/voz")
async def ligacao(CallSid: str = Form(...)):
    session = await ermis.sessions.create(transport="twilio", metadata={"call_sid": CallSid})
    asyncio.create_task(conversar(session))
    return Response(session.twiml(), media_type="application/xml")   # o áudio vai direto para a Ermis

async def conversar(session):
    async with ermis.connect(session) as call:
        async for event in call:
            if isinstance(event, SessionStarted):
                await call.speak("Olá! Como posso ajudar?", calibrate=True)
            elif isinstance(event, Decision):
                await call.speak(await sua_ia(event))

Exemplo completo, com respostas rápidas, confirmação, desistência e despedida: examples/atendente_twilio.py.

Referência

Ermis(api_key=None, *, base_url=None, timeout=10.0, http_client=None)

Cliente assíncrono. Sem api_key, lê ERMIS_API_KEY; sem base_url, lê ERMIS_API_URL ou usa https://api.ermis.ai. Feche com await ermis.aclose() ou use async with Ermis() as ermis.

usage() devolve os lançamentos de crédito em páginas: passe o next_cursor recebido em before para buscar a página seguinte (limit de 1 a 100). balance() devolve balance, reserved_credits (reservado por ligações em andamento) e available_credits, em créditos inteiros.

Opções de sessions.create (todas opcionais; o que você não passar usa o padrão da API): transport ("twilio", "browser", "websocket"), audio_format ("mulaw_8k", "pcm16_48k"), language, voice, auto_decide, transcription_priority ("balanced", "latency", "accuracy"), vad=VadOptions(min_silence_ms=…), barge_in=BargeInOptions(enabled=…, min_speech_ms=…), waiting=WaitingOptions(…), max_duration_s, metadata.

from ermis import WaitingOptions

waiting = WaitingOptions(
    filler_after_ms=800,                       # None desliga a frase de espera
    filler_messages=["Certo, um momento."],
    filler_by_intent={"complaint": ["Entendo, sinto muito por isso."]},   # frase pela intenção da fala
    gap_after_ms=600,                          # pausa antes da sua resposta; None desliga
    patience_after_ms=3500,
    patience_every_ms=8000,
    patience_messages=["Ainda estou verificando…"],
    timeout_ms=20000,                          # None: espera sem limite
    timeout_message="Desculpe, não consegui essa informação agora.",
    timeout_action="apologize",                # ou "end"
)

Session

session_id, audio_url, control_url, session_token, e:

• session.twiml(): TwiML pronto para o transporte twilio, com o token escapado.
• session.browser_credentials(): {"audio_url", "session_token"}, o que entregar ao navegador no transporte browser. A chave de API nunca sai do servidor.

Call: o canal de controle

async for event in call recebe os eventos até SessionEnded. Os comandos podem ser chamados a qualquer momento, inclusive enquanto você trata um evento.

decide() e extract_slot() geram o id, esperam a resposta com esse id (padrão: 10 s) e devolvem o resultado. Essas respostas não aparecem na iteração. Depois do fim, call.ended guarda o SessionEnded.

Eventos

Todo evento tem type e raw (o JSON original). Eventos novos da API chegam como UnknownEvent em vez de quebrar o seu código.

Transcript.assessment traz ignore, ask_to_repeat, unproductive, confirm e o atalho usable (nem ignore, nem ask_to_repeat, nem unproductive).

Erros

O mesmo erro chega como status HTTP ou código de fechamento do WebSocket; o SDK levanta a mesma exceção nos dois casos. Todas herdam de ErmisError (message, code, status, request_id). Guarde o request_id para falar com o suporte.

Outros transportes

Navegador. Crie a sessão com transport="browser", audio_format="pcm16_48k" e envie session.browser_credentials() ao navegador. O navegador abre audio_url?session_token=… e troca áudio direto com a Ermis; o seu backend conduz a conversa com ermis.connect(session), como no Twilio.

Seu próprio WebSocket. Com transport="websocket", o mesmo Call leva áudio e controle: envie com call.send_audio(frame), receba Audio na iteração e avise o fim de cada fala com call.playback_finished(speak_id).

Documentação

• Referência da Voice API: sessões, canal de controle, decisões, mensagens de espera, áudio e erros.
• Na plataforma da Ermis: Documentação API → Ermis Voice e a aba Ligação da Área de Teste, para conversar com o agente pelo microfone.

Desenvolvimento

uv venv && uv pip install -e ".[dev]"
.venv/bin/python -m pytest -q

Os testes rodam contra uma Voice API simulada (REST com httpx.MockTransport, controle com um servidor WebSocket local).

Licença

MIT. Veja LICENSE.