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"]
}| Propriedade | Tipo | Padrão | Descrição |
|---|---|---|---|
conditions | array | [] | 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. |
actions | array | — | 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
fieldprecisa ser uma pergunta ou um composite da decisão; - respostas de escolha só aceitam
eqeneq, e o valor precisa ser uma das opções; - probabilidades e confiança são números de 0 a 1 —
0.7, não70; - 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:
- Um destino desligado (
"enabled": false) é ignorado. - As suas
actionseconditionssão checadas. Destinos que não combinam não deixam entrada. - Os seus params são resolvidos. Quando um param marcado como
requirednão tem valor, o destino não dispara: a sua entrada diz"status": "skipped", "reason": "missing_param"e nomeia oparam. - 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". - O restante roda: respostas e funções são devolvidas, chamadas de LLM e de agentes
syncsã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
actionsquando definido — o lugar certo para um alerta como escalate → avisar a pessoa de plantão; - as variáveis
result.*,confidence.*,scores.*ecomposites.*sãonull.
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.
Visão geral dos destinos
O que acontece depois de uma decisão — por opção, nível, limiar de probabilidade ou ação final — respostas fixas, saídas estruturadas, LLMs, seu agente, workflows, webhooks assinados, requisições HTTP e funções.
Params e templates
Mapeie valores para um destino — params de um campo ou de um valor fixo, params obrigatórios, variáveis {{…}} em URLs, headers, bodies e textos, e como cada lugar os codifica por você.