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

O edge e as células

Onde vivem os dados do seu workspace, o que o edge faz com cada requisição e por que seu código nunca escolhe região.

Os dados de cada workspace vivem em uma célula: uma cópia completa da plataforma em uma região (us1 nos Estados Unidos, co1 na Colômbia, br1 no Brasil). Na frente de todas as células há um único ponto de entrada, o edge, que recebe cada requisição e a leva à célula correta.

Para você isso significa uma coisa: a API vive em um único host, api.qomni.ai, com o produto e a versão na rota (https://api.qomni.ai/agents/v1), e a URL nunca leva região. Seu código é o mesmo para um cliente em Bogotá e para um em São Paulo.

O app web também tem um único host, app.qomni.ai: o portal e a página de cada produto dentro de cada workspace, em app.qomni.ai/{workspace}/{producto} (por exemplo app.qomni.ai/acme/agents). Os endereços antigos de cada produto (agents.qomni.ai/acme…) redirecionam para lá.

Por que existem células

Gravações e transcrições de chamadas têm regras legais diferentes em cada país. Guardar os dados de um workspace no próprio país torna mais simples cumpri-las e mais curto o caminho de cada requisição. A alternativa, um único banco de dados para o mundo todo, obrigaria a escolher um país para todos.

A Qomni escolheu não passar essa decisão para o seu código. Por isso a célula vai dentro da chave de API (sk_agents_live_co1_…) e o edge a lê de lá. Não há um parâmetro de região, nem um host por país, nem nada que você possa configurar errado.

O percurso de uma requisição

sk_agents_live_co1_…token de 10 sSeu servidorEdgeCélula co1apiCélula us1Célula br1
  1. O edge identifica a requisição. Lê o prefixo da chave (sk_<product>_<mode>_<cell>_…) e verifica o checksum. Uma chave copiada errado é rejeitada aqui, com 401 api_key_malformed, sem chegar a nenhum servidor.
  2. Encontra a célula. Com uma chave de API, a célula está na chave. No app web, uma página de produto (app.qomni.ai/{workspace}/{producto}/…) vai para a célula do workspace da sua rota; o resto de app.qomni.ai (seus workspaces, as configurações, o login) não vive em nenhuma célula. Um endereço antigo de produto (agents.qomni.ai/acme/…) não chega a nenhuma célula: o edge responde 308 para a mesma página em app.qomni.ai/acme/agents/….
  3. Assina um token de edge. Vale 10 segundos, serve para uma única requisição e fica ligado ao host público, à célula e ao seu endereço IP.
  4. Reenvia a requisição ao serviço dessa célula que atende a rota, com a rota tal como está. Qual é esse serviço não se vê de fora. A origem só aceita requisições que tragam o token: ninguém pode pular o edge chamando uma origem diretamente.

A resposta traz o header X-Request-Id. Guarde-o nos seus logs: é o que o suporte usa para encontrar sua requisição.

Erros do edge

Têm a mesma forma que os erros da API.

Código Quando
api_key_missing, api_key_malformed Falta o header Authorization, ou a chave não tem a forma ou o checksum esperados.
realtime_session_invalid A sessão do WebSocket não existe ou expirou. Vale 60 segundos.
origin_unavailable A célula não respondeu. Nada foi feito: tente de novo com backoff.
unknown_api 404: o primeiro segmento da rota em api.qomni.ai não nomeia nenhuma API (/payroll/v1/…).
api_host_moved 404: o host é o endereço antigo da API (agents-api.qomni.ai). Use https://api.qomni.ai/agents/v1.
not_found, method_not_allowed A rota ou o método não existem nessa API.
product_host_moved 410: um método diferente de GET ou HEAD no endereço antigo de um produto (agents.qomni.ai). Envie a requisição para app.qomni.ai/{workspace}/{producto}.
host_moved 404: o host é o endereço antigo de um produto, que já não serve páginas.

Limites

  • Seu código nunca escolhe a célula. Não há parâmetro, host nem header para isso.
  • O endereço antigo da API (agents-api.qomni.ai) não redireciona: responde 404 api_host_moved com a nova URL base.
  • Uma chave só vale na célula dela. Usá-la em outra responde 421 wrong_cell. Na prática isso não acontece: a célula da chave é a do workspace que a criou.
  • Os dados não se movem entre células. Um workspace nasce em uma célula e fica lá.
  • O edge não guarda nem lê seus dados: só roteia e assina.

Veja também

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