Catálogo de decisões do Jev: como documentar cada chamada quando o time cresce

Fala aí, beleza? Decisão automatizada que só uma pessoa do time entende não é automação, é dependência…

O Jev é o primeiro modelo público da TypeSafe AI, lançado em 15 de setembro de 2026. Ele não escreve prosa: recebe um estado e devolve valor tipado, com o mapa de probabilities e uma estimativa de confidence entre 0 e 1

Ou seja: cada chamada que você faz pro Jev é uma regra de negócio rodando em produção

Enquanto o time é você e mais ninguém, tudo bem, a regra mora na sua cabeça. Quando entra a terceira pessoa, alguém vai olhar um ticket roteado errado e perguntar "por que isso foi parar aqui?" e a resposta honesta vai ser "sei lá"

O catálogo de decisões do Jev existe pra matar esse "sei lá"

O que você precisa antes de montar o catálogo

Nada de exótico, mas tem quatro coisas que precisam existir ANTES de você abrir o primeiro arquivo:

1. Acesso ao Jev. Hoje o modelo está aberto a todos, sem lista de espera, com cadastro em console.typesafe.ai e US$ 5 de crédito inicial (cerca de 120 milhões de tokens de entrada). O preço na TypeSafe é de US$ 0,042 por milhão de tokens de entrada, com tokens de saída gratuitos

Se você prefere ir por gateway, ele também está no AI Gateway da Vercel (gratuito por lá até 25 de setembro de 2026, depois volta ao preço da TypeSafe), no Cloudflare Workers AI, no OpenRouter e no AI Gateway da Netlify

Pré-inscrição Curso Jev

Domine o Jev e coloque decisões de IA dentro do seu sistema

Você vai aprender a usar o Jev, o System One Model da TypeSafe AI, pra automatizar decisões com resposta tipada e confiança medida, sem depender de chat nem de alguém revisando cada passo. Entre na lista de espera para garantir a condição de lançamento!

Quero minha vaga

2. Uma chave de API. A chamada é um POST para https://api.typesafe.ai/v1/systemone, com header Authorization: Bearer <API_KEY> e Content-Type: application/json. A TypeSafe anuncia tempo de resposta na faixa de 70 a 500 ms, então isso cabe dentro de request de usuário, e é justamente por caber que vai virar regra escondida se ninguém documentar 🙂

3. Um lugar versionado pro catálogo. Repo do produto, ao lado do código que faz a chamada. Wiki não serve, e eu vou insistir nisso lá na conclusão

4. Exemplos rotulados do seu domínio. Uns 30, 50, o que você conseguir juntar com rótulo humano. A documentação da TypeSafe trata threshold de confiança como coisa específica de cada caso de uso, que deve ser medido e testado em exemplos rotulados do próprio usuário. Sem esse conjunto, o campo threshold da sua ficha vai nascer chutado

Como documentar cada chamada ao Jev, passo a passo

Um aviso antes: o formato de ficha que eu mostro aqui é convenção do seu time, não recurso oficial da TypeSafe. O modelo devolve decisão, o catálogo é o que VOCÊ mantém ao redor dele

Sugestão de layout no repo:

decisions/
  README.md
  ticket-routing.yml
  incident-severity.yml
  tool-call-guard.yml

1. Dê um ID e um dono a cada decisão

Toda decisão delegada ao Jev vira um arquivo com identificador estável e uma pessoa responsável. Pessoa, não caixa de entrada

id: ticket-routing
titulo: Para qual fila o ticket vai
dono: @matheus (líder de suporte)
substituto: @ana
criado_em: 2026-09-18
status: producao

O erro comum deste passo: botar "time de suporte" no campo dono. Quando a decisão começa a errar, ninguém do time sente que o problema é dele, e o arquivo apodrece

2. Escolha e registre a primitiva

O Jev tem três primitivas de pergunta, e a escolha muda tudo o que vem depois:

Na ficha:

primitiva: Choice
pergunta_key: fila
opcoes:
  - financeiro
  - suporte_tecnico
  - comercial
  - abuso

O erro comum deste passo: usar Choice com oito opções que na verdade são uma escala (baixo, médio, alto, crítico e por aí vai). Se as opções têm ordem entre elas, isso é Score, que aceita de 2 a 10 níveis e deixa você descrever cada nível separadamente

3. Documente o state: o que entra e, principalmente, o que NÃO entra

O state é a informação que o modelo vai avaliar. A ficha precisa listar os campos permitidos e, do lado, os campos proibidos

state:
  inclui:
    - assunto_do_ticket
    - primeira_mensagem (texto do cliente, truncado)
    - plano_da_conta
  nao_inclui:
    - histórico completo da thread
    - notas internas do time
    - qualquer campo editável por terceiros

O erro comum deste passo: despejar o payload inteiro do usuário dentro do state "porque contexto é bom". Contexto demais é superfície de ataque: conteúdo dentro do state pode direcionar a resposta do Jev, seja por instrução injetada, enquadramento enganoso ou texto que argumenta pela própria classificação

