Saltar al contenido
Qomni

Agents

Crea un agente, dale voz y ponlo a atender: REST para las llamadas y un WebSocket para hablar con él en tiempo real desde tu app.

URL base
https://api.qomni.ai/agents/v1
Clave
sk_agents_test_…
curl https://api.qomni.ai/agents/v1/calls \
  -H "Authorization: Bearer sk_agents_test_…"

Novedades

Habla con un agente en tiempo real

Abre una conversación de voz con un agente de Qomni desde tu app por WebSocket, sin exponer tu clave, en Python o TypeScript.

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.

POST /agents/v1/realtime/sessions (clave secreta){ url }, válida 60 sla urlabre el WebSocketsession.startedinput_text.sendresponse.text.delta …response.donesession.endsession.ended (minutos facturados)ClienteTu servidorAgents APIClienteTu servidorAgents API

Antes de empezar

Necesitas:

  • Una clave de prueba de Agents (sk_agents_test_…), guardada en la variable de entorno QOMNI_KEY.
  • Python 3.10 o superior, o Node.js 22 o superior (ya trae fetch y WebSocket).
  1. Instala lo necesario

    En Python usamos requests para la llamada REST y websockets para el socket. En Node.js, tsx ejecuta TypeScript sin compilarlo.

  2. Crea una sesión

    Para abrir una conversación, pide una sesión con tu clave. instructions es 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 url del 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"
    }
  3. 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 en realtime.py o realtime.mts:

    Ejecútalo:

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.

Navegación del sitio

Nuevo

Qomni está en beta privada

La API y la app todavía no están abiertas. Mira qué está hecho, qué falta y cómo se abre, paso a paso hasta el primer cliente.

Escribe para buscar…

↑↓ moverte↵ abrirEsc para cerrar