Configurações da decisão
engine, storeInput, storeOutput, timeoutMs, fallbackAction, onEngineError e shadow — o que cada configuração de runtime de uma decisão faz, seu padrão e seus limites — mais as configurações do workspace.
Cada decisão tem sete configurações de runtime, editadas no card Engine e runtime do editor (ou no nó Engine do builder visual). Elas fazem parte do schema, então os clientes da API recebem uma mudança quando você faz o deploy; o Playground usa as configurações do rascunho na hora.
"settings": {
"storeInput": true,
"storeOutput": true,
"timeoutMs": 5000,
"fallbackAction": "escalate",
"onEngineError": "error",
"engine": "laya",
"shadow": { "engine": "openai", "sampleRate": 0.1 }
}| Configuração | Tipo | Padrão | O que faz |
|---|---|---|---|
storeInput | boolean | true | Guarda o state da requisição no log de execuções. Arquivos são guardados como nome, tipo, tamanho e os primeiros 4.000 caracteres do texto — nunca o arquivo em si. |
storeOutput | boolean | true | Guarda result, confidence, níveis ponderados, composites e as distribuições completas no log de execuções. |
timeoutMs | integer, 500–30.000 | 5000 | O prazo do engine para uma chamada desta decisão, retries incluídos, em milissegundos. |
fallbackAction | continue, block, escalate, fallback | escalate | A ação quando nenhuma política combinou e o engine se recusou a responder uma pergunta, uma choice respondeu other ou uma pergunta ficou abaixo do seu minConfidence — e, com onEngineError: "fallback", quando o engine falha. |
onEngineError | error, fallback | error | O que a API responde quando o engine falha: o erro, ou um 200 com a ação de fallback. |
engine | jev, laya, openai | ausente | O engine que roda esta decisão. Ausente = o engine padrão do workspace. Veja Engines e BYOK. |
shadow | objeto: engine (jev, laya, openai) e sampleRate (0.01–1, padrão 0.1) | ausente | Um segundo engine que também responde uma amostra das execuções de produção em segundo plano, para comparação. Ausente = desligado. Veja shadow. |
engine
Deixe de fora para seguir o engine padrão do workspace (Configurações → Engine) — mudar o padrão então move todas essas decisões de uma vez. Defina-o para fixar uma decisão num engine: por exemplo, manter o workspace no Jev e rodar uma decisão de triagem multilíngue no Laya. No editor: Engine e runtime → Engine.
O engine precisa estar configurado em Configurações → Engine — para o Laya, um servidor Laya; para a OpenAI Decisions, uma chave OpenAI — senão as execuções respondem 424 ENGINE_NOT_CONFIGURED. Teste de novo no Playground limiares como minConfidence quando trocar de engine: cada modelo tem seu próprio perfil de confiança.
storeInput e storeOutput
Essas configurações só afetam o que é registrado no log; a resposta da API é sempre completa.
- Com
storeInputdesligado, as execuções mostram Não guardada (storeInput está desligado) no lugar do estado, e a execução não pode ser repetida no Playground. Estados inválidos também não são guardados. - Com
storeOutputdesligado, as execuções guardam o status, a ação, o motivo da ação, a latência, o modelo, os tokens e o custo estimado, mas não as respostas, a confiança, os níveis ponderados, os composites nem as distribuições.
Desligue-as em decisões que recebem dados pessoais ou sensíveis. Veja Segurança e dados.
Quando uma requisição traz um Idempotency-Key, a resposta dela — respostas incluídas — é guardada por 24 horas para que um retry possa ser reproduzido, seja qual for o valor de storeOutput. Veja Idempotência.
timeoutMs
O prazo do engine, de 500 ms a 30 s — 5 segundos por padrão. Ele cobre a chamada inteira ao engine, retries incluídos:
- A Dcision faz até 2 retries em erros de rede,
429,503,529e outras respostas5xxdo provedor, esperando 200 ms e depois 400 ms — ou oRetry-Afterdo provedor, quando ele o envia e cabe no prazo. - Um timeout não é repetido, nem um
4xxdiferente de429. - Na chave de engine compartilhada da Dcision, picos esperam por um slot livre dentro do mesmo prazo em vez de falhar na hora.
Uma chamada que estoura o tempo falha com 504 ENGINE_TIMEOUT — ou responde com a ação de fallback quando onEngineError é fallback. Aumente timeoutMs para estados grandes ou muitas perguntas; diminua-o em caminhos críticos de latência que têm um fallback. Dê ao seu próprio cliente HTTP um timeout alguns segundos maior que timeoutMs.
fallbackAction
A ação aplicada quando nenhuma política combinou e o engine se recusou a responder uma pergunta (uma recusa, só na OpenAI Decisions), uma pergunta choice respondeu a opção reservada other ou a confiança de uma pergunta ficou abaixo do seu minConfidence. O padrão, escalate, manda casos incertos para uma pessoa; continue na prática ignora a incerteza. Veja Políticas e ações.
A ação de fallback também é o que onEngineError: "fallback" responde quando o engine falha.
onEngineError
O que acontece quando o engine falha — um timeout, um provedor sobrecarregado ou inacessível, uma chave rejeitada, uma resposta fora do contrato — depois dos retries:
| Valor | A API responde |
|---|---|
error (padrão) | O erro, como 504 ENGINE_TIMEOUT ou 503 ENGINE_UNAVAILABLE. O seu código decide o que isso significa. |
fallback | 200 OK com action = o fallbackAction da decisão, action_reason = { "type": "engine_error", "code": "<engine error code>" }, result e confidence vazios, e zero tokens e custo. |
{
"decision_id": "dec_3fKq9ZtW1mXcV7bN2pLa",
"execution_id": "exec_Vn4Kp8Wd2Lq6Tz1Xc9Bs",
"schema": "lead-qualification",
"version": 3,
"result": {},
"confidence": {},
"action": "escalate",
"action_reason": { "type": "engine_error", "code": "ENGINE_TIMEOUT" },
"metrics": {
"latency_ms": 5004,
"engine": "jev",
"model": "jev-1.13.0",
"estimated_cost_usd": 0,
"input_tokens": 0,
"output_tokens": 0
}
}- Essas respostas não são cobradas e não são guardadas para idempotência: repetir com o mesmo
Idempotency-Keychega ao engine de novo. - A execução é registrada com status Error e o código de erro do engine.
- Isso cobre só falhas do engine (os códigos
ENGINE_*, excetoENGINE_NOT_CONFIGURED). Estados inválidos, cota, rate limits e uma chave de engine ausente continuam respondendo com seus erros.
Escolha fallback para caminhos que sempre precisam responder — um chat ou um assistente de voz, um checkout — e escolha um fallbackAction que seja seguro sem respostas, normalmente escalate. No editor: Engine e runtime → Se o engine falhar → Responder com a ação de fallback.
shadow
O modo sombra testa outro engine no tráfego real sem mudar o que os clientes recebem. Com settings.shadow, uma parte das execuções de produção — sampleRate, 10% por padrão, de 1% a 100% — também roda no motor sombra, em segundo plano, depois que a resposta está pronta:
"settings": {
"engine": "jev",
"shadow": { "engine": "openai", "sampleRate": 0.2 }
}- Só execuções de produção: a API, as URLs de webhook e o servidor MCP, na versão publicada. Execuções do Playground e respostas do GPT-Live nunca ganham uma execução sombra, e nada roda quando o motor sombra é o próprio engine que respondeu.
- Mesma entrada. O motor sombra recebe exatamente o que o engine principal recebeu: o mesmo estado, com os arquivos já lidos, e as mesmas perguntas.
- A resposta nunca muda.
result,actione os destinos vêm do engine principal; a chamada sombra não tem destinos e não faz a requisição esperar. - Sem créditos da Dcision. As execuções sombra não contam no volume incluído nem consomem créditos. Com a sua própria chave de provedor ou da OpenAI, o provedor cobra a chamada na sua conta.
- Guardada na execução: o modelo, as respostas, a confiança, a latência e os tokens de entrada do motor sombra — ou o código de erro quando a chamada sombra falhou. Uma chamada sombra que falha nunca faz a execução falhar.
O motor sombra precisa estar configurado em Configurações → Engine, como qualquer engine; senão as suas chamadas falham com ENGINE_NOT_CONFIGURED e aparecem como falhas. A Visão geral da decisão então mostra com que frequência os dois engines concordam — veja Visão geral e calibragem e Compare e rode engines em sombra. No editor: Engine e runtime → Motor sombra e Amostra da sombra (%). Como toda configuração, chega à produção quando você faz o deploy.
Configurações do workspace
Configurações no app reúne o que vale para todas as decisões do workspace. Todos no workspace podem abrir; Admins e o Proprietário alteram, e a Zona de perigo pertence só ao Proprietário — veja Time, papéis e conta.
| Configuração | Quem altera | Descrição |
|---|---|---|
| Nome | Admins e o Proprietário | O nome do workspace, de 2 a 80 caracteres. O slug do workspace é fixo. |
| Retenção do log de execuções | Admins e o Proprietário | 7, 14, 30, 90, 180 ou 365 dias. O seu plano limita: os logs são guardados pelo menor entre este valor e a retenção do plano — veja Execuções e uso. |
| Engine | Admins e o Proprietário | O engine padrão — Jev, Laya ou OpenAI Decisions — e como cada um é chamado: a chave ou o servidor da Dcision, ou a sua própria chave de provedor, chave OpenAI ou servidor Laya, com o modelo. Veja Engines e BYOK. Vale na hora para novas execuções, em toda decisão que não escolhe o próprio engine. |
| Organização | Admins e o Proprietário | Razão social, identificação fiscal, e-mail de cobrança, país, endereço e site — impressos nas faturas. |
| Membros | Admins para Membros e Leitores; o Proprietário para Admins | Quem está no workspace e seu papel — Proprietário, Admin, Membro ou Leitor — mais os convites. Veja Time, papéis e conta. |
| Destinos | Admins e o Proprietário | O segredo de assinatura das entregas e os segredos do workspace que os destinos usam. |
| Zona de perigo | O Proprietário | Excluir o workspace. |
Versões e deploy
Rascunhos, versões imutáveis, deploys, slugs, desativar, duplicar e excluir decisões — e o que os seus clientes da API veem em cada etapa.
Templates
Os dezenove templates prontos — o que cada um decide, suas perguntas, composites e políticas, os padrões que demonstra — e como começar uma decisão a partir de um deles.