Uma conversa em tempo real tem dois passos: seu servidor cria uma sessão
por REST com a chave dele, e seu cliente abre um WebSocket com a url dessa
sessão. A chave nunca passa pelo socket. Neste guia, um único programa
faz as duas partes, para você testar de uma vez. Em produção, o servidor
cria a sessão e o navegador ou o app só recebe a url.
Antes de começar
Você precisa de:
- Uma chave de teste do Agents (
sk_agents_test_…), guardada na variável de ambienteQOMNI_KEY. - Python 3.10 ou superior, ou Node.js 22 ou superior (que já traz
fetcheWebSocket).
-
Instale o necessário
Em Python usamos
requestspara a chamada REST ewebsocketspara o socket. Em Node.js,tsxexecuta TypeScript sem compilar.export QOMNI_KEY="sk_agents_test_…" pip install requests websocketsexport QOMNI_KEY="sk_agents_test_…" npm install --save-dev tsx -
Crie uma sessão
Para abrir uma conversa, peça uma sessão com a sua chave.
instructionsé opcional e diz ao agente o que fazer nesta conversa:curl https://api.qomni.ai/agents/v1/realtime/sessions \ -H "Authorization: Bearer $QOMNI_KEY" \ -H "Content-Type: application/json" \ -d '{ "instructions": "Responde en una frase" }'A resposta traz a
urldo socket. Abra-a em menos de 60 segundos:201 Createdjson { "id": "rts_01k8x3d5n2p7q4r6s8t0v1w3y5", "url": "wss://api.qomni.ai/agents/v1/realtime?session=rts_co1_…", "client_secret": "rts_co1_…", "expires_at": "2026-10-21T15:05:05Z", "max_duration_seconds": 900, "livemode": false, "cell": "co1" } -
Abra o socket e converse
O programa cria a sessão, espera
session.started, envia uma pergunta, imprime a resposta à medida que ela chega e desliga. Salve-o emrealtime.pyourealtime.mts:import asyncio import json import os import requests import websockets QUESTION = { "type": "input_text.send", "text": "¿Hacen domicilios al centro?", } HANG_UP = {"type": "session.end"} def create_session() -> str: key = os.environ["QOMNI_KEY"] response = requests.post( "https://api.qomni.ai/agents/v1/realtime/sessions", headers={"Authorization": f"Bearer {key}"}, json={"instructions": "Responde en una frase"}, timeout=10, ) if not response.ok: error = response.json()["error"] raise SystemExit(f"{error['code']}: {error['message']}") return response.json()["url"] async def converse(url: str) -> None: async with websockets.connect(url) as socket: async for raw in socket: message = json.loads(raw) match message["type"]: case "session.started": await socket.send(json.dumps(QUESTION)) case "response.text.delta": print(message["delta"], end="", flush=True) case "response.done": print() await socket.send(json.dumps(HANG_UP)) case "session.ended": print(message) case "error": raise SystemExit(message["error"]["code"]) asyncio.run(converse(create_session()))const url = "https://api.qomni.ai/agents/v1/realtime/sessions"; const response = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.QOMNI_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ instructions: "Responde en una frase" }), }); if (!response.ok) { const { error } = await response.json(); throw new Error(`${error.code}: ${error.message}`); } const session = await response.json(); const socket = new WebSocket(session.url); const send = (message: object) => socket.send(JSON.stringify(message)); socket.onmessage = ({ data }) => { const message = JSON.parse(data); switch (message.type) { case "session.started": send({ type: "input_text.send", text: "¿Hacen domicilios al centro?", }); break; case "response.text.delta": process.stdout.write(message.delta); break; case "response.done": console.log(); send({ type: "session.end" }); break; case "session.ended": console.log(message); break; case "error": throw new Error(message.error.code); } };Execute:
python realtime.pynpx tsx realtime.mts
Você deve ver
A resposta do agente aparece palavra por palavra, seguida da mensagem
session.ended. Em modo de teste, billed_minutes é sempre 0:
Sí, llevamos pedidos al centro de lunes a sábado.
{'type': 'session.ended', 'reason': 'client_ended', 'billed_minutes': 0, 'usage_record_id': None}Se em vez disso você vir api_key_malformed, a chave foi copiada errado: exporte
QOMNI_KEY de novo. Se vir realtime_session_invalid, passaram mais de 60
segundos entre criar a sessão e abrir o socket.
Desligar
O programa desliga sozinho ao receber response.done: envia session.end, e o
servidor responde session.ended com os minutos faturados e fecha o
socket. Se você não desligar, a sessão termina sozinha aos max_duration_seconds
(900 segundos) com reason: max_duration.
Próximos passos
Você já tem uma conversa completa com um agente. Para colocá-la no seu app,
separe as duas partes: a sessão é criada pelo seu servidor e a url você
entrega ao cliente.
- WebSocket em tempo real: cada mensagem do canal, incluindo o áudio.
- API keys e autenticação: por que a chave não deve chegar ao navegador.
- Modo de teste: o que muda com uma chave de teste.