Skip to content
Qomni

Agents

Create an agent, give it a voice and put it to work: REST for the calls and a WebSocket to talk to it in real time from your app.

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

What's new

Talk to an agent in realtime

Open a voice conversation with a Qomni agent from your app over WebSocket, without exposing your key, in Python or TypeScript.

A realtime conversation has two steps: your server creates a session over REST with its key, and your client opens a WebSocket with that session’s url. The key never travels over the socket. In this guide one program does both parts, so you can try it in one go. In production, the server creates the session and the browser or the app only receives the url.

POST /agents/v1/realtime/sessions (secret key){ url }, valid for 60 sthe urlopens the WebSocketsession.startedinput_text.sendresponse.text.delta …response.donesession.endsession.ended (billed minutes)ClientYour serverAgents APIClientYour serverAgents API

Before you begin

You need:

  • An Agents test key (sk_agents_test_…), stored in the QOMNI_KEY environment variable.
  • Python 3.10 or later, or Node.js 22 or later (it ships with fetch and WebSocket).
  1. Install what you need

    In Python we use requests for the REST call and websockets for the socket. In Node.js, tsx runs TypeScript without compiling it.

  2. Create a session

    To open a conversation, request a session with your key. instructions is optional and tells the agent what to do in this conversation:

    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" }'

    The response carries the socket’s url. Open it within 60 seconds:

    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. Open the socket and talk

    The program creates the session, waits for session.started, sends a question, prints the reply as it arrives and hangs up. Save it as realtime.py or realtime.mts:

    Run it:

You should see

The agent’s reply appears word by word, followed by the session.ended message. In test mode, billed_minutes is always 0:

Sí, llevamos pedidos al centro de lunes a sábado.
{'type': 'session.ended', 'reason': 'client_ended', 'billed_minutes': 0, 'usage_record_id': None}

If you see api_key_malformed instead, the key was copied wrong: export QOMNI_KEY again. If you see realtime_session_invalid, more than 60 seconds passed between creating the session and opening the socket.

Hanging up

The program hangs up on its own when it receives response.done: it sends session.end, and the server replies session.ended with the billed minutes and closes the socket. If you do not hang up, the session ends by itself after max_duration_seconds (900 seconds) with reason: max_duration.

Next steps

You now have a complete conversation with an agent. To put it in your app, split the two parts: your server creates the session and hands the url to the client.

Site navigation

New

2 of 7 steps doneNext: the platform in production

Qomni is in private beta

The API and the app are not open yet. See what is done, what is left and how it opens, step by step until the first customer.

Type to search…

↑↓ move↵ openEsc to close