Engines e BYOK
As decisões rodam no Jev, no Laya ou na OpenAI Decisions. Use a chave da Dcision na TypeSafe, traga a sua chave OpenRouter, TypeSafe, Vercel AI Gateway ou OpenAI, ou rode o Laya no seu servidor — e custo, limites, erros.
Engines
A Dcision roda decisões em três engines. Os três são modelos de decisão — devolvem decisões e probabilidades em vez de texto gerado — e os três respondem aos mesmos três tipos de pergunta: choice, score e probability, cada uma com uma distribuição de probabilidade, que a Dcision transforma em respostas tipadas, confiança e níveis ponderados. Jev e Laya falam o mesmo contrato System One; a OpenAI Decisions tem o próprio, e a Dcision o traduz.
| Engine | metrics.engine | O que é | Onde roda |
|---|---|---|---|
| Jev (padrão) | "jev" | O modelo de decisão System One da TypeSafe. | TypeSafe, OpenRouter ou Vercel AI Gateway — na chave da Dcision ou na sua. |
| Laya | "laya" | Modelo de decisão open source (Apache 2.0) da Convai Innovations, com 322M–421M de parâmetros. | Um servidor Laya: o seu, ou o da Dcision quando disponível. Veja Laya. |
| OpenAI Decisions | "openai" | A Decisions API da OpenAI (gpt-6-luna, beta público). | OpenAI, na sua chave OpenAI — ou na da Dcision quando disponível. Veja OpenAI Decisions. |
As respostas informam o engine em metrics.engine e o modelo exato que respondeu em metrics.model.
O decision schema não depende do engine: a Dcision o compila numa representação neutra de engine, e só o adaptador do engine fala com o modelo. O estado, o contexto da decisão e as perguntas — em texto ou JSON estruturado — são enviados nos formatos nativos do engine, e todas as perguntas de uma decisão vão em uma requisição.
Qual engine roda uma decisão
Configurações → Engine define o engine padrão do workspace — Jev até você mudar. Uma decisão pode escolher o seu em Engine e runtime → Engine (settings.engine); sem isso, ela segue o padrão. Cada engine mantém a própria credencial e o próprio modelo, então um workspace pode rodar a maioria das decisões no Jev, uma no Laya e outra na OpenAI Decisions.
Jev: quem faz a chamada ao engine
Escolha em Configurações → Engine (Admins e o Proprietário). A escolha vale na hora para todas as decisões Jev do workspace — Playground e API.
| Opção | O que acontece |
|---|---|
| Chave do engine da Dcision (padrão) | A Dcision chama a TypeSafe (Jev direto) com a própria chave, incluída no seu plano. Escolha o modelo: jev-1.13.0 por padrão. Nada mais a configurar. |
| Minha própria chave de provedor (BYOK) | A Dcision chama o engine com a sua chave, no provedor e no modelo que você escolher. O provedor cobra direto da sua conta. |
Modelos na chave da Dcision
| Modelo | O que é |
|---|---|
jev-1.13.0 | Fixado (padrão, recomendado). Uma versão fixa: as respostas — e a confiança — não mudam sem você saber. |
jev-latest | A última versão estável. Muda quando a TypeSafe lança uma nova versão. |
jev-preview | Builds de prévia, à frente de jev-latest quando existe uma. |
Os aliases mudam quando a TypeSafe lança uma nova versão, então as respostas por trás deles podem mudar sem nenhuma mudança do seu lado. metrics.model e o log de execuções sempre registram a versão exata que respondeu — jev-1.13.0 mesmo quando você selecionou jev-latest.
Fixe uma versão do modelo
Limiares como minConfidence são ajustados para um modelo. Use o jev-1.13.0 fixado para decisões de produção, e passe para uma nova versão no seu próprio ritmo, depois de testar de novo no Playground.
Provedores
Os três expõem o mesmo contrato System One:
| Provedor | Endpoint | Modelos | Onde obter uma chave |
|---|---|---|---|
| OpenRouter | https://openrouter.ai/api/v1/systemone | typesafe/jev-1.13 | openrouter.ai/keys |
| TypeSafe (Jev direto) | https://api.typesafe.ai/v1/systemone | jev-1.13.0 (padrão), jev-latest, jev-preview | docs.typesafe.ai |
| Vercel AI Gateway | https://ai-gateway.vercel.sh/typesafe/v1/systemone | typesafe-ai/jev | vercel.com/docs/ai-gateway |
Laya
O Laya é um modelo System One open source: sem preço por token, e ele roda onde você o roda — os seus dados nunca saem do seu servidor. O servidor dele, laya-serve, expõe o mesmo contrato /v1/systemone do Jev, então a Dcision o chama com as mesmas perguntas.
| Modelo | O que é |
|---|---|
auto | Padrão. O roteador do Laya escolhe o checkpoint pelo idioma da entrada. metrics.model informa o que respondeu, por exemplo laya/multilingual. |
english | Checkpoint em inglês (ModernBERT-large, 421M). Lê até 512 tokens. |
multilingual | Mais de 100 idiomas (mmBERT, 322M), o mais rápido. Lê até 1.024 tokens. |
typed-decisions | Ajustado para observabilidade de agentes e workflows de atendimento ao cliente. Lê até 1.024 tokens. |
Rode o seu servidor Laya
Rode o laya-serve (Python 3.10+) num host que a Dcision alcance por HTTPS público, atrás do seu reverse proxy:
pip install "laya[serve]"
LAYA_API_KEY=<a long random secret> LAYA_PRELOAD=1 laya-serve # listens on :8000O projeto também traz um Dockerfile e arquivos compose para CPU e CUDA. Uma GPU responde em ~35 ms; uma CPU, em algumas centenas de ms por decisão.
Em Configurações → Engine → Servidor Laya, informe a URL do servidor (https://laya.example.com — a Dcision chama /v1/systemone nela) e a LAYA_API_KEY, se você definiu uma. Clique em Salvar servidor e depois em Testar.
Selecione Laya como engine padrão — ou escolha-o nas configurações de uma decisão —, escolha o modelo e clique em Salvar configurações do engine.
Proteja o seu servidor Laya
O laya-serve não tem autenticação a menos que LAYA_API_KEY esteja definida. Defina-a antes de expor o servidor e cole-a em Configurações → Engine. A Dcision só chama endereços https:// públicos — nunca privados, de loopback ou de metadados de nuvem — e não segue redirecionamentos.
Contexto menor que o do Jev. O Laya lê até 512 tokens (english) ou 1.024 (multilingual, typed-decisions) de estado e pergunta; entradas mais longas são truncadas pelo servidor. Para estados longos, prefira multilingual ou fique com o Jev. Teste de novo os limiares (minConfidence, intervalos de políticas) no Playground ao mover uma decisão para o Laya: cada modelo tem o próprio perfil de confiança.
OpenAI Decisions
A OpenAI Decisions é a API da OpenAI para respostas tipadas sobre uma entrada (POST /v1/decisions). Ela responde aos mesmos três tipos de pergunta do Jev, então uma decisão roda nela sem mudanças: a Dcision traduz as perguntas e normaliza as respostas para as mesmas escalas.
| Modelo | O que é |
|---|---|
gpt-6-luna | Padrão e, por enquanto, o único modelo da Decisions API (beta público). metrics.model registra o id exato que respondeu. |
| Dcision | OpenAI Decisions | Observações |
|---|---|---|
probability | predicate | Os critérios yes/no são acrescentados às instruções. result é a probabilidade; a confiança é ` |
choice | choice | As opções viram choices com as descrições, em ordem; a opção reservada other fica por último. A confiança é a da OpenAI. |
score | score | Os níveis viram levels (a rubrica de um nível estruturado é a descrição dele). result é o nível mais provável e scores o nível ponderado, a partir de 1. |
| estado | input | Texto como está; objetos e listas como texto JSON. O context da decisão vai dentro dele, como no Jev. |
Use a sua chave OpenAI
Em Configurações → Engine → Chave OpenAI, cole uma chave de platform.openai.com/api-keys — uma chave de projeto basta — e clique em Salvar chave e depois em Testar.
Selecione OpenAI Decisions como engine padrão — ou escolha-a nas configurações de uma decisão — com Minha chave OpenAI, e clique em Salvar configurações do engine. A Dcision chama https://api.openai.com/v1/decisions; a OpenAI cobra da sua conta.
Recusas. A OpenAI pode se recusar a responder uma pergunta. A execução ainda responde 200: a pergunta recusada não tem entrada em result, as outras perguntas mantêm as suas respostas e a decisão toma a sua ação de fallback com action_reason: { "type": "refusal", "question": … } — não importa o que diga o onEngineError, já que o engine respondeu.
Valem os controles da sua conta OpenAI. Rate limits, Zero Data Retention, HIPAA e residência de dados são os do projeto OpenAI por trás da chave. Teste de novo os limiares (minConfidence, intervalos de políticas) no Playground ao mover uma decisão para a OpenAI: cada modelo tem o próprio perfil de confiança.
GPT-Live
O GPT-Live, a voz em tempo real da OpenAI, pode delegar decisões tipadas à OpenAI Decisions enquanto o usuário fala. A Dcision exporta as perguntas de uma decisão publicada como essa delegação — GET /v1/decisions/{slug}/openai-live — e roda as políticas, os destinos e o log de execuções da decisão sobre as respostas da sessão — POST /v1/decisions/{slug}/openai-live/answers. Essas chamadas são cobradas como execuções, com metrics.engine: "openai" e sem custo de engine: a OpenAI cobra a sessão Live. Veja o guia do GPT-Live.
Compare e rode engines em sombra
Cada engine tem as suas próprias respostas e o seu perfil de confiança. Duas ferramentas mostram como outro engine responde a sua decisão antes de você trocar:
| Ferramenta | Roda | Custo |
|---|---|---|
| Comparar motores no Playground | O estado do editor, no Jev, no Laya e na OpenAI Decisions de uma vez. | Três execuções do Playground. |
Modo sombra — settings.shadow | Uma amostra das execuções reais de produção, também num segundo engine, em segundo plano. | Sem créditos da Dcision. |
Compare os engines no Playground
Comparar motores, ao lado de Rodar decisão, roda o mesmo estado e o mesmo rascunho nos três engines de uma vez. São três execuções do Playground, registradas em Execuções; os destinos nunca são entregues. Uma tabela mostra os engines lado a lado: a resposta de cada pergunta com a sua confiança, a ação, a latência, o custo estimado e, quando um engine falhou, o código de erro — ENGINE_NOT_CONFIGURED para um engine que o workspace não configurou. As linhas em que os engines discordam ficam destacadas.
Modo sombra em produção
Defina settings.shadow — no editor, Engine e runtime → Motor sombra e Amostra da sombra (%) — e faça o deploy. Uma parte das execuções da decisão pela API, por webhook e pelo MCP, 10% por padrão, também roda no motor sombra com exatamente a mesma entrada. Quem chama sempre recebe a resposta do engine principal; a resposta sombra fica guardada na execução e nunca dispara destinos.
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 as cobra na sua conta.
A Visão geral da decisão mostra um card Modo sombra: com que frequência os dois engines concordam, no geral e por pergunta, o número de execuções sombra e de falhas, e a latência mediana do motor sombra — veja Visão geral e calibragem. Quando a concordância é alta nas perguntas que movem as suas políticas, troque o settings.engine e confira de novo limiares como minConfidence.
Traga a sua própria chave
Em Configurações → Engine → Chaves de provedor, cole a chave ao lado do provedor e clique em Salvar chave.
Clique em Testar. A Dcision roda uma pequena decisão de sondagem (o template Detecção de spam numa mensagem de uma linha) com a sua chave e mostra o modelo e a latência, ou o erro do provedor. A sondagem não é registrada como execução, mas o seu provedor pode cobrá-la.
Selecione Minha própria chave de provedor, o provedor e o modelo, e clique em Salvar configurações do engine. As novas execuções passam a usá-los na hora.
Se você selecionar Minha própria chave de provedor sem salvar uma chave para esse provedor, toda execução falha com 424 ENGINE_NOT_CONFIGURED.
Como as chaves são protegidas
- Criptografadas em repouso com AES-256-GCM; a API nunca as devolve — só os 4 últimos caracteres são exibidos.
- Nunca gravadas em logs e nunca enviadas a lugar nenhum além do endpoint do provedor.
- Só Admins e o Proprietário podem adicioná-las, substituí-las, testá-las ou removê-las; todos os demais no workspace veem quais provedores têm chave, com os 4 últimos caracteres.
- Remover uma chave a exclui. Salve uma chave nova para trocá-la.
Chaves para destinos LLM
As chaves OpenRouter e Vercel AI Gateway salvas aqui também alimentam os destinos LLM — as respostas que uma decisão pode gerar para uma rota. Elas são usadas para essas respostas mesmo quando o engine roda na chave da Dcision, e o provedor cobra os tokens delas da sua conta. A chave do engine da Dcision nunca roda destinos LLM.
Limites do engine
- Orçamento de tokens. O Jev lê o estado uma vez e avalia cada pergunta contra ele: cerca de 32.000 tokens para o estado mais a pergunta mais longa e 64.000 para o estado mais todas as perguntas. A Dcision confere os dois antes da chamada e responde
422 INVALID_STATEquando um estado não cabe — veja Limites. - Vazão. A TypeSafe limita cada conta em requisições e tokens por segundo. Na chave da Dcision, o limite é compartilhado por todos os workspaces, então a Dcision suaviza os picos: uma chamada espera por uma vaga livre dentro do prazo dela em vez de falhar na hora. Com a sua própria chave, valem os limites da sua conta no provedor — na OpenAI, os do seu projeto OpenAI.
- Imagens, áudio e documentos. Os três engines leem texto e JSON. A Dcision converte documentos em texto, transcreve áudio e — como Jev e Laya não veem imagens — descreve as imagens em texto para eles; a OpenAI Decisions recebe as imagens como imagens. Veja Entradas.
Custo
No Laya, o custo do engine é o servidor que você roda: a Dcision estima estimated_cost_usd: 0 para chamadas ao Laya. Uma execução bem-sucedida pela API ainda conta como uma decisão cobrável.
Na OpenAI Decisions, o preço é US$ 0,10 por 1M de tokens de entrada (sem cobrança de saída ou cache): uma decisão de 375 tokens de entrada é estimada em 0.0000375.
No Jev, cada resposta inclui metrics.input_tokens, metrics.output_tokens e metrics.estimated_cost_usd: os tokens de entrada da chamada vezes o preço do modelo. O Jev custa US$ 0,042 por 1M de tokens de entrada e não cobra tokens de saída — eles são informados só para observabilidade —, então uma decisão de 375 tokens de entrada é estimada em 0.00001575. É uma estimativa do custo do engine — útil para comparar decisões —, não a sua fatura da Dcision.
Todas as perguntas de uma decisão compartilham uma chamada, então adicionar uma pergunta acrescenta os tokens dela à chamada, não outra requisição.
Com a sua própria chave, o provedor cobra a chamada ao engine. A chamada ainda conta como uma decisão cobrável no seu plano da Dcision quando dá certo pela API.
Erros de engine
| Código | Status | Causa |
|---|---|---|
ENGINE_NOT_CONFIGURED | 424 | Nenhuma chave salva para o provedor selecionado, nenhum servidor Laya para uma decisão Laya, nenhuma chave OpenAI para uma decisão OpenAI, ou a chave do engine da Dcision está indisponível. |
ENGINE_AUTH_FAILED | 502 | O provedor rejeitou a chave (401/403) ou a conta não tem créditos (402, 429 insufficient_quota da OpenAI). Confira em Configurações → Engine. |
ENGINE_RATE_LIMITED | 503 | O provedor está sobrecarregado ou limitou a taxa (429/503/529), ou a chave compartilhada da Dcision não teve vaga livre antes do prazo. |
ENGINE_UNAVAILABLE | 503 | O provedor falhou (5xx) ou não pôde ser alcançado. |
ENGINE_TIMEOUT | 504 | Nenhuma resposta dentro do timeoutMs da decisão. |
ENGINE_INVALID_REQUEST | 502 | O provedor rejeitou a requisição; a mensagem inclui o motivo. Também uma URL de servidor Laya que resolve para um endereço privado ou reservado. |
ENGINE_ERROR | 502 | O engine respondeu fora do contrato (por exemplo, uma opção desconhecida). |
Dentro do timeoutMs da decisão, a Dcision faz até 2 retries em erros de rede, respostas 429/503/529 e outros 5xx, respeitando o Retry-After do provedor — veja timeoutMs. As execuções que falham são registradas com status Erro e não são cobradas. Com onEngineError: "fallback", todo erro desta tabela, exceto ENGINE_NOT_CONFIGURED, vira um 200 com a ação de fallback da decisão. Veja Erros.
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.
Playground
Teste rascunhos — inclusive edições não salvas — com payloads reais, leia a confiança e as distribuições, pré-visualize destinos, compare execuções e engines e repita entradas de execuções anteriores.