Como adotar o Jev em um projeto que já existe sem reescrever tudo?

Trocar a peça que toma decisão dentro de um sistema em produção é o tipo de coisa que dá frio na barriga

Ninguém quer virar a chave num domingo e descobrir na segunda que a triagem parou de funcionar

O Jev é o primeiro modelo da classe que a TypeSafe AI chama de System One: você manda um estado e perguntas tipadas, ele devolve decisões estruturadas que o software consome direto, sem etapa de parsing nem de validação

E é justamente por ser tipado que dá pra encaixar ele numa etapa só, rodando em paralelo com o que já existe, sem tocar no resto do pipeline

A ideia deste post é essa: um plano de adoção incremental, etapa por etapa, com sombra antes de promoção

O que você precisa antes de começar

Primeiro o aviso chato, mas importante: o Jev foi lançado em early access e o acesso continua por waitlist, com devs sendo liberados aos poucos

Ou seja, não é disponibilidade geral ainda

Então o item zero da lista é ter o acesso liberado mesmo, senão o plano todo fica no papel

Com o acesso na mão, o resto é bem "next, next e finish":

• SDK Python, que pede Python 3.10 ou superior
• ou o SDK JavaScript/TypeScript, se o seu backend for Node
• a variável de ambiente TYPESAFE_API_KEY, que o cliente do SDK lê por padrão
• logs da decisão atual e um lugar pra gravar o resultado das duas decisões lado a lado

Instalação do SDK Python:

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

pip install typesafe-sdk
# ou, se tu usa uv
uv add typesafe-sdk

Instalação do SDK JS/TS:

npm install @typesafe-ai/sdk

Com a TYPESAFE_API_KEY configurada, o cliente já sobe apontando pro alias jev-latest por padrão

E a agent skill oficial, vale a pena?

Vale, se tu escreve código com um agente do lado

A TypeSafe publica uma agent skill oficial que dá ao agente o contexto da API: os três tipos de pergunta, os padrões arquiteturais e boas práticas pra estruturar avaliações

No Claude Code, a instalação é assim:

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

Em outros agentes de código:

npx skills add typesafe-ai/skills --skill typesafe-ai

E aí tu seleciona o agente na listinha

Se tu já tem costume de usar agente pra mexer em código legado sem quebrar tudo, esse contexto extra ajuda bastante na hora de desenhar as perguntas tipadas

Passo a passo do plano de adoção incremental

A regra que guia tudo aqui é simples: o Jev entra observando, não mandando

1. Escolha UMA etapa do pipeline

Nada de "vou colocar IA no sistema"

Escolhe uma decisão binária ou uma classificação que JÁ existe hoje e que tem resultado observável depois (aprovou e deu certo? roteou pro time certo? o ticket voltou?)

Se tu não consegue dizer se a decisão foi boa ou ruim depois, não dá pra comparar nada

O erro comum deste passo: escolher a etapa mais complexa do sistema porque é a que mais dói. Começa pela que tem sinal de resultado mais limpo, não pela que dói mais

2. Traduza essa etapa para uma das três primitivas tipadas

Tudo que se pergunta ao Jev é uma de três coisas:

A escolha muda o formato da resposta, então ela muda o código que consome

Triagem sim/não é Noul, roteamento entre filas é Choice, prioridade em faixas é Score

O erro comum deste passo: tentar espremer uma classificação de 6 categorias dentro de um Noul e depois encadear vários Nouls na mão. Se é escolha entre opções nomeadas, é Choice

3. Monte o estado dentro do orçamento de contexto

A janela é de 64k tokens por requisição, com 32k disponíveis pro estado mais a pergunta mais longa

Então o estado não é "joga o registro inteiro do banco lá dentro"

É um recorte: só os campos que um humano olharia pra tomar aquela decisão específica

O erro comum deste payment: serializar o objeto completo "por garantia". Contexto irrelevante não é neutro, ele atrapalha (a própria TypeSafe lista "estado grande com detalhe irrelevante" como ponto fraco do modelo)

4. Instale o SDK e fixe a versão do modelo

O alias jev-latest é o padrão do SDK e é estável, mas em produção vale saber exatamente com quem tu tá falando

A versão atual é jev-1.13.0

Existe também o jev-preview, que avança quando tem build de preview, e IDs versionados são aceitos na API

