Una conversación en tiempo real tiene dos pasos: tu servidor crea una sesión
por REST con su clave, y tu cliente abre un WebSocket con la url de esa
sesión. La clave nunca viaja por el socket. En esta guía un solo programa
hace las dos partes, para que lo pruebes de una vez. En producción, el
servidor crea la sesión y el navegador o la app sólo recibe la url.
Antes de empezar
Necesitas:
- Una clave de prueba de Agents (
sk_agents_test_…), guardada en la variable de entornoQOMNI_KEY. - Python 3.10 o superior, o Node.js 22 o superior (ya trae
fetchyWebSocket).
-
Instala lo necesario
En Python usamos
requestspara la llamada REST ywebsocketspara el socket. En Node.js,tsxejecuta TypeScript sin compilarlo.export QOMNI_KEY="sk_agents_test_…" pip install requests websocketsexport QOMNI_KEY="sk_agents_test_…" npm install --save-dev tsx -
Crea una sesión
Para abrir una conversación, pide una sesión con tu clave.
instructionses opcional y le dice al agente qué hacer en esta conversación: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" }'La respuesta trae la
urldel socket. Ábrela en 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" } -
Abre el socket y conversa
El programa crea la sesión, espera
session.started, envía una pregunta, imprime la respuesta a medida que llega y cuelga. Guárdalo enrealtime.pyorealtime.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); } };Ejecútalo:
python realtime.pynpx tsx realtime.mts
Deberías ver
La respuesta del agente aparece palabra por palabra, seguida del mensaje
session.ended. En modo de prueba, billed_minutes es siempre 0:
Sí, llevamos pedidos al centro de lunes a sábado.
{'type': 'session.ended', 'reason': 'client_ended', 'billed_minutes': 0, 'usage_record_id': None}Si en su lugar ves api_key_malformed, la clave está mal copiada: vuelve a
exportar QOMNI_KEY. Si ves realtime_session_invalid, pasaron más de 60
segundos entre crear la sesión y abrir el socket.
Colgar
El programa cuelga solo al recibir response.done: envía session.end, y el
servidor responde session.ended con los minutos facturados y cierra el
socket. Si no cuelgas, la sesión termina sola a los max_duration_seconds
(900 segundos) con reason: max_duration.
Siguientes pasos
Ya tienes una conversación completa con un agente. Para ponerla en tu app,
separa las dos partes: la sesión la crea tu servidor y la url se la das al
cliente.
- WebSocket en tiempo real: cada mensaje del canal, incluido el audio.
- API keys y autenticación: por qué la clave no debe llegar al navegador.
- Modo de prueba: qué cambia con una clave de prueba.