---
title: "Fale com um agente em tempo real"
description: "Abra uma conversa de voz com um agente da Qomni a partir do seu app por WebSocket, sem expor sua chave, em Python ou TypeScript."
version: "pt-br"
---

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

# Fale com um agente em tempo real

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

```mermaid
sequenceDiagram
  participant C as Cliente
  participant S as Seu servidor
  participant A as Agents API
  S->>A: POST /agents/v1/realtime/sessions (chave secreta)
  A-->>S: { url }, válida por 60 s
  S-->>C: a url
  C->>A: abre o 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 faturados)
```

## Antes de começar

Você precisa de:

- Uma chave de teste do Agents (`sk_agents_test_…`), guardada na variável
  de ambiente `QOMNI_KEY`.
- Python 3.10 ou superior, ou Node.js 22 ou superior (que já traz `fetch` e
  `WebSocket`).

1. ### Instale o necessário

   Em Python usamos `requests` para a chamada REST e `websockets` para o
   socket. Em Node.js, `tsx` executa TypeScript sem compilar.

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

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

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

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

   A resposta traz a `url` do socket. Abra-a em 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. ### 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 em
   `realtime.py` ou `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);
     }
   };
   ```

   Execute:

   ```bash
   python realtime.py
   ```

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

```text
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](/pt-br/agents/websocket/): cada mensagem do canal, incluindo o áudio.
- [API keys e autenticação](/pt-br/concepts/authentication/): por que a chave não deve chegar ao navegador.
- [Modo de teste](/pt-br/concepts/test-mode/): o que muda com uma chave de teste.

Source: https://docs.qomni.ai/pt-br/agents/realtime/index.mdx
