Visão geral e calibragem
Leia a aba Visão geral de uma decisão — execuções, taxa de sucesso, latência, custo, ações, motivos e estatísticas por pergunta — e aja sobre cada sugestão de calibragem, com os limiares por trás dela.
A Visão geral é a primeira aba de toda decisão. Ela responde três perguntas sobre o período que você escolher: está funcionando, quanto custa e onde falha ou hesita — e o que deveria mudar? O editor fica na aba Editor, ao lado; decisões novas e duplicadas abrem direto no editor.
Escolha o período — 7, 30 (o padrão) ou 90 dias — e o tráfego: Todo o tráfego, API ou Playground. Todos no workspace podem ver a Visão geral, inclusive os Viewers. Os dias são contados em UTC.
Indicadores
| Indicador | O que é |
|---|---|
| Execuções | Todas as execuções do período — bem-sucedidas ou não. A seta compara com o período anterior de mesma duração (novo quando aquele não teve nenhuma). |
| Taxa de sucesso | A parcela de execuções sem erro, com o número de erros. Fica vermelha a partir de 2% de erros. |
| Latência p50 · p95 | A latência mediana e o percentil 95 das execuções bem-sucedidas. |
| Tokens de entrada / execução | A média de tokens de entrada das execuções bem-sucedidas — o que determina o custo e a latência do engine. |
| Custo do engine (est.) | A soma do custo estimado do engine nas execuções, e quantas versões rodaram no período. |
Abaixo deles:
- Execuções por dia — execuções e, tracejados, os erros.
- Ação final — a parcela de cada ação que quem chamou recebeu (execuções bem-sucedidas e fallbacks por erro do engine).
- Por quê — qual parte da decisão escolheu a ação: Uma regra de política casou, Respondeu "other", O engine se recusou a responder (uma recusa), Abaixo da confiança mínima, Engine falhou → fallback ou Nenhuma regra casou (continue) — e quantas vezes cada regra casou (Regras que casaram: #1 × 120).
- Erros — execuções com falha por código de erro; cada código abre Execuções filtradas por erros. Erros nunca são cobrados.
- Tráfego — execuções pela API e pelo Playground. Versões — execuções por versão publicada, e o rascunho para as execuções do Playground.
Perguntas
Um card por pergunta, a partir de uma amostra das últimas 2.000 execuções bem-sucedidas do período. As estatísticas precisam das respostas, então só cobrem execuções guardadas com o storeOutput da decisão ligado.
| Métrica | O que mostra | Destacada a partir de |
|---|---|---|
| Respostas | A parcela de cada opção ou nível. Perguntas de probabilidade mostram a distribuição de p(sim) em décimos, de 0 a 1. | — |
| Confiança | Um histograma de 20 barras de 0,05, de 0 a 1. Respostas confiantes ficam à direita. | — |
| Confiança média | A confiança média das respostas. | abaixo de 0,6 |
| Abaixo do mínimo | A parcela de respostas abaixo do minConfidence da pergunta — execuções que recebem a ação de fallback, a menos que uma política tenha casado antes. | 20% |
| Quase empates (choice, score) | A parcela de respostas cujas duas opções ou níveis mais prováveis ficaram a menos de 0,15 de distância, e o par confundido com mais frequência. | 15% |
| Indecisas (probability) | A parcela de probabilidades entre 0,35 e 0,65 — nem sim, nem não. | 30% |
| "other" (choice) | A parcela de respostas em que nenhuma opção serviu. | 10% |
| p(sim) médio (probability) | A probabilidade média de sim. | — |
Ajustar, em cada card, abre a pergunta no editor.
Destinos
Para decisões com destinos, uma tabela conta, por destino e no período:
| Coluna | Conta |
|---|---|
| Devolvidas | Respostas devolvidas na resposta — funções, respostas fixas e respostas de LLM e de agente. |
| Entregues | Entregas que deram certo: webhooks, requisições de API, workflows e repasses para agentes. |
| Falharam | Entregas que falharam, e chamadas de LLM ou de agente que falharam. |
| Pendentes | Entregas ainda aguardando uma tentativa. |
Modo sombra
Para decisões com settings.shadow, um card Modo sombra compara o engine principal com o motor sombra nas execuções de produção amostradas do período (até as 2.000 mais recentes):
| Métrica | O que mostra |
|---|---|
| Concordância | A parcela de execuções sombra em que todas as perguntas tiveram a mesma resposta nos dois engines. |
| Execuções sombra | Quantas execuções foram comparadas, e quantas falharam no motor sombra — as que falharam não são comparadas. |
| Latência p50 da sombra | A latência mediana do motor sombra, para comparar com a Latência p50 do engine principal. |
| Por pergunta | A concordância de cada pergunta, verde a partir de 90%, âmbar a partir de 70%, vermelha abaixo disso. |
Duas respostas concordam quando uma pergunta de escolha escolheu a mesma opção, uma pergunta de nota o mesmo nível, ou uma pergunta de probabilidade caiu do mesmo lado de 0,5 — as duas acima ou as duas abaixo. Uma pergunta que algum dos engines se recusou a responder não entra na conta. Leia as taxas por pergunta das perguntas que as suas políticas usam antes de trocar o settings.engine — veja Compare e rode engines em sombra.
Sugestões de calibragem
O card Sugestões de calibragem transforma os números em conselhos. Cada sugestão cita a medição por trás dela, para que você possa conferir, e leva ao campo a mudar com Corrigir no editor. Elas são ordenadas por gravidade — alta, média, baixa, info.
- Abaixo de 20 execuções no período, o card só diz que a amostra é pequena — nada de conselho baseado em ruído.
- Os conselhos por pergunta também precisam de 20 respostas daquela pergunta na amostra.
- As sugestões apontam para o rascunho — o que você edita — ou para a versão publicada quando o rascunho é inválido.
| Sugestão | Aparece quando | Gravidade | O que fazer |
|---|---|---|---|
| As estatísticas por pergunta estão desligadas | A decisão não guarda as saídas. | info | Ligue Guardar a saída para receber conselhos por pergunta. |
| Só 12 execuções neste período | Menos de 20 execuções. | info | Rode entradas representativas no Playground ou envie tráfego real. |
| 5% das execuções falharam (principalmente ENGINE_TIMEOUT, 41) | 2% ou mais das execuções falharam — alta a partir de 10%. | média, alta | Por código: aumente timeoutMs ou responda com a ação de fallback (ENGINE_TIMEOUT); distribua os picos ou use sua própria chave (ENGINE_RATE_LIMITED); ligue o fallback por erro do engine (ENGINE_UNAVAILABLE); corrija o que quem chama envia (INVALID_STATE); senão, leia os erros em Execuções. |
| 34% das execuções terminam na ação de fallback (escalate) | 30% ou mais das execuções receberam a ação de fallback por causa de other ou de baixa confiança. | média | Leia os conselhos por pergunta antes de afrouxar os limiares. |
| "route" respondeu "other" em 14% das execuções | Uma pergunta choice respondeu other em 10% ou mais das suas respostas — alta a partir de 25%. | média, alta | Veja essas execuções; adicione uma opção para o caso comum ou amplie as descrições. |
| "route" fica em quase empate em 22% das execuções (principalmente "sales" vs "sdr") | As duas respostas mais prováveis de uma pergunta choice ou score ficaram a menos de 0,15 de distância em 15% ou mais das suas respostas — alta a partir de 30%. | média, alta | Contraste as duas descrições e adicione exclusões ("não para clientes atuais"); o Jev tende para a primeira opção, então coloque a mais específica primeiro. Para níveis, descreva cada um com critérios concretos. |
| A confiança média de "priority" é 0,52 | A confiança média de uma pergunta está abaixo de 0,6. | média | Faça uma pergunta literal, divida as compostas, aponte os campos do state que importam com crases ou acrescente contexto em context. |
| minConfidence 0,8 manda 27% de "route" para escalate | 20% ou mais das respostas de uma pergunta ficam abaixo do seu minConfidence. | média | O card simula a parcela abaixo de 0,5, 0,6, 0,7, 0,8 e 0,9 e indica o maior limiar que a mantém em 10% ou menos. Baixe o limiar só se as respostas perto dele costumam estar certas; senão, melhore a pergunta primeiro. |
| Respostas incertas de "route" podem disparar regras de bloqueio | A pergunta não tem minConfidence, a decisão tem uma regra block e algumas respostas ficam abaixo de 0,7. | baixa | Defina um minConfidence para que respostas incertas recebam a ação de fallback em vez de serem bloqueadas. |
| "purchase_intent" fica indecisa (p entre 0,35 e 0,65) em 31% das execuções | Uma probabilidade entre 0,35 e 0,65 em 30% ou mais das suas respostas. | média | Adicione critérios de conta como sim e conta como não. |
| "route" respondeu "sales" em 93% das execuções | Uma resposta de uma pergunta choice ou score em 90% ou mais de pelo menos 50 respostas. | baixa | Ou o tráfego é uniforme, ou a pergunta não discrimina: deixe as outras opções mais nítidas ou remova a pergunta para economizar tokens. |
| "spam" nunca escolhida em 412 execuções | Uma opção ou nível nunca foi escolhido em pelo menos 200 respostas (exceto other). | baixa | Confira a descrição dela ou remova-a se esse caso não acontece. |
| A regra #3 (IF route eq spam THEN block) nunca casou em 1.250 execuções | Pelo menos 100 execuções e uma regra que nunca casou. | baixa | Uma regra anterior pode sempre vencer, ou o valor está fora de alcance. |
| A regra #1 (…) casa com 97% das execuções | Pelo menos 100 execuções e uma regra casou com 95% ou mais delas. | baixa | A regra pode ser mais ampla do que o pretendido — as regras seguintes nunca têm chance. |
| 2.480 tokens de entrada por decisão em média | Mais de 2.000 tokens de entrada por execução em média. | baixa | Encurte as instruções e o context, junte perguntas, envie states menores. |
| A latência p95 é 3,4 s | A latência p95 está acima de 3 s. | baixa | A latência cresce com os tokens de entrada; com prazos apertados, responda com a ação de fallback em erros do engine. |
| O destino "sales_crm" falhou em 12% das entregas | Pelo menos 10 entregas entregues ou com falha, e 5% ou mais falharam — alta a partir de 25%. | média, alta | Abra uma execução para ler a resposta do receptor, corrija o destino e reenvie. |
Calibre, passo a passo
Comece pela primeira sugestão. Abra Execuções filtradas pela decisão e leia algumas execuções por trás do número — suas entradas, respostas e distribuições.
Mude o rascunho no editor: descrições de opções, instruções, critérios, um limiar, uma regra. Mude uma coisa de cada vez.
Rode essas entradas de novo no Playground — Rodar esta entrada de novo no Playground, a partir de uma execução — e compare com a execução anterior.
Publique e acompanhe os dias seguintes com o filtro de tráfego API: a Visão geral inclui todas as versões do período, e Versões mostra como as execuções se dividem entre elas.
Limiares como minConfidence devem seguir o custo de uma resposta errada, não só a taxa de fallback: uma rota de reembolso merece uma régua mais alta que "enviar um artigo". Veja Lidando com baixa confiança e other e Escrevendo boas perguntas.
Calibragem com resultados reais
A Visão geral mede o quanto o engine está seguro e consistente — não se ele acertou. Para comparar a confiança com os resultados reais, exporte as execuções com GET /v1/executions e cruze-as com o que aconteceu no seu sistema.
Lidando com baixa confiança e other
Desenhe decisões que admitem incerteza — a opção reservada other, a confiança mínima, políticas de confiança, a ação de fallback, quase empates e o fallback por erro de engine.
Retries idempotentes
Um cliente Dcision pronto para produção — chaves de idempotência, timeouts, quais erros repetir, backoff exponencial com Retry-After — em JavaScript e Python.