Perguntas
Perguntas de choice, score e probability — instruções e critérios estruturados, o que a API devolve para cada uma, níveis ponderados, a opção reservada other e a confiança mínima.
Perguntas são o que uma decisão responde sobre o estado. Uma decisão tem de 1 a 64 perguntas, todas respondidas em uma única chamada ao engine: o Jev avalia cada uma delas de forma independente e em paralelo sobre o mesmo estado. Cada pergunta vira uma chave nos objetos result e confidence da resposta, na ordem em que você as define.
| Tipo | Use para | result[key] | Exemplo |
|---|---|---|---|
choice | Escolher uma opção: um time, uma categoria, uma ferramenta | Um dos valores das suas opções (string) | "sales" |
score | Posicionar o estado numa escala ordenada | O rótulo do nível mais provável (string) | "high" |
probability | Uma pergunta de sim/não | Probabilidade de sim, de 0 a 1 | 0.9412 |
Propriedades comuns
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
key | string | Sim | snake_case, única na decisão. Vira a chave JSON na resposta. |
type | string | Sim | choice, score ou probability. |
instructions | string, objeto ou array | Sim | A pergunta que o engine responde: texto ou JSON estruturado. Até 8.000 caracteres (no JSON conta o tamanho serializado). |
minConfidence | number | Não | De 0 a 1. Abaixo dela, a decisão aplica a ação de fallback — veja abaixo. |
Choice
{
"key": "route",
"type": "choice",
"instructions": "Which team should receive this lead?",
"options": [
{ "value": "sales", "description": "high intent, ready to talk to sales" },
{ "value": "sdr", "description": "some intent, needs qualification" },
{ "value": "nurture", "description": "early stage, send content" }
]
}optionsprecisa de pelo menos 2 e no máximo 254 opções, maisother— 255 no total, o máximo do Jev.valuesegue as regras de chaves e precisa ser único dentro da pergunta.descriptiondiz ao engine quando a opção se aplica: texto ou JSON, até 2.000 caracteres. É opcional — omita-a, ou defina comonull, quando o valor já diz tudo ("yes_refund"). As descrições decidem a precisão: contraste opções parecidas e acrescente exclusões como "não para clientes atuais".- A ordem importa. O Jev pode tender para a opção listada primeiro. Teste as perguntas importantes com as opções reordenadas no Playground e confira se a resposta continua a mesma.
A opção reservada other
Toda pergunta de choice tem uma opção other. A Dcision a adiciona automaticamente como a última opção, com a descrição none of the options above. Ela não pode ser removida, mas você pode descrevê-la incluindo-a em options — onde quer que você a coloque, ela é movida para o final:
{ "value": "other", "description": "not about our product, or a language we don't support" }Sem other, o engine é forçado a escolher a opção menos errada. Com ela, "nenhuma destas" vira uma resposta explícita: quando uma pergunta de choice responde other e nenhuma política casou antes, a decisão aplica a sua ação de fallback com action_reason.type = "other_option". Veja Políticas e ações.
O que a API devolve
result.route— a opção escolhida, por exemplo"sales"(ou"other").confidence.route— o quanto a opção escolhida fica acima de uma divisão igual entre todas as opções, de 0 a 1 — veja Confiança.- Com
?include=probabilities,probabilities.routetraz uma probabilidade por opção,otherincluída.
Políticas sobre uma resposta de choice só podem usar eq e neq. A comparação ignora maiúsculas/minúsculas e espaços nas pontas.
Score
{
"key": "priority",
"type": "score",
"instructions": "How urgent is it to answer this lead?",
"scale": ["low", "medium", "high", "critical"]
}scalelista de 2 a 10 níveis, do mais baixo ao mais alto. Um nível é um rótulo (até 2.000 caracteres) ou uma rubrica estruturada com umlabel. Os rótulos precisam ser únicos.result.priorityé o rótulo do nível mais provável — não uma média — econfidence.prioritydiz o quanto a distribuição está concentrada em torno dele.scores.priorityé o nível ponderado: a média dos níveis ponderada pelas probabilidades, contando a partir de 1. Na escala acima,2.81fica entremedium(2) ehigh(3), mais perto dehigh. Use-o para agir entre níveis.- Com
?include=probabilities,probabilities.prioritytraz uma probabilidade por rótulo, na ordem da escala.
Políticas comparam níveis, numerados a partir de 1: na escala acima, low é 1 e critical é 4.
- Sobre a resposta (
"on": "output"), uma regra usa o número do nível ("value": 3) ou o rótulo ("value": "high"), com qualquer operador:{ "field": "priority", "operator": "gte", "value": "high", "action": "escalate" }casa comhighecritical. Um rótulo que não está na escala nunca casa. - Sobre o nível ponderado (
"on": "score"), uma regra comparascores.prioritycom um número:{ "field": "priority", "on": "score", "operator": "gte", "value": 3.5, "action": "escalate" }dispara quando o peso pende paracritical, mesmo quehighseja o nível mais provável.
Probability
{
"key": "purchase_intent",
"type": "probability",
"instructions": "Does this lead have real intent to buy in the next 30 days?",
"criteria": {
"yes": "asks for pricing, a demo, a quote or a start date",
"no": "just browsing, student, vendor or spam"
}
}criteria.yesecriteria.nosão opcionais — texto ou JSON, até 2.000 caracteres cada — e dizem o que conta como sim e como não. Mantenha-os alinhados com as instruções:yesdeve descrever o caso do sim.result.purchase_intenté a probabilidade de sim, entre 0 e 1, arredondada para 4 casas decimais.confidence.purchase_intenté|2p − 1|: a distância de um cara ou coroa.0.03(um não confiante) e0.97(um sim confiante) têm ambos confiança0.94;0.5tem confiança0.- Com
?include=probabilities,probabilities.purchase_intenté{ "yes": p, "no": 1 − p }.
Políticas comparam a probabilidade com um número, por exemplo { "field": "purchase_intent", "operator": "gte", "value": 0.8, "action": "continue" }.
Instruções e critérios estruturados
O Jev lê estrutura nativamente. Onde quer que uma pergunta tenha texto — instructions, description das opções, níveis de score, criteria.yes e criteria.no — você pode enviar um objeto ou array JSON no lugar. A estrutura ajuda quando uma pergunta tem várias partes, ou quando precisa de dados de apoio como uma taxonomia, um schema ou uma linha de banco de dados: as chaves rotulam cada parte.
{
"key": "duplicate_candidate",
"type": "probability",
"instructions": {
"potential_duplicate": { "name": "John Smith", "location": "Oakland, California", "last_employer": "Google" },
"question": "Is the resume in `resume` for the same person as `potential_duplicate`?"
}
}- Aponte para os dados com crases. Cite campos do estado e chaves da instrução entre crases —
`resume`,`ticket.messages[0].text`— para dizer ao engine exatamente o que olhar. - Dê uma rubrica às opções. Uma descrição de opção como
{ "what": "Charges, invoices, refunds", "not_for": "Order tracking", "examples": ["I was charged twice"] }deixa mais nítida a fronteira entre opções vizinhas. - Os limites são os mesmos do texto, medidos sobre o JSON serializado: 8.000 caracteres para instruções, 2.000 para uma descrição de opção, um nível de score ou um critério. Objetos e arrays não podem ser vazios.
- No editor, cole um objeto ou array JSON no campo: ele é guardado como estrutura e marcado como estruturada. Qualquer coisa que não seja JSON válido continua sendo texto.
Níveis de score estruturados
Um nível de score pode ser um objeto com um label — o rótulo é o que result devolve e o que as políticas comparam; o objeto inteiro é o que o engine lê:
{
"key": "bug_severity",
"type": "score",
"instructions": "If this describes a bug, how severe is it for the customer?",
"scale": ["cosmetic", "minor", "major", { "label": "critical", "rubric": "outage, data loss, security issue or money at risk" }]
}O rótulo tem de 1 a 255 caracteres; o nível inteiro, serializado, até 2.000. Níveis simples e estruturados podem ser misturados numa mesma escala. O editor adiciona níveis como rótulos simples e mostra os estruturados com um ícone de chaves — o template Support Ticket Triage começa com um.
Confiança mínima
Qualquer pergunta pode definir minConfidence entre 0 e 1. Quando a confiança da resposta fica abaixo dela e nenhuma política casou antes, a decisão aplica a sua ação de fallback com action_reason.type = "low_confidence":
{ "type": "low_confidence", "question": "route", "confidence": 0.52, "minConfidence": 0.8 }No editor, a chave Confiança mínima começa em 80%. Sem ela, respostas de baixa confiança continuam dando continue.
Para uma pergunta de probability, a confiança é |2p − 1|, então uma confiança mínima sinaliza uma faixa de probabilidades em torno de 0,5: 0.8 sinaliza todo p entre 0,1 e 0,9; 0.6, todo p entre 0,2 e 0,8. O editor mostra a faixa ao lado do controle deslizante. Veja Confiança e probabilidades e Lidando com baixa confiança e other.
Dicas
- Pergunte uma coisa por pergunta. Divida "isto é spam urgente?" numa probability (
spam) e num score (urgency) — custam uma chamada do mesmo jeito. - Formule as instruções como uma pergunta literal sobre o estado: "Qual time deve receber este lead?".
- Prefira probability para sim/não — é mais fácil aplicar um limiar ao número do que a uma choice de duas opções.
- Prefira score para níveis ordenados — assim as políticas podem usar
gte/ltesobre o nível e limiares sobre o nível ponderado. - Escreva as descrições das opções como critérios, não como rótulos, e torne as vizinhas mutuamente exclusivas. Se o Playground sinalizar um quase empate, as descrições se sobrepõem.
- Coloque os fatos do negócio em
context, não em cada instrução. - Deixe contas, contagens e datas no código e envie os resultados no estado.
- A ordem importa: quando várias perguntas respondem
otherou ficam abaixo da sua confiança mínima, a primeira na ordem das perguntas é a informada emaction_reason.
Mais em Escrevendo boas perguntas.
Entradas — texto, JSON, imagens, áudio e documentos
O que uma decisão consegue ler — texto, JSON estruturado, imagens, áudios e documentos (PDF, Word, Excel, PowerPoint, CSV e mais) — e como cada um chega ao Jev, ao Laya ou à OpenAI Decisions.
Composites
Combine várias respostas num único número com pesos que você controla — Σ(peso × valor) / Σ|peso| — devolva-o em composites e use-o em políticas.