Pra fase de comparação, fixar o ID versionado é mais honesto: tu compara a decisão atual contra UM modelo, não contra um alvo que mudou no meio do caminho

O erro comum deste passo: rodar semanas de sombra no alias e depois não saber qual build gerou cada linha do log

5. Rode em sombra

Agora a parte boa: chama o Jev com o mesmo estado da decisão real, mas a saída dele NÃO afeta o fluxo

Ela só vai pro log

A latência publicada pela TypeSafe é de 70 a 500 ms ponta a ponta, o que faz a chamada caber bem como tarefa lateral, fora do caminho crítico da requisição

# pseudo: a decisão real continua mandando
decisao_atual = pipeline.decidir(pedido)

# o Jev roda em paralelo, sem poder de veto
try:
    estado = montar_estado(pedido)  # recorte enxuto, dentro do orçamento
    resposta_jev = perguntar_ao_jev(estado)  # veja o quickstart oficial pra assinatura
    log_sombra.gravar(
        id=pedido.id,
        decisao_atual=decisao_atual,
        decisao_jev=resposta_jev,
        modelo="jev-1.13.0",
    )
except Exception as e:
    log_sombra.gravar_falha(pedido.id, str(e))

return decisao_atual

Repara no try/except abraçando tudo

Modo sombra que derruba a requisição quando a API pisca deixa de ser sombra e vira dependência, beleza? 🙂

O erro comum deste passo: deixar a chamada do Jev dentro do fluxo síncrono sem proteção e transformar um experimento em incidente

6. Registre as duas decisões lado a lado, com a probabilidade

Não grava só "bateu" ou "não bateu"

Grava a decisão atual, a decisão do Jev e a probabilidade devolvida

É essa probabilidade que vai virar o limiar depois

O Jev é treinado com um método chamado RLCD (Reinforcement Learning for Calibrated Decisions), que otimiza probabilidades contra resultados, então a probabilidade é informação de verdade, não enfeite

O erro comum deste passo: comparar só o acerto agregado. O interessante mora nas divergências, e tu precisa conseguir abrir caso a caso

7. Calibre o limiar de confiança nos SEUS dados

Aqui não tem número mágico pra copiar de post nenhum

A documentação da TypeSafe é explícita: limiares de confiança são específicos de cada caso de uso e devem ser testados nos dados do próprio cliente

Então tu pega o log da sombra e pergunta: acima de que probabilidade a decisão do Jev bateu com o resultado observado de forma consistente?

Esse vira o teu limiar. O que fica abaixo dele continua indo pro caminho antigo

O erro comum deste passo: pegar um valor genérico da internet e chamar de calibração

8. Defina a regra de promoção e o fallback

Antes de ligar qualquer coisa, escreve em uma frase: "o Jev assume quando X"

E escreve também o caminho de volta: acima do limiar decide, abaixo do limiar cai pro processo antigo, erro de API cai pro processo antigo

O fallback tem que ser o código que já roda hoje, não um plano B novo que ninguém testou

O erro comum deste passo: promover por empolgação, sem regra escrita. Aí não dá pra reverter com critério, só na base do achismo

9. Ligue para uma fatia do tráfego

Um percentual pequeno primeiro, com o log lado a lado continuando ativo

Essa lógica de validar em paralelo antes de entregar o volante é a mesma que vale pra testar um modelo novo no seu projeto antes de adotar de vez

Só depois que a fatia se comporta é que a etapa inteira passa pro Jev

O erro comum deste passo: desligar o log de comparação no dia da promoção. Mantém ele rodando mais um tempo, é o teu sensor

Que etapas do seu sistema são boas candidatas para começar

As candidatas naturais são as decisões chatas e repetitivas que hoje vivem em if aninhado ou na cabeça de alguém:

• triagem e roteamento: esse pedido vai pra fila de análise manual ou segue direto? (Noul ou Choice)
• checagem de elegibilidade: o cliente atende aos critérios descritos? (Noul)
• classificação de ticket: qual categoria dentre as N que tu já usa hoje? (Choice)
• priorização por nível: urgência em faixas, usando um Score com 2 a 10 descrições de nível ordenadas

Repara no padrão: todas têm um conjunto FECHADO de saídas possíveis

E isso conversa direto com uma característica do modelo: o Jev só pode responder com uma opção que você forneceu, então não existe etapa de validar uma resposta inventada