4. Escreva instructions e criteria com situações concretas

O corpo da requisição combina o state, o campo model e um mapa questions com uma ou mais perguntas tipadas. Cada pergunta tem instructions e, nos tipos Choice e Score, criteria

{
  "model": "jev-1.13.0",
  "state": {
    "assunto": "Cobrança duplicada no cartão",
    "mensagem": "Fui cobrado duas vezes esse mês",
    "plano": "pro"
  },
  "questions": {
    "fila": {
      "instructions": "Escolha a fila que resolve o pedido do cliente sem repasse interno",
      "criteria": {
        "financeiro": "Cobrança, nota fiscal, reembolso, cartão recusado, cobrança duplicada",
        "suporte_tecnico": "Erro na aplicação, integração quebrada, login que não funciona",
        "comercial": "Upgrade de plano, pedido de proposta, dúvida sobre limites do plano",
        "abuso": "Denúncia de conteúdo, spam enviado pela plataforma, conta comprometida"
      }
    }
  }
}

Instructions e cada nível de criteria podem ser string, objeto ou array, e a documentação recomenda descrever situações concretas em vez de graus vagos

O erro comum deste passo: escrever criteria tipo "impacto alto", "impacto médio", "impacto baixo". Isso não descreve situação nenhuma, e o que você acha que é alto não é o que a pessoa ao seu lado acha 😀

5. Congele a ordem das opções

Esse aqui pega muita gente de surpresa. A documentação do Pydantic sobre o Jev afirma que a ordem das opções de um Literal ou dos membros de um Enum faz parte do que o Jev vê, e que reordenar pode mudar a resposta

Então a ordem vira item de catálogo, com aviso explícito:

ordem_das_opcoes: congelada
# reordenar o Literal/Enum muda o que o modelo vê
# mudança de ordem = nova validação nos exemplos rotulados

O erro comum deste passo: alguém passa um linter, ordena o Enum em ordem alfabética "pra ficar organizado" e a taxa de acerto muda sem uma linha de lógica ter sido tocada. Tome cuidado!

6. Meça o threshold de confiança e anote onde ele foi medido

A resposta de um Choice traz o tipo, a opção de maior probabilidade, o mapa probabilities com todas as opções (floats que somam 1) e um confidence entre 0 e 1 derivado dessas probabilidades

O threshold é o corte que separa "o sistema age sozinho" de "isso vai pra humano". E ele não é número universal: precisa ser medido e testado nos seus exemplos rotulados antes de você confiar nele

threshold_confidence: <valor medido>
medido_em: decisions/evals/ticket-routing-2026-09.csv
quantidade_de_exemplos: <n>
medido_por: @matheus
medido_em_data: 2026-09-19

O erro comum deste passo: copiar o threshold do post de outra empresa, de outro caso de uso, e tratar como verdade. Se o número não foi medido nos seus dados, ele é decoração

7. Mapeie o que o sistema faz com CADA resultado

A ficha só está completa quando alguém que nunca viu o código consegue dizer o que acontece depois da resposta. Inclusive no caminho chato, o de baixa confiança

acoes:
  acima_do_threshold: roteia automático e loga a decisão
  abaixo_do_threshold: manda pra triagem humana com as 3 opções mais prováveis
  opcao_abuso: sempre humano, independente do confidence
  erro_ou_timeout: fila padrão de suporte + alerta no canal do time

Repare que a última linha não é sobre o Jev, é sobre a sua aplicação. Vale ter combinado antes o que fazer quando a decisão não chega, porque esse caminho sempre existe e quase nunca está escrito

O erro comum deste passo: documentar só o caminho feliz. Aí no primeiro resultado de baixa confiança o sistema faz o que o else de alguém fez seis meses atrás

8. Fixe o ID versionado do modelo e registre o que voltou

O alias jev-latest resolve hoje para jev-1.13.0 e se move quando sai uma nova release, o que pode mudar suas respostas sem nenhuma mudança do seu lado. A documentação orienta fixar o ID da versão quando os thresholds de confiança foram calibrados contra uma versão específica

A resposta traz o campo model com o ID versionado do modelo que respondeu e usage.input_tokens, os tokens de entrada consumidos. Logue os dois em toda chamada:

• model: qual versão produziu aquele resultado
• usage.input_tokens: custo e tamanho do state que você realmente mandou
• confidence e o probabilities completo: dá pra reprocessar depois com outro corte

model_pinado: jev-1.13.0
log_obrigatorio: [model, confidence, probabilities, usage.input_tokens]

Com esses campos no log, monitorar as decisões em produção deixa de ser adivinhação e vira consulta

O erro comum deste passo: rodar jev-latest em produção com threshold calibrado. Funciona liso até a release que muda a distribuição das probabilidades

9. Defina cadência de revisão e quem aprova mudança

Último campo da ficha, e o que mantém o catálogo vivo:

