Gatilhos de destino

Quando um destino dispara — condições sobre respostas, confiança, níveis ponderados e composites, ações finais, uma confiança mínima por rota, níveis de nota, limiares de probabilidade — e em que ordem.

Todo destino tem um objeto when. Ele dispara quando a ação final da decisão é uma das when.actions (se você definir alguma) e todas as condições em when.conditions valem:

{
  "conditions": [
    { "field": "route", "on": "output", "operator": "eq", "value": "sales" },
    { "field": "route", "on": "confidence", "operator": "gte", "value": 0.8 }
  ],
  "actions": ["continue"]
}
PropriedadeTipoPadrãoDescrição
conditionsarray[]Até 5 condições, todas precisam valer. Mesmo formato de uma condição de política: field, on (output, confidence ou score), operator e value.
actionsarray—Dispara só quando a ação final é uma destas: continue, block, escalate, fallback.

Um when vazio dispara depois de toda decisão.

Por opção

O gatilho mais comum, e o que o seletor Destino de uma opção cria: a resposta da pergunta é igual à opção.

{ "conditions": [{ "field": "route", "on": "output", "operator": "eq", "value": "sales" }] }

Use neq para "toda rota exceto spam". A opção reservada other é uma resposta como qualquer outra: um destino em route = other dispara quando nenhuma opção se encaixa — enquanto a ação de fallback da decisão (escalate por padrão) diz ao seu código que uma pessoa deve olhar.

Confiança mínima por rota

O campo Confiança mínima de um destino acrescenta uma condição confidence ≥ sobre a mesma pergunta, de modo que a rota só dispara quando o engine tem certeza suficiente:

{
  "conditions": [
    { "field": "route", "on": "output", "operator": "eq", "value": "sales" },
    { "field": "route", "on": "confidence", "operator": "gte", "value": 0.8 }
  ]
}

Ela é independente da minConfidence da própria pergunta, que muda a ação: uma resposta de baixa confiança recebe a ação de fallback e action_reason.type = "low_confidence", independentemente dos destinos. Combine as duas, ou dê a cada rota o seu próprio limiar — uma rota de reembolso pode exigir 0,9 enquanto uma rota de "enviar um artigo" aceita 0,6. Veja roteamento por confiança.

Por nível de nota

Os seletores de uma pergunta de nota criam uma condição sobre o nível mais provável:

{ "conditions": [{ "field": "priority", "on": "output", "operator": "eq", "value": "critical" }] }

Os níveis também podem ser comparados por número (1 = o primeiro nível) com qualquer operador — "operator": "gte", "value": 3 é high ou critical numa escala de quatro níveis — ou pelo nível ponderado com "on": "score", que pode cair entre níveis: "on": "score", "operator": "gte", "value": 3.5.

Limiares de probabilidade

Destino quando … ≥ … numa pergunta de probabilidade cria um limiar sobre a probabilidade de yes, 0,8 por padrão:

{ "conditions": [{ "field": "purchase_intent", "on": "output", "operator": "gte", "value": 0.8 }] }

Composites e outras respostas

Uma condição pode usar qualquer pergunta ou composite da decisão, então um destino não precisa seguir a pergunta a cujo painel pertence: lead_score ≥ 0.75 manda leads quentes para um workflow, qualquer que seja a rota.

{
  "conditions": [
    { "field": "lead_score", "on": "output", "operator": "gte", "value": 0.75 },
    { "field": "route", "on": "output", "operator": "neq", "value": "spam" }
  ]
}

Ações finais

actions liga um destino ao veredito em vez de a uma resposta — todo escalate posta no Slack, todo block abre um ticket de moderação:

{ "actions": ["escalate"] }

Com conditions e actions juntos, os dois precisam valer.

Validação

As condições seguem as regras das condições de política, e são checadas quando você salva ou publica — 422 INVALID_SCHEMA caso contrário:

  • o field precisa ser uma pergunta ou um composite da decisão;
  • respostas de escolha só aceitam eq e neq, e o valor precisa ser uma das opções;
  • probabilidades e confiança são números de 0 a 1 — 0.7, não 70;
  • níveis de nota vão de 1 até o número de níveis, ou usam o rótulo de um nível;
  • composites vão de −1 a 1 (0 a 1 com pesos positivos).

Avaliação

Depois que a ação é escolhida, a Dcision percorre os destinos na ordem do schema:

  1. Um destino desligado ("enabled": false) é ignorado.
  2. As suas actions e conditions são checadas. Destinos que não combinam não deixam entrada.
  3. Os seus params são resolvidos. Quando um param marcado como required não tem valor, o destino não dispara: a sua entrada diz "status": "skipped", "reason": "missing_param" e nomeia o param.
  4. No máximo 10 destinos disparam por execução, e no máximo 3 deles podem fazer quem chama esperar — respostas de LLM e agentes no modo sync. Além disso, a entrada diz "status": "skipped", "reason": "limit".
  5. O restante roda: respostas e funções são devolvidas, chamadas de LLM e de agentes sync são aguardadas em paralelo, e entregas em segundo plano entram na fila.

Quando o engine falha

Com onEngineError: "fallback", uma falha do engine responde 200 com a ação de fallback e sem respostas. Então:

  • destinos com condições não disparam — não há resposta para comparar;
  • destinos sem condições disparam, filtrados por actions quando definido — o lugar certo para um alerta como escalate → avisar a pessoa de plantão;
  • as variáveis result.*, confidence.*, scores.* e composites.* são null.

Respostas de fallback são repetidas de verdade

Fallbacks por erro do engine não são guardados para idempotência: repetir a chamada com o mesmo Idempotency-Key roda a decisão de novo, e os seus destinos disparam de novo com novos IDs de entrega. Deduplique esses alertas do seu lado — por exemplo, pelo ID do seu próprio registro.

Replays

Um replay idempotente devolve a resposta guardada — incluindo as suas entradas de destinations e os seus IDs de entrega — e não dispara nada de novo. Os SDKs, porém, despacham de novo as funções de uma resposta reproduzida, então torne os handlers de função idempotentes.

Nesta página