Como usar o Jev para escolher qual LLM responde cada pedido do usuário?

Fala aí, beleza? Mandar TODO pedido do usuário pro modelo mais caro da sua lista é o jeito mais elegante de queimar dinheiro num "oi, tudo bem?"

E o contrário também dói: escolher sempre o modelo baratinho e ver ele derrapar numa tarefa de raciocínio longo

É aí que entra o Jev, o primeiro modelo System One da TypeSafe AI. Ele não gera string. Ele recebe o estado da sua aplicação mais perguntas tipadas e devolve decisões tipadas com probabilidade calibrada

Ou seja: em vez de pedir pra uma LLM escrever "acho que o melhor modelo aqui seria…" e depois parsear isso na unha, você pergunta de forma estruturada e recebe uma escolha, um mapa de probabilidades e um número de confiança

Neste post a gente monta um roteador de modelos do zero: modelagem das opções, chamada da API, leitura da resposta e o que fazer quando a confiança cai. Bora?

O que você precisa antes de começar

A lista é curta, prometo 🙂

• Conta no console da TypeSafe: o Jev deixou de ter lista de espera em 20/09/2026, então qualquer pessoa consegue se cadastrar em console.typesafe.ai e gerar a chave
• A chave no ambiente: os SDKs oficiais leem a variável TYPESAFE_API_KEY
• Um SDK ou um cliente HTTP: dá pra fazer no curl puro também, a API é um POST simples
• A sua lista de modelos: os LLMs que a sua aplicação JÁ sabe chamar hoje, com nome e uma descrição honesta do que cada um faz bem

Esse último item é o que mais gente subestima. O Jev decide entre as opções que VOCÊ der. Se a descrição da opção é vaga, a decisão sai vaga, e a culpa não é do modelo

Instalando o SDK de JavaScript/TypeScript:

npm install @typesafe-ai/sdk

E o de Python (exige Python 3.10 ou superior):

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

A chave vai pro ambiente:

export TYPESAFE_API_KEY="sua-chave-aqui"

Sobre a versão do modelo: o campo model aceita o ID versionado jev-1.13.0 e os aliases jev-latest (padrão do SDK) e jev-preview. Em produção eu fixaria o versionado, porque alias muda debaixo do teu pé e tu descobre pelo gráfico de erro… 😅

Os limites de contexto do jev-1.13 também entram aqui no planejamento: 64k tokens cobrindo o state mais todas as perguntas, e 32k cobrindo o state mais a pergunta mais longa

Curso Recomendado

Curso de Jev: Sistemas Mais Inteligentes, Rápidos e Robustos

Desenvolva sistemas mais inteligentes, rápidos e robustos com Jev

Conhecer curso

Passo a passo: montando o roteador de modelos com o Jev

A ideia do roteador é simples de descrever e chata de acertar: pegar o pedido que chegou, olhar o contexto e apontar qual modelo responde

1. Defina o state do pedido

O state é o que o Jev olha pra decidir. Ele pode ser string, objeto JSON, array ou null, e serve pra passar log de conversa, registros ou o estado atual da aplicação

Se você conhece o payload que já manda pro seu LLM hoje, é a mesma energia: contexto suficiente pra decidir, nada além disso

{
  "ultima_mensagem": "preciso refatorar esse arquivo de 800 linhas e manter os testes passando",
  "idioma": "pt-BR",
  "tem_anexo": false,
  "turnos_na_conversa": 3,
  "plano_do_usuario": "pro"
}

O erro comum deste passo: state inchado. A doc de limitações do jev-1.13 é explícita que a acurácia cai quando o state cresce com conteúdo irrelevante. Jogar a conversa inteira desde 2024 ali dentro não deixa a decisão mais esperta, deixa mais confusa

2. Modele a pergunta choice

A API aceita três tipos de pergunta: choice (escolher uma opção de uma lista), score (posição numa escala definida) e noul (probabilidade de uma afirmação sim/não ser verdadeira)

Roteador de modelo é choice, claro. E uma choice é montada com dois campos: instructions, que diz O QUE decidir, e criteria, que é um mapa de opção pra descrição daquela opção (aceitando null quando a opção dispensa detalhe)

Outro ponto massa: uma choice aceita até 255 opções, e cada opção custa poucos tokens. Por isso a própria doc orienta passar a lista completa em vez de uma lista curta. Não precisa pré-filtrar seus modelos na mão antes de perguntar

{
  "type": "choice",
  "instructions": "Escolha qual modelo deve responder a última mensagem do usuário, considerando complexidade da tarefa e custo",
  "criteria": {
    "modelo_rapido": "Perguntas curtas, saudações, dúvidas factuais diretas e reformulações de texto simples",
    "modelo_raciocinio": "Tarefas com várias etapas: refatoração de código, análise de requisitos, planejamento e depuração",
    "modelo_visao": "Qualquer pedido que dependa de interpretar imagem, print de tela ou PDF anexado",
    "escalar_humano": null
  }
}

