Políticas e ações

Como as regras de política com condições AND são escritas e avaliadas, e como a action e o action_reason de cada resposta são calculados — política, opção other, baixa confiança, padrão ou erro do engine.

Perguntas produzem respostas; políticas transformam respostas numa ação sobre a qual o seu código pode decidir. Toda resposta bem-sucedida traz tanto a action quanto o action_reason que a explica.

Ações

AçãoSignificado por convenção
continueSeguir pelo caminho automatizado.
blockParar: rejeitar, descartar ou pôr o evento em quarentena.
escalatePassar para uma pessoa ou um nível acima.
fallbackSeguir pelo seu caminho de fallback — por exemplo, um modelo maior ou mais recuperação de contexto.

Ações são rótulos para o seu código. A Dcision nunca bloqueia nem redireciona nada por conta própria: uma decisão cuja ação é block ainda responde 200 OK, e a sua aplicação aplica a ação.

Regras de política

Uma regra é uma condição, condições and opcionais e a ação a devolver quando todas elas valem:

{ "field": "route", "on": "output", "operator": "eq", "value": "spam", "action": "block" }
PropriedadeTipoPadrãoDescrição
fieldstring—A chave de uma pergunta — ou de um composite — desta decisão.
onstringoutputO que comparar: a resposta (output), a sua confidence ou o nível ponderado de uma pergunta de score (score).
operatorstring—eq, neq, gt, gte, lt ou lte.
valuestring ou number—O valor a comparar (strings de até 255 caracteres).
andarray—Até 5 condições a mais — cada uma com seus próprios field, on, operator e value — que também precisam valer.
actionstring—continue, block, escalate ou fallback.

Uma decisão tem até 50 regras. O que value e operator aceitam depende do campo e de on:

CampoonComparavalueOperadores
pergunta de choiceoutputa opção escolhida (maiúsculas/minúsculas e espaços nas pontas ignorados)uma opção, como stringeq, neq
pergunta de scoreoutputo nível mais provável (1 = o mais baixo)um número de nível ou um rótulo de níveltodos os seis
pergunta de scorescoreo nível ponderado, a partir de 1 — ele pode cair entre níveis, como 2,4um númerotodos os seis
pergunta de probabilityoutputa probabilidade de simum número de 0 a 1todos os seis
qualquer perguntaconfidencea confiança da respostaum número de 0 a 1todos os seis
compositeoutputo valor do compositeum númerotodos os seis

Regras que violam essas restrições tornam o schema inválido (422 INVALID_SCHEMA), por exemplo "Choice outputs only support eq / neq.", "Unknown question \"intent\".", "Only score questions have a weighted level." ou "Compare a composite's value with a number.".

Condições AND

Regras compostas são do que a maioria dos padrões precisa. Toda condição de uma regra precisa valer para a regra casar. Dos templates:

TemplateRegra
ticket-triagecategory = bug_report AND bug_severity ≥ 4 → escalate
voice-bankingintent = approve_transfer AND confiança de intent < 0.9 → escalate
customer-service-routerintent = technical_issue AND nível ponderado de complexity ≥ 2.5 → escalate
resume-screeningsenior_ic < 0.35 AND eng_manager < 0.35 → block

Em JSON, a primeira fica assim:

{
  "field": "category",
  "on": "output",
  "operator": "eq",
  "value": "bug_report",
  "and": [{ "field": "bug_severity", "on": "output", "operator": "gte", "value": 4 }],
  "action": "escalate"
}

As condições de uma regra podem usar perguntas e composites diferentes, ou a mesma pergunta duas vezes — a sua resposta e a sua confiança, como em voice-banking. Para OR, escreva duas regras com a mesma ação.

Como a ação é calculada

Depois que o engine responde, a Dcision calcula os composites e então percorre cinco passos, parando no primeiro que se aplica:

Políticas, em ordem. A primeira regra cujas condições valem todas define a ação. action_reason → { "type": "policy", "rule": 1 } — rule é o índice a partir de 0 da regra (o app mostra como "regra de política #2").

