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

Idempotência e novas tentativas

O que é uma requisição idempotente, quando é seguro repetir uma chamada à Qomni e como usar o header Idempotency-Key.

Uma requisição é idempotente quando repeti-la produz o mesmo resultado que fazê-la uma única vez. Listar suas chamadas é idempotente: você faz isso dez vezes e a lista não muda. Criar uma chamada não é: você a cria duas vezes e o agente liga duas vezes para o mesmo cliente.

Redes falham, então seu código precisa tentar de novo. O problema é repetir uma requisição que cria algo sem criá-lo duas vezes.

Por que o problema existe

O caso perigoso não é quando a requisição falha. É quando você não sabe se falhou:

POST /agents/v1/callscria call_01… e o agente ligaa resposta se perdenova tentativa: POST /agents/v1/callscria call_02… e o agente liga de novo201 call_02…Seu servidorAgents APISeu servidorAgents API
  1. Seu servidor envia POST /agents/v1/calls.
  2. A Qomni cria a chamada e o agente liga para o cliente.
  3. A resposta se perde no caminho (a conexão cai, seu tempo de espera se esgota).
  4. Seu código vê um erro de rede e tenta de novo.
  5. A Qomni cria uma segunda chamada e o cliente recebe duas.

Do seu lado, os passos 2 e 3 são invisíveis: uma falha de rede antes da resposta parece igual a uma falha de rede antes de a requisição chegar. Nenhum cliente consegue distingui-las sozinho.

Como se resolve

A solução é você dar um nome a cada operação. Você envia um header Idempotency-Key com um valor que escolhe, e repete esse mesmo valor em cada nova tentativa da mesma operação. Assim a API reconhece a repetição e devolve o resultado da primeira vez em vez de criar outra chamada.

A chave boa sai dos seus próprios dados: o id do pedido a lembrar, o id da consulta a confirmar, o id do cliente mais a data. Uma chave aleatória gerada em cada tentativa não serve, porque cada tentativa levaria uma chave nova.

Quando tentar de novo

O que você recebeu Tente de novo Por quê
503 origin_unavailable Sim, com backoff A célula não recebeu a requisição. Nada foi feito.
429 rate_limited Sim, após Retry-After segundos A requisição não foi processada.
Erro de conexão antes de enviar o corpo Sim A requisição não chegou.
Tempo de espera esgotado aguardando a resposta Só com Idempotency-Key Pode ter chegado e ter sido processada.
4xx diferente de 429 Não A requisição está errada. Repeti-la igual vai falhar igual.

Use um backoff exponencial: espere 1 segundo, depois 2, depois 4, com um máximo de cinco tentativas. Tentar de novo sem esperar só piora uma célula que já está saturada.

Limites

  • As requisições GET já são idempotentes. Não precisam do header.
  • A chave identifica uma operação, não um recurso. Dois pedidos diferentes levam duas chaves diferentes mesmo que liguem para o mesmo número.
  • A chave não muda o que a requisição faz. Se você tentar de novo com a mesma chave e outro corpo, o corpo que vale é o da primeira vez.

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