Como escrever uma boa pergunta tipada para o Jev?

Fala aí, beleza? No Jev quem decide a qualidade da resposta é o jeito que você escreve a pergunta, não um prompt mágico enfiado no começo do texto

E isso muda o hábito: não tem "aja como um especialista", não tem fórmula secreta, tem enunciado claro e recorte bem descrito

Relembrando o terreno: Jev é o modelo System One da TypeSafe AI, onde você envia um estado e um mapa de perguntas tipadas e recebe respostas estruturadas, uma por pergunta

É modelo de decisão tipada, não de texto conversacional

Ou seja: a engenharia toda mora no desenho da pergunta e das opções. Bora ver como escrever isso direito?

O que você precisa saber antes de escrever a pergunta

Anatomia mínima, que vale pros três tipos: todos compartilham os campos type e instructions, e cada tipo acrescenta o seu próprio criteria

O instructions é a pergunta que se faz sobre o estado, é ali que fica a lógica de avaliação

O state é o conteúdo a ser avaliado: pode ser uma string simples de texto ou dados estruturados, tipo log de chat e estado de aplicação

E o questions é um mapa de chaves escolhidas por VOCÊ: as respostas voltam sob as mesmas chaves que você definiu

Os três tipos, e quando cada um cabe:

Dá pra misturar Choice, Score e Noul numa mesma requisição, sobre o mesmo estado

As requisições vão para o endpoint de avaliação da TypeSafe, com autorização Bearer e content-type JSON:

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

O campo model indica qual modelo atende a requisição, e jev-latest é o modelo principal da TypeSafe

Um aviso sobre acesso, pra tu não te frustrar: a TypeSafe liberou cadastro pra todos sem lista de espera em 20/09/2026, com US$ 5 de crédito inicial, e pausou novos cadastros em 22/09/2026 por causa da demanda

Contas criadas antes da pausa seguem funcionando, e a empresa diz que quer reabrir assim que possível

Passo a passo para escrever uma boa pergunta tipada

Vou usar como base o exemplo oficial da referência da API, aquele da pergunta department, e ir apertando os parafusos em cima dele

1. Escolha o tipo pela forma da resposta, não pelo assunto

Pergunte a si mesmo: a resposta é sim ou não? Então é Noul. É posição num espectro que eu consigo descrever em degraus? Então é Score. É uma opção dentro de um conjunto? Choice

O erro comum deste passo: transformar julgamento binário em Choice de duas opções, ou transformar espectro em Choice de "baixo, médio, alto" quando Score existe justamente pra isso

2. Escreva o enunciado completo em instructions, mesmo com a chave parecendo óbvia

A documentação é explícita: não confie no nome da chave como enunciado. department não é pergunta, é etiqueta

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

O erro comum deste passo: deixar instructions vazio ou telegráfico apostando que a chave explica o resto

3. Liste TODAS as opções do Choice, cada uma com descrição curta em criteria

No Choice, criteria é um mapa de opção para descrição de rubrica, e o formato aceita null quando a opção não precisa de detalhe extra

Só que aceitar não é recomendar: a documentação avisa que rótulo sem descrição custa confiança, e confiança é justamente o número que tu vai usar pra decidir se automatiza ou não

Ou seja, o null é a exceção, não o padrão

O erro comum deste passo: cair no null por preguiça e deixar os recortes sem nada que os diferencie

4. Faça os recortes mutuamente exclusivos

Os rótulos de um Choice são mutuamente exclusivos: exatamente um se aplica

Se duas opções podem caber na mesma entrada, tu não tem uma pergunta ruim de vocabulário, tu tem um problema de modelagem

O erro comum deste passo: opções que se sobrepõem na vida real (integração de pagamento que é meio billing, meio technical) e que aparecem depois como distribuição espalhada na resposta

5. Dê uma saída pro caso ambíguo

O Choice sempre nomeia um vencedor. Sempre. Então a documentação manda dar a lista completa de opções e acrescentar uma opção de saída quando a lista pode não cobrir toda entrada, tipo other ou none of the above

A outra rota oficial é perguntar "nenhuma destas" como um Noul separado:

{
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    },
    "fits_no_department": {
      "type": "noul",
      "instructions": "Is this message outside the scope of billing, technical and sales?"
    }
  }
}

