---
title: "Habla con un agente en tiempo real"
description: "Abre una conversación de voz con un agente de Qomni desde tu app por WebSocket, sin exponer tu clave, en Python o TypeScript."
version: "es"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.qomni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Habla con un agente en tiempo real

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`.

```mermaid
sequenceDiagram
  participant C as Cliente
  participant S as Tu servidor
  participant A as Agents API
  S->>A: POST /agents/v1/realtime/sessions (clave secreta)
  A-->>S: { url }, válida 60 s
  S-->>C: la url
  C->>A: abre el WebSocket
  A-->>C: session.started
  C->>A: input_text.send
  A-->>C: response.text.delta …
  A-->>C: response.done
  C->>A: session.end
  A-->>C: session.ended (minutos facturados)
```

## 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.

   ```bash
   export QOMNI_KEY="sk_agents_test_…"
   pip install requests websockets
   ```

   ```bash
   export QOMNI_KEY="sk_agents_test_…"
   npm install --save-dev tsx
   ```

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:

   ```bash
   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**:

   ```json title="201 Created"
   {
     "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`:

   ```python
   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()))
   ```

   ```typescript
   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:

   ```bash
   python realtime.py
   ```

   ```bash
   npx 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`:

```text
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](/es/agents/websocket/): cada mensaje del canal, incluido el audio.
- [API keys y autenticación](/es/concepts/authentication/): por qué la clave no debe llegar al navegador.
- [Modo de prueba](/es/concepts/test-mode/): qué cambia con una clave de prueba.

Source: https://docs.qomni.ai/es/agents/realtime/index.mdx