revisao: trimestral
aprovacao_de_mudanca: dono + 1 revisor do time de plataforma
mudancas_que_exigem_revalidacao:
  - alterar criteria
  - adicionar ou remover opção
  - mudar a ordem das opções
  - trocar a versão do modelo
  - mudar o threshold

O erro comum deste passo: tratar mudança de criteria como "ajuste de texto". Mexer no criteria é mexer na regra de negócio, e merece o mesmo PR review que qualquer código

Problemas que aparecem quando o catálogo não existe (e como prevenir)

"A resposta mudou e ninguém mexeu no código"

Causa: o alias jev-latest se move quando sai uma nova release, então o modelo que responde hoje não é obrigatoriamente o mesmo de ontem

Prevenção: pinar o ID versionado no campo model da requisição e registrar o model que volta na resposta. Se o log tem a versão, a investigação leva minutos em vez de uma tarde inteira

"Copiei o threshold e a coisa falha em produção"

Causa: threshold de confiança é específico de cada caso de uso

Prevenção: medir nos seus exemplos rotulados e deixar na ficha o caminho do arquivo de avaliação, quem mediu e quando. Assim a próxima pessoa revalida em vez de herdar um número órfão

"Alguém escreveu um texto que mudou o veredito"

Causa: conteúdo dentro do state pode direcionar a resposta, e a adoção do Jev em infraestrutura de agentes está mais rápida do que as práticas de auditar, restringir e revisar essas decisões. A Vercel afirmou que ele foi o modelo de adoção mais rápida na história do AI Gateway, com uso por quase 13% dos times pagos nas primeiras 24 horas, então dá pra imaginar quanta chamada existe por aí sem ficha nenhuma

Prevenção: limitar o que o Jev enxerga, campo a campo, como faz o middleware da LangChain que usa o Jev pra decidir se as chamadas de ferramenta de um agente devem rodar. E manter checagem determinística ao lado do guard: a documentação do Pydantic é direta ao dizer que um guard construído sobre o Jev fica AO LADO das checagens determinísticas, não no lugar delas

"O refactor organizou o Enum e a métrica caiu"

Causa: a ordem das opções faz parte do que o modelo vê

Prevenção: campo ordem_das_opcoes: congelada na ficha, e a mudança de ordem entrando na lista do passo 9, aquela que exige revalidação

Quais decisões entram no catálogo (exemplos por tipo de pergunta)

Regra prática: se o resultado do Jev dispara uma ação sem humano no meio, tem que ter ficha. Se é só métrica interna, pode esperar

Choice: roteamento e escolha de ferramenta

Roteamento de ticket pra fila, escolha de qual ferramenta o agente deve usar, classificação de motivo de cancelamento. Choice aceita até 255 opções, o que é MUITO mais do que qualquer roteamento saudável precisa, então não use isso como desculpa pra criar 40 filas

• Dono: quem responde pelo SLA da fila, normalmente o líder da área de destino
• Acima do threshold: roteia automático
• Abaixo do threshold: triagem humana recebendo as opções mais prováveis do mapa probabilities, o que já acelera a vida de quem decide

Score: severidade e prioridade

Severidade de incidente, prioridade de bug, risco de uma solicitação. Score aceita de 2 a 10 níveis e cada nível é descrito em criteria, que é exatamente onde o seu time escreve o que significa "cliente parado" em vez de "impacto alto"

• Dono: SRE ou o time de plataforma
• Nível mais grave, com confiança acima do corte: abre incidente e chama on-call
• Baixa confiança: cria o incidente no nível padrão e marca pra revisão humana, porque aqui errar pra menos é pior que errar pra mais

Noul: guardrail de passa ou não passa

Noul devolve probabilidade de verdadeiro/falso, então é o formato natural pra pergunta binária: essa tool call pode rodar? esse conteúdo viola a política?

• Dono: time de plataforma ou segurança
• Verdadeiro com confiança alta: deixa passar
• Qualquer outra coisa: bloqueia ou escala, e as checagens determinísticas continuam rodando de qualquer jeito

Repare no padrão: em guardrail, o caminho de baixa confiança é o caminho conservador. Em roteamento, é o caminho humano. Isso muda por decisão e é exatamente o tipo de coisa que ninguém lembra de escrever

Vídeo: tome suas próprias decisões como dev

Pra começar do zero com o assunto decisão, esse vídeo do canal serve de introdução, falando de critério e de como escolher caminho sendo dev

Conclusão

Catálogo não é wiki bonita que ninguém abre, é arquivo no repo que quebra PR quando alguém muda criteria sem revalidar

A ficha completa tem nove campos que você já viu: ID, dono, primitiva, state (com o que entra e o que fica de fora), instructions e criteria, ordem congelada das opções, threshold medido, ações por resultado e versão pinada do modelo

Próximo passo, e faça hoje: pega a decisão mais crítica que já está rodando em produção, preenche a ficha inteira e confere duas coisas…

O threshold foi medido nos SEUS dados rotulados?

A versão do modelo está fixada?

Se a resposta de alguma das duas for "acho que sim", você acabou de achar o primeiro item do backlog 😀

Até o próximo post!