Uma pergunta que o engine se recusou a responder. O OpenAI Decisions pode recusar uma pergunta; a primeira pergunta recusada, na ordem das perguntas, dispara a ação de fallback da decisão. Ela não tem entrada em result, e as políticas sobre ela nunca casam. action_reason → { "type": "refusal", "question": "route" }

Uma choice respondeu other. A primeira pergunta de choice, na ordem das perguntas, cuja resposta é a opção reservada other dispara a ação de fallback da decisão (settings.fallbackAction, escalate por padrão). action_reason → { "type": "other_option", "question": "route" }

Baixa confiança. A primeira pergunta, na ordem das perguntas, cuja confiança fica abaixo do seu minConfidence dispara a ação de fallback. action_reason → { "type": "low_confidence", "question": "route", "confidence": 0.52, "minConfidence": 0.8 }

Padrão. Nada se aplicou: a ação é continue. action_reason → { "type": "default" }

As políticas sempre vencem: uma regra como route eq other → block tem precedência sobre a ação de fallback.

Existe um sexto motivo fora desses passos. Quando o engine falha e o onEngineError da decisão é fallback, não há respostas para avaliar: a resposta traz a ação de fallback e { "type": "engine_error", "code": "ENGINE_TIMEOUT" }.

Exemplo completo

O template Lead Qualification tem duas regras e a ação de fallback padrão, escalate:

[
  { "field": "route", "on": "output", "operator": "eq", "value": "spam", "action": "block" },
  { "field": "purchase_intent", "on": "confidence", "operator": "lt", "value": 0.6, "action": "escalate" }
]
resultconfidence.purchase_intentactionaction_reason
route: "sales", purchase_intent: 0.94120.8824continue{ "type": "default" }
route: "spam", purchase_intent: 0.030.94block{ "type": "policy", "rule": 0 }
route: "sdr", purchase_intent: 0.450.1escalate{ "type": "policy", "rule": 1 }
route: "other", purchase_intent: 0.150.7escalate{ "type": "other_option", "question": "route" }

A confiança de uma probabilidade é |2p − 1|, então a regra 1 escala todo lead cujo purchase_intent fica entre 0,2 e 0,8.

No editor

O card Políticas lê cada regra como IF condição THEN ação:

  1. Adicionar regra cria uma regra sobre a primeira pergunta.
  2. Escolha o campo — perguntas, depois composites — e o que comparar: resposta, confiança ou, para uma pergunta de score, nível ponderado. Depois, o operador e o valor.
  3. + AND adiciona uma condição, até 5. Cada uma tem seu próprio campo, comparação, operador e valor.
  4. Escolha a ação depois de THEN.

As regras são avaliadas de cima para baixo. Renomear ou apagar uma pergunta atualiza ou remove as regras que começam por ela; condições and e termos de composites que apontam para uma pergunta que não existe mais são sinalizados como problemas a corrigir.

Agindo sobre o resultado

switch (decision.action) {
  case "continue":
    return routeTo(decision.result.route);
  case "block":
    return discard(lead);
  case "escalate":
    return sendToHuman(lead, decision.action_reason);
  case "fallback":
    return askLargerModel(lead);
}

Erros do engine: um erro ou uma ação — você escolhe

Por padrão, quando o engine estoura o tempo ou falha, a API devolve um erro como 504 ENGINE_TIMEOUT e nenhuma ação: decida no seu código o que um erro significa — normalmente o mesmo caminho de escalate. Defina onEngineError como fallback para receber, em vez disso, um 200 com a ação de fallback e action_reason.type = "engine_error"; essas respostas não são cobradas. Veja Configurações da decisão e Erros.

Dicas

  • Coloque as regras mais específicas primeiro: a primeira que casar vence. Regras compostas (and) costumam vir antes das simples que elas refinam.
  • Use on: "confidence" com lt para escalar respostas de que o engine não tem certeza — ou defina minConfidence na pergunta para usar a ação de fallback no lugar. Combine os dois para limiares por ação.
  • Use on: "score" para agir entre níveis — frustration ≥ 3.5 — em vez de esperar o nível mais alto vencer.
  • Reserve block para saídas inequívocas (spam, abuso) e deixe a incerteza dar escalate.
  • As políticas fazem parte do schema: uma mudança só vale para os clientes da API quando você publica uma nova versão.

Nesta página