O erro comum deste passo: criteria genérico do tipo "modelo bom pra tarefas difíceis". Rubrica boa é a que um estagiário conseguiria aplicar sem te perguntar nada. Escreva a fronteira entre as opções, não o elogio de cada uma

3. Monte a chamada pro endpoint System One

A requisição é um POST para https://api.typesafe.ai/v1/systemone, com autenticação Bearer, Content-Type: application/json e um corpo com state, questions e model

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-1.13.0",
    "state": {
      "ultima_mensagem": "preciso refatorar esse arquivo de 800 linhas",
      "idioma": "pt-BR",
      "tem_anexo": false
    },
    "questions": [
      {
        "type": "choice",
        "instructions": "Escolha qual modelo deve responder a última mensagem do usuário",
        "criteria": {
          "modelo_rapido": "Perguntas curtas e dúvidas factuais diretas",
          "modelo_raciocinio": "Tarefas com várias etapas, código e planejamento",
          "modelo_visao": "Pedidos que dependem de imagem ou PDF anexado"
        }
      }
    ]
  }'

O formato exato do envelope de cada pergunta vale conferir na doc oficial da API antes de subir pra produção, beleza?

O erro comum deste passo: estourar contexto sem perceber. São dois orçamentos diferentes, 64k pro state mais TODAS as perguntas e 32k pro state mais a pergunta mais longa. Quem monta criteria gigante pra 200 opções bate no segundo limite bem antes de imaginar

4. Leia a resposta e use os três campos

A resposta de uma pergunta choice traz a opção escolhida, o mapa probabilities (floats que somam 1) e um confidence pra opção selecionada

{
  "model": "jev-1.13.0",
  "choice": "modelo_raciocinio",
  "probabilities": {
    "modelo_rapido": 0.07,
    "modelo_raciocinio": 0.88,
    "modelo_visao": 0.05
  },
  "confidence": 0.88
}

O campo model da resposta informa qual versão respondeu, o que é ouro puro pro teu log: quando a taxa de acerto do roteador mudar, tu sabe se mudou a tua rubrica ou a versão do modelo

O erro comum deste passo: olhar só o choice e ignorar o resto. As probabilities são o diagnóstico da tua modelagem. Se duas opções vivem empatadas em 0.45 e 0.44, o problema não é a decisão, são as duas opções que tu escreveu parecidas demais

5. Mande as perguntas auxiliares na MESMA requisição

Esse é o detalhe que muda o desenho do sistema: o modelo ingere o state uma vez e avalia todas as perguntas em paralelo. A doc orienta mandar todas as perguntas necessárias numa única requisição, porque acrescentar perguntas quase não muda o tempo de resposta

Então junto da escolha do modelo tu pode mandar uma score de prioridade do ticket e uma noul perguntando se a mensagem é uma tentativa de jailbreak antes do LLM responder, tudo de uma vez

O erro comum deste passo: fazer três chamadas sequenciais pra três decisões sobre o MESMO state. É pagar três vezes pelo mesmo contexto e somar três latências por teimosia 😛

Confidence baixa: como configurar a porta de confiança

O confidence é um número de 0 a 1 calculado a partir da distribuição de probabilidades: distribuição espalhada entre várias opções significa confiança baixa, e probabilidade concentrada numa opção só puxa esse número pra cima

E aqui vai o ponto mais importante do post: a decisão do Jev não é o fim do fluxo, é a entrada dele

A TypeSafe documenta isso como um padrão com nome, o confidence-gated routing: agir quando o modelo está seguro e escalar quando não está, com limiar diferente por ação conforme o custo do erro

1. Separe as ações por custo do erro

Rotear pro modelo rápido e errar custa o quê? Uma resposta fraca e um retry. Aprovar uma operação financeira e errar custa MUITO mais

No exemplo bancário da doc, abaixo de 0.6 de confiança em qualquer ação o sistema manda pra um atendente humano, e pra ação de alto risco (aprovar transferência) exige confiança acima de 0.85

Não copie esses números pro teu roteador. Use como referência de FORMATO: um piso geral, e limiares mais altos pra ações caras de desfazer

2. Defina o fallback de cada faixa

Fallback não pode ser "joga pro modelo caro e reza". Decida antes:

• Confiança alta: roteia direto pro modelo escolhido
• Confiança na zona cinzenta: roteia pro modelo mais capaz da lista (errar pra cima é mais barato que errar pra baixo)
• Confiança abaixo do piso: escala pra humano, ou pede um esclarecimento ao usuário antes de gastar token

3. Logue a distribuição inteira, não só a escolha

Guarde probabilities e confidence de cada decisão junto do desfecho real. Em uma semana tu tem o dado pra calibrar o limiar com número em vez de achismo

O erro comum deste passo: mexer no limiar toda vez que aparece um caso estranho. Limiar se ajusta olhando distribuição acumulada, não olhando o ticket que o chefe reclamou hoje de manhã haha

4. Trate empate como sinal de modelagem ruim

Se muitos pedidos caem abaixo do piso, quase sempre o problema é criteria sobreposto: duas opções que descrevem a mesma coisa com palavras diferentes

