Pular para o conteúdo
Qomni

Agents

Crie um agente, dê voz a ele e coloque-o para atender: REST para as ligações e um WebSocket para falar com ele em tempo real a partir do seu app.

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

Novidades

Fale com um agente em tempo real

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.

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.

POST /agents/v1/realtime/sessions (chave secreta){ url }, válida por 60 sa urlabre o WebSocketsession.startedinput_text.sendresponse.text.delta …response.donesession.endsession.ended (minutos faturados)ClienteSeu servidorAgents APIClienteSeu servidorAgents API

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.

  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:

    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:

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

    Execute:

Você deve ver

A resposta do agente aparece palavra por palavra, seguida da mensagem session.ended. Em modo de teste, billed_minutes é sempre 0:

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.

Navegação do site

Novo

2 de 7 passos feitosA seguir: a plataforma em produção

A Qomni está em beta privada

A API e o app ainda não estão abertos. Veja o que está feito, o que falta e como abre, passo a passo até o primeiro cliente.

Digite para buscar…

↑↓ mover↵ abrirEsc para fechar