O erro comum deste passo: assumir que o Jev vai "se recusar" a responder quando nada encaixa. Ele não se recusa, ele elege alguém

6. No Score, escreva níveis como SITUAÇÕES, em array ordenado do baixo pro alto

No Score, criteria é um array ordenado de descrições de nível, da ponta baixa para a alta

E a orientação oficial é descrever situação, não grau: "Broken or degraded feature, but workaround exists" funciona, "Moderately severe" não

{
  "questions": {
    "severity": {
      "type": "score",
      "instructions": "How severe is the impact described by the customer?",
      "criteria": [
        "Cosmetic or question only, nothing is blocked",
        "Broken or degraded feature, but workaround exists",
        "Core flow unusable, money or data is stuck"
      ]
    }
  }
}

O erro comum deste passo: régua de advérbios ("levemente", "moderadamente", "muito"). Advérbio não é critério, é opinião

7. Separe a pergunta do contexto

O campo instructions pode ser string, objeto ou array. Isso permite deixar a pergunta num campo e os dados ou o contexto em outros, referenciando os campos pelo nome entre crases

E o estado aceita JSON aninhado: uma pergunta pode apontar para um valor aninhado por caminho com pontos e índices entre crases, tipo support.tickets[0].message

{
  "questions": {
    "department": {
      "type": "choice",
      "instructions": {
        "question": "Which team should handle the message in `support.tickets[0].message`?",
        "account_tier": "Enterprise"
      },
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Contexto longo ou lista de exemplos deve ficar em campos nomeados ao lado da pergunta, que o código pode trocar sem reescrever o enunciado

O erro comum deste passo: grudar contexto dentro da frase da pergunta, e aí cada mudança de negócio te obriga a reescrever o enunciado inteiro

8. Mande só o contexto que a pergunta usa

A orientação é incluir apenas o contexto relevante pras perguntas atuais, recuperando e filtrando em código antes de enviar, pra evitar distração e context rot

Essa decisão é meio-irmã da que tu toma ao montar o state do Jev, então vale alinhar os dois lados: pergunta estreita pede estado enxuto

O erro comum deste passo: despejar o objeto do usuário inteiro porque "vai que ajuda"

9. Decomponha em perguntas atômicas e componha o resultado no código

A orientação oficial é fazer as perguntas mais explícitas, estreitas e atômicas possíveis: decompor pergunta ampla em várias que avaliam uma propriedade cada, e combinar os resultados com lógica no código

E olha que massa: decompor não custa mais viagem de rede, porque perguntas sobre o mesmo estado são avaliadas em paralelo na mesma requisição

O erro comum deste passo: manter a pergunta guarda-chuva ("isso é urgente e do financeiro?") e depois tentar adivinhar qual metade puxou a confiança pra baixo

Antes e depois: perguntas mal formuladas que geram decisão instável

Chave autoexplicativa sem enunciado:

Antes:

{ "is_refund_request": { "type": "noul", "instructions": "" } }

Depois:

{
  "is_refund_request": {
    "type": "noul",
    "instructions": "Is the customer asking for money to be returned?"
  }
}

A chave é pra TEU código encontrar a resposta, não pro modelo entender a pergunta

Rótulos nus:

Antes:

{
  "department": {
    "type": "choice",
    "instructions": "Which team should handle this?",
    "criteria": { "billing": null, "technical": null, "sales": null }
  }
}

Depois: as mesmas três chaves com a rubrica curta do exemplo oficial ("Payments, invoicing, refunds" e companhia)

O null existe e é legítimo pra opção que não pede detalhe, só que usar ele em TODAS te tira a única coisa que diferencia os recortes

Opções que se sobrepõem:

O clássico: chega "minha integração de pagamento parou" e billing e technical brigam pelo ticket

Quando duas opções são parecidas e o modelo confunde, a descrição de cada opção pode ser um objeto dizendo o que aquela opção cobre, o que pertence a outra opção e alguns exemplos, usando os MESMOS nomes de campo em todas as opções

{
  "department": {
    "type": "choice",
    "instructions": "Which team should handle this?",
    "criteria": {
      "billing": {
        "covers": "Money movement outcomes: invoices, refunds, payouts not arriving",
        "not_this": "API errors or webhook failures, that is technical",
        "examples": ["payout never landed", "invoice charged twice"]
      },
      "technical": {
        "covers": "Bugs, outages and integration failures",
        "not_this": "Questions about amounts charged, that is billing",
        "examples": ["webhook returns 500", "SDK auth error"]
      }
    }
  }
}

Repare que o truque é a comparabilidade: mesmos campos nas duas opções, então a fronteira fica escrita dos dois lados

Score em graus:

Antes: ["Not severe", "Moderately severe", "Very severe"]

Depois: ["Cosmetic issue only", "Broken or degraded feature, but workaround exists", "Core flow unusable"]

"Moderadamente grave" só é definível se tu já souber o que é grave, e é exatamente isso que tu tá perguntando 😛

Pergunta ampla única:

Antes: uma pergunta só perguntando se o ticket é urgente E do financeiro

Depois: um Noul pra "é sobre dinheiro que não chegou?", um Score pra severidade, e o AND acontece no teu código

Como as perguntas do mesmo estado rodam em paralelo na mesma requisição, tu ganha diagnóstico separado sem pagar ida e volta extra

Como ler a resposta e saber se a pergunta está boa

Aqui é onde a redação vira número, e dá pra debugar feito código

Respostas de Choice e Score trazem probabilities, que é a distribuição entre opções ou níveis, e confidence, que resume essa distribuição num único número de 0 a 1

Noul é diferente: a resposta é um único número, a probabilidade de a resposta ser sim. 0 significa não, 1 significa sim, e perto de 0,5 o modelo dá probabilidade parecida pra sim e pra não

E Noul não tem propriedade de confiança separada, ao contrário de Choice e Score. Tome cuidado com isso na hora de escrever o if

Agora os sintomas:

• Confiança média ou baixa de forma recorrente naquela pergunta: suspeite de recorte sobreposto, de rótulo sem descrição ou de contexto demais atrapalhando
• Distribuição espalhada entre exatamente duas opções: a fronteira entre elas não está descrita. É caso de covers e not_this nas duas, com os mesmos campos
• Noul travado perto de 0,5: provavelmente a pergunta não é binária de verdade, e o que tu quer é um Score com níveis descritos
• Vencedor esquisito em entrada fora do escopo: falta a saída, seja other/none of the above, seja o Noul de "nenhuma destas"

E o que fazer com o número? A documentação sugere dividir a confiança em três faixas de ação:

• alta: agir automaticamente
• média: prosseguir com cautela, confirmando, sinalizando pra revisão ou buscando mais informação
• baixa: não agir, mandar pra humano, pedir esclarecimento ou usar outro sistema

Se liga nisso: o limiar não é um número único. A própria documentação diz que ações diferentes no mesmo sistema devem ser barradas em níveis diferentes conforme a consequência do erro

Rotear ticket errado é chato, estornar dinheiro errado é outro campeonato

Essa lógica de faixas é o que segura a barra quando tu vai encaixar o Jev num projeto que já existe, porque o caminho manual continua existindo embaixo

Pra quem tá chegando agora em ferramentas de IA pro dia a dia de desenvolvimento, esse vídeo do canal mostra o Agent View do Claude Code, o dashboard próprio pra acompanhar conversas:

Conclusão

O checklist mental da pergunta boa, pra tu colar no monitor:

• tipo escolhido pela FORMA da resposta (Noul binário, Score espectro, Choice conjunto)
• enunciado completo em instructions, sem apostar no nome da chave
• toda opção do Choice com descrição curta, recortes que não se sobrepõem
• saída pro ambíguo: other/none of the above ou um Noul de "nenhuma destas"
• Score em situações, array ordenado do baixo pro alto
• pergunta num campo, contexto em campos nomeados, e só o contexto que a pergunta usa
• perguntas atômicas, composição no teu código

Próximo passo prático: monta uma requisição pequena misturando Choice, Score e Noul sobre o MESMO estado e olha confidence antes de plugar isso em qualquer decisão automática

E iterar na redação é barato: o Jev cobra US$ 0,042 por 1 milhão de tokens de entrada, com tokens de saída gratuitos, então reescrever a mesma pergunta cinco vezes até a distribuição parar de balançar é o caminho normal, não desperdício

A versão listada na página de modelos da TypeSafe é a Jev 1.12, de setembro de 2026

Até o próximo post! =)