Reescreva a fronteira entre elas e o confidence sobe sozinho

Onde esse roteador faz diferença no dia a dia

O uso óbvio é o que a gente montou: separar pergunta trivial de tarefa de raciocínio longo, e parar de pagar preço de reasoning pra responder "qual o horário de atendimento?"

Mas a mesma choice resolve outros use cases:

• Roteamento por capacidade necessária: o pedido veio com print? vai pro modelo de visão. Precisa chamar ferramenta? vai pro modelo que a tua stack já plugou nas tools
• Roteamento por idioma: quando tu tem um modelo que manda melhor em português e outro que brilha em inglês técnico
• Responder ou escalar: a opção "escalar_humano" convive com os modelos na mesma lista, e o criteria dela pode ser null quando a instrução já deixa claro
• Prioridade de ticket: aí já é uma score viajando junto na mesma requisição
• Filtro de entrada: dá pra decidir o modelo e, no mesmo request, moderar o conteúdo enviado pelo usuário antes de qualquer token de geração ser gasto

O argumento de custo é bem direto: o Jev 1.13 cobra US$ 0,042 por 1M de tokens de entrada e US$ 0,00 de saída, com faixa de latência ponta a ponta divulgada de 70 a 500 ms

Sobre aquele número que tá rodando o Twitter, "até 190x mais rápido e 440x mais barato": isso é afirmação do fornecedor sobre os workflows publicados pela própria TypeSafe, não medição independente. Serve como indicação de ordem de grandeza, não como promessa pro teu caso… mede no teu tráfego antes de colocar no slide, beleza? 😀

Plugando o Jev na sua stack: LiteLLM, Vercel AI Gateway, OpenRouter e Claude Code

Se a tua aplicação já passa por um proxy ou gateway, tu provavelmente não precisa abrir exceção de rede pra API nova

1. LiteLLM (pass-through oficial)

O LiteLLM tem pass-through pra API System One. Na prática tu troca a base https://api.typesafe.ai por LITELLM_PROXY_BASE_URL/typesafe e chama:

curl -X POST "$LITELLM_PROXY_BASE_URL/typesafe/v1/systemone" \
  -H "Content-Type: application/json" \
  -d '{ "model": "jev-1.13.0", "state": {}, "questions": [] }'

As envs TYPESAFE_API_KEY e TYPESAFE_API_BASE ficam no ambiente do proxy. E o registro de modelos do LiteLLM já inclui jev-1.13.0, jev-latest e jev-preview, então o rastreio de custo entra no mesmo painel que o resto

2. Vercel AI Gateway

A Vercel mantém uma página oficial pra chamar a API da TypeSafe pelo AI Gateway. Se o teu app já vive lá, o caminho é esse

3. OpenRouter

O Jev está disponível no OpenRouter em beta, servido por um endpoint próprio de decisões

Tome cuidado aqui: não é /chat/completions. É outro endpoint, porque não é um modelo de chat. Quem tentar encaixar no client de chat que já tem vai bater a cabeça sem motivo

4. Agent skill oficial (Claude Code e outros agentes)

Existe agent skill oficial da TypeSafe, mantida no repositório typesafe-ai/skills no GitHub

No Claude Code a instalação é por marketplace de plugin:

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

E a invocação é por comando de plugin:

/typesafe:typesafe-ai

Em outros agentes, a instalação é via npx (local ao projeto por padrão, -g pra global):

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

Vídeo: entendendo os gatilhos que disparam esse tipo de fluxo

Todo roteador começa num gatilho: a mensagem chegou, o webhook disparou, o evento entrou na fila

Pra começar do zero com essa parte de automação, este vídeo do canal mostra como funcionam os triggers do n8n e qual é a função de cada um deles:

Depois que o gatilho dispara, é exatamente ali, antes da chamada de geração, que a decisão do Jev entra no fluxo

Quando o Jev erra: limitações documentadas e como contornar

A TypeSafe publica uma página de model jaggedness do jev-1.13, listando onde o modelo é irregular. Isso é bem honesto da parte deles e economiza teu tempo

A regra mental que resolve quase tudo aí em cima: pré-processa o que é objetivo, pergunta só o que é julgamento

Próximo passo

No fim, um roteador de LLM com o Jev nasce de três decisões suas, não do modelo:

1. Como você modela as opções (instructions claro e criteria com fronteira nítida entre os modelos)
2. Qual o limiar de cada ação (custo do erro define o número, não o gosto)
3. Qual o fallback quando a confiança cai

O caminho mais curto pra começar: cria a chave no console, replica aquela pergunta choice com DOIS ou três modelos só, roda em cima do teu tráfego real e mede quantos pedidos caem abaixo do teu limiar

Se cair pouco, aumenta a lista e vai refinando as rubricas. Se cair muito, o problema tá no criteria, não no limiar 🙂

E vale acompanhar a evolução: o Jev foi anunciado em 15/09/2026 e a versão 1.13 saiu em 18/09/2026, então é coisa MUITO nova e a doc ainda deve mexer bastante nas próximas semanas…

Até o próximo post!