E onde NÃO começar?

A TypeSafe publica uma página de jaggedness específica da versão 1.13, listando onde o modelo falha

É leitura obrigatória antes de escolher a etapa, e olha que legal: um fornecedor documentando os pontos fracos do próprio modelo não é exatamente comum 😀

Os pontos listados lá:

• leitura literal da pergunta
• contagem e números
• comparação de datas (datas são lidas como texto)
• indireção
• estado grande com detalhe irrelevante
• conteúdo adversarial no estado
• instruções contraditórias
• invariantes estruturais entre respostas
• ausência total de geração de texto

Traduzindo pro teu roadmap: não começa por aquela regra que conta ocorrências, nem por aquela que decide com base em "faz mais de 90 dias que"

Essas duas caem em cima de contagem e de comparação de datas, os dois itens da lista

Começa pelo julgamento qualitativo com opções fechadas, que é onde o modelo joga em casa

Se tu ainda tá na dúvida entre mexer num sistema grande que já existe ou montar algo separado pra estudar a ferramenta antes, este vídeo do canal trata justamente da escolha entre pequenos projetos e um projeto grande:

Problemas comuns na fase de comparação (e como prevenir)

A fase de sombra é onde aparecem as surpresas. Se liga nas quatro mais frequentes:

Divergência alta demais entre o Jev e o processo atual

Sintoma: as duas decisões discordam num volume que não faz sentido nenhum, e nas divergências tu olha e pensa "mas era óbvio"

Causa provável: pergunta ambígua. A leitura literal da pergunta está na lista oficial de falhas da 1.13, então o modelo responde exatamente o que tu escreveu, não o que tu quis dizer

Prevenção: reescreve a afirmação do Noul ou os nomes das opções do Choice de forma que uma pessoa de fora do time leia e chegue na mesma interpretação. Sem implícito, sem jargão interno

Volume de chamadas explodindo

Sintoma: uma decisão virou seis perguntas, e aí cada item do pipeline dispara seis requisições

Causa: perguntas sobre o MESMO estado sendo mandadas uma por uma

Prevenção: existe um cookbook oficial de perguntas paralelas exatamente pra isso, agrupando várias perguntas sobre um mesmo estado em uma única chamada em vez de N chamadas separadas

Como a cobrança é por token de entrada, mandar o mesmo estado seis vezes é pagar seis vezes pelo mesmo contexto

O estado estourando o orçamento de contexto

Sintoma: requisições falhando ou qualidade caindo conforme o registro cresce

Causa: contexto irrelevante grudado no estado (histórico completo, campos de auditoria, metadados que ninguém lê)

Prevenção: lembra do teto, 64k por requisição com 32k pro estado mais a pergunta mais longa, e trata o recorte do estado como parte do design, não como detalhe de implementação

Tome cuidado com um clássico: aquele campo de "observações" que alguém usa como diário e sozinho come metade do orçamento

Esperar texto livre de volta

Sintoma: o time tenta encaixar o Jev onde precisava de uma explicação escrita pro usuário e não sai nada

Causa: expectativa errada mesmo. A saída fica restrita às opções tipadas que tu forneceu, e ausência total de geração de texto está lá na página de jaggedness

Prevenção: separa as responsabilidades no desenho. Decisão tipada é com o Jev, redação de texto é com outra peça do sistema

Próximo passo

O ciclo inteiro cabe em três palavras: sombra, comparação, promoção por fatia

Nenhuma dessas etapas pede reescrita, e nenhuma delas tira o processo atual do ar num único movimento

E tem um detalhe que deixa a fase paralela bem confortável de manter no ar: o preço publicado é de US$ 0,042 por 1 milhão de tokens de entrada, com tokens de saída não cobrados

Rodar em sombra significa exatamente pagar entrada sem interferir em nada, então dá pra deixar comparando por bastante tempo antes de decidir qualquer coisa

Mas tudo isso depende do acesso, que ainda é por waitlist no early access

Então o próximo passo concreto é duplo: entra na waitlist e, enquanto o acesso não sai, abre o teu pipeline e marca a primeira etapa candidata

Decisão com saídas fechadas, resultado observável, sem contagem e sem comparação de data

Quando a chave virar, tu já tem o desenho pronto e é só ligar a sombra 🙂

até o próximo post!