Como fazer roteamento e guardrails de LLM? Exemplo de colaboração entre Jev e grandes modelos de linguagem

Divulgação de interesses e evidências: A PandaNpc está desenvolvendo uma camada de decisão de agente que usa Jev. A seguir, citamos respectivamente a documentação oficial da TypeSafe, o cookbook oficial e chamadas reais do Jev e calibração de cenários sintéticos em nosso repositório. Nossa calibração usa um provedor de LLM falso e scriptado, portanto não representa tráfego real de usuários nem o desempenho de uma cadeia de produção completa.

O roteamento de LLM pode ser feito assim: primeiro deixe o Jev julgar a que categoria pertence a solicitação e qual o nível de risco; depois, o código decide se encaminha para uma função comum, um LLM especializado ou revisão humana. Jev também pode ser colocado entre recuperação e geração para filtrar evidências, ou após a saída do LLM para verificar resultados. Ele retorna opções fechadas, pontuações e probabilidades; respostas abertas, geração de código e raciocínio longo continuam a cargo do LLM. A explicação da TypeSafe sobre agentes de codificação deixa claro que Jev não pode substituir diretamente o modelo de chat por trás do Claude Code ou do Codex.

Este artigo usa uma solicitação de atendimento ao cliente, um pipeline de perguntas e respostas RAG e nosso próprio registro de calibração de agente para explicar onde os dois tipos de modelo realmente se encontram e por que resultados de baixa confiança precisam ter um destino claro.

O que o Jev consegue julgar e do que o LLM continua responsável?

Em 23 de setembro de 2026, a página de modelos da TypeSafe lista o modelo estável jev-1.13.0. A API aceita um state e um conjunto de questions, e retorna os answers estruturados correspondentes via POST /v1/systemone. jev-latest apontava para 1.13.0 naquele dia, mas o alias muda com as versões; sistemas com limites calibrados devem fixar a versão e registrar o ID real do modelo na resposta.

O Noul não tem um campo de confidence independente; não se pode escrever uma probabilidade de Noul diretamente como “confiança do modelo”. Score também não deve ser usado para calcular valores exatos. Valores monetários, comparação de datas, cotas e verificações de permissão devem permanecer em programas determinísticos; a documentação oficial já lista esses limites do Jev 1.13.

A forma mínima de uma chamada

A forma de requisição abaixo é consistente com a referência oficial da API; a pergunta de exemplo é uma configuração ilustrativa construída para este artigo, e não foi testada online aqui:

O JSON abaixo usa uma mensagem de cliente em inglês; em português do Brasil, o cliente diria “O pedido foi cobrado duas vezes, por favor me ajude com o reembolso.”

{
  "model": "jev-1.13.0",
  "state": {
    "message": "My order was charged twice. Please help me get a refund.",
    "account_note": "Customer asks about an order charge"
  },
  "questions": {
    "intent": {
      "type": "choice",
      "instructions": "What does state.message primarily request?",
      "criteria": {
        "refund": "Money returned for a charge",
        "information": "An explanation only",
        "other": "Neither option fits"
      }
    },
    "asks_refund": {
      "type": "noul",
      "instructions": "Does state.message explicitly ask for money back?"
    }
  }
}

Um sistema real também deve primeiro verificar por código se os lançamentos de cobrança pertencem ao mesmo pedido e se o reembolso é permitido. O exemplo acima serve apenas para interpretar a intenção do usuário; o usuário pedir reembolso não significa que o direito ao reembolso foi comprovado, muito menos constitui autorização para executar o reembolso diretamente.

Usar Jev para roteamento de LLM: três caminhos de transferência

O exemplo oficial de roteamento de intenção da TypeSafe entrega primeiro a solicitação de atendimento ao Jev para julgar intenção e complexidade, e então o código faz o roteamento: consulta de status do pedido vai para uma função de banco de dados; dúvidas de produto e devoluções/trocas vão para LLMs especializados carregados com materiais diferentes; reclamações complexas ou resultados de baixa confiança entram na fila humana. Esta é a colaboração mais fácil de entender entre Jev e LLM: o primeiro fornece julgamentos estruturados; o segundo entra em cena apenas quando é necessário gerar explicações ou diálogo.

Na implementação, pode-se projetar na seguinte ordem, em vez de deixar o modelo decidir livremente todas as ações:

1. Defina primeiro os caminhos: liste claramente as solicitações que funções comuns, cada LLM especializado e a revisão humana conseguem tratar, e deixe other ou uma opção equivalente de fallback para o Choice.
2. Coloque os fatos no state: fala original do usuário, status da conta e registros de pedido devem ser campos separados; não trate texto de páginas web de origem desconhecida como instrução de sistema.
3. Faça perguntas estreitas de cada vez: use Choice para intenção, Score para risco ou urgência, e Noul para um fato pontual que precise de confirmação. A recomendação oficial é que várias perguntas independentes sobre o mesmo state podem ser avaliadas em paralelo na mesma requisição.
4. Deixe o código fazer o roteamento final: primeiro verifique permissões e regras rígidas, depois veja as probabilidades do Jev e os limiares calibrados para este negócio; solicitações de baixa confiança ou com falta de evidência vão para revisão humana ou pergunta adicional.
5. Registre os resultados e revise: salve versão do modelo, versão da pergunta, probabilidades, destino final e resultados de correção humana, para poder julgar se o limiar é adequado.

Fonte da imagem: TypeSafe AI — “Apresentando System One Models & Jev”, 2026-09-15. Os quatro workflows foram construídos pela própria TypeSafe; as métricas são agregadas com pesos iguais por workflow; o método de avaliação está em avaliações de workflow da TypeSafe.

Esta imagem oficial ajuda a entender por que ele enfatiza “colocar vários julgamentos estreitos dentro de um workflow de software”. O eixo vertical na figura usa o nome “accuracy” do fabricante, mas sua referência de resposta vem do consenso de probabilidades previstas por dois grandes modelos, não de uma única resposta correta verificada por humanos; o custo e as métricas também dependem desses quatro workflows e do método de avaliação do fabricante, e não podem ser convertidos em “quanto se economiza em qualquer cenário”.

Geração aumentada por recuperação: Jev filtra evidências antes da resposta do LLM

O cookbook de passagens RAG da TypeSafe oferece um exemplo multimodelo mais concreto: o embedding da OpenAI primeiro recupera parágrafos; o Jev faz quatro perguntas Noul para cada “pergunta + parágrafo” — se é relevante, se contém evidência utilizável para responder, se refuta a premissa da pergunta, e se tenta dar instruções ao modelo de resposta. O código processa as quatro probabilidades em ordem e decide colocar o parágrafo na área de evidências, na área de evidências conflitantes, ou descartá-lo; fim, o Claude Sonnet 5 escreve a resposta.

Esta etapa resolve um problema comum: parágrafos com alta similaridade vetorial não são necessariamente utilizáveis. Eles podem apenas usar palavras semelhantes, ou podem ser um post de fórum contendo uma injeção de prompt como “ignore o texto anterior”. O exemplo do cookbook coloca a verificação de injeção antes das regras de roteamento e também lembra que o limiar é um ponto de partida escolhido para aquele corpus, não o valor padrão para todas as aplicações RAG. Seus números de demonstração vêm do jev-1.12 de 2026-08-27 e não podem ser tomados como novos resultados de avaliação do atual jev-1.13.0.

Depois da geração, também se pode fazer uma camada de verificação. O cookbook de verificação de citações da TypeSafe primeiro usa código para encontrar o texto original da citação, e depois usa Jev para julgar se aquele trecho apoia, refuta ou não menciona a afirmação gerada. Ele consegue destacar citações que merecem revisão; o julgamento do modelo ainda pode errar, e “passou na verificação” não pode ser escrito como garantia de fato.

Nossa calibração de agente: onde a escalada por baixa confiança pode travar?

No repositório da PandaNpc, o cliente Jev, o banco de perguntas e o orquestrador usam o Jev na identificação de intenção do agente, na pontuação de modificações candidatas, na verificação de condições de conclusão e na decisão de submissão. O cliente também faz retentativas limitadas para timeout, 429 e 5xx, e impõe limites ao orçamento de requisições e a resultados expirados; a permissão de execução é controlada pelo orquestrador e pela camada de ferramentas controladas, e não é concedida diretamente por um julgamento do Jev.

Em 2026-09-22, usamos jev-1.13.0 para executar 19 turnos sintéticos uma vez em shadow e uma vez em enforce, totalizando 38 execuções, e registramos 165 decisões reais do Jev. Este relatório interno de calibração e as respostas reais salvas usam um provedor de LLM falso e scriptado; portanto, esses dados só mostram o desempenho de decisão em cenários controlados. Eles não podem comprovar a taxa de sucesso geral, a proporção de economia ou a latência ponta a ponta sob solicitações reais de usuários.

A descoberta mais valiosa não foi a velocidade média, mas sim um limiar “aparentemente seguro” que causou bloqueio: dos 19 turnos em enforce, 13 escalaram na Q2 “a informação é suficiente para começar a modificação?”, porque a probabilidade do Noul caiu na faixa incerta original de 0.15–0.85; o LLM Worker não teve chance de executar as etapas seguintes. O registro de calibração mostra que, das 34 decisões de Q2 anotadas como com informação suficiente, muitas probabilidades ficaram no meio da faixa. O relatório sugere dividir a Q2 complexa em julgamentos mais atômicos, ou ajustar as regras de escalada; essas são sugestões, não limiares já implantados.

Nosso banco de perguntas classifica a entrada como answer_only, inspect, modify ou out_of_scope; no caminho de escrita, as modificações candidatas propostas pelo Worker são primeiro ordenadas por Score, e o conteúdo final e o resumo de alterações passam por verificação de aceitação e decisão de submissão. Esses são apenas pontos de decisão: se é possível de fato ler ou escrever um objeto ainda é determinado pelo executor controlado, que concede permissões por estágio. O Jev não tem autoridade para relaxar por conta própria a lista de permissões de ferramentas, nem pode contornar a verificação de consistência antes da submissão.

Os dados de calibração revelam outro trade-off. No modo shadow, o Jev fornece respostas e a distribuição completa, mas não altera o caminho de execução original do Worker; no modo enforce, a resposta influencia se continua, escala ou descarta. Tomar diretamente a acurácia do shadow como taxa de conclusão do enforce seria ler o sistema errado: a escalada da Q2 intercepta a tarefa antes do tempo, fazendo com que as perguntas posteriores de pontuação de candidatos, aceitação e submissão nem sequer tenham chance de aparecer. Por isso, este relatório lê separadamente a distribuição de cada pergunta, a direção da escalada e o estado final.

Há um contraste concreto entre modificações candidatas: no mesmo turno, uma candidata que modificava precisamente o alvo recebeu 2.94 pontos, enquanto uma candidata que sobrescrevia o arquivo inteiro recebeu 0.38 ponto; a candidata de maior pontuação foi escolhida. Este exemplo só mostra que, naquele contexto sintético, a pergunta de pontuação distinguiu as duas propostas. Por outro lado, uma candidata com evidência truncada recebeu 2.27 pontos; não se pode ignorar sua baixa confiança e marcação de truncamento só porque o número parece “razoável”. Nosso código sinaliza separadamente evidência incompleta, para evitar que o modelo faça um julgamento determinístico de escrita apenas com base no prefixo preservado.

Também separamos “qual candidata escolher” e “permitir ou não que ela escreva” em duas etapas diferentes. Depois que a candidata passa pela pontuação do Jev, o executor controlado só abre ferramentas de escrita na fase ACT/modify; o ticket de uso único emitido vincula o ID da chamada de ferramenta, o número da revisão atual, o hash do objeto alvo e o resumo dos parâmetros. Mesmo que o texto da candidata induza o modelo a “ignorar restrições”, ele não obtém permissão de ferramenta para passar por essas verificações. Esta é a experiência que tiramos integração em nível de código: o julgamento probabilidade decide qual caminho vale a pena seguir, a permissão de efeito colateral é determinada por condições programáticas auditáveis.

Os caminhos de falha também precisam ser projetados O cliente só faz retentativas limitadas em timeout, erro de rede, 429 ou 5xx; respostas canceladas ou que ultrapassam o prazo turno são descartadas diretamente. Se oev estiver indisponível no modo enforce, não se pode continuar sem autorização de degradação; quando é permitido usar llm_only, o executor trava em somente leitura. Se uma ramificação já sofreu modificações e só então perde o Jev, o orquestrador marca o turno inteiro como falho, em vez de deixar o LLM seguinte completar a escrita sem a camada de decisão. Esses caminhos têm custo para a experiência do usuário, mas fazem com quemodelo temporariamente indisponível” não se torne silenciosamente “permissão de escrita como antes”.

O relatório de calibração também distingue “escalada por baixa confiança” de “recusa de execução”. Por exemplo, um discard correto, se a confiança não atingir o limiar unificado de 0.85, será registrado como necessitando de entrada do usuário; isso não é o mesmo que liberação incorreta. Com base nisso, o relatório sugere separar os limiares de submissão e de descarte, mas isso ainda é uma sugestão. Ao escrever workflows, é preciso distinguir três resultados: liberação incorreta, recusa incorreta e pendente de revisão; caso contrário, o mesmo conjunto de dados levará a conclusões erradas sobre limiares.

Este caso nos diz que a cooperação entre Jev e LLM não pode ser desenhada apenas como “Jev julga primeiro, LLM trabalha depois”. Para cada julgamento, é preciso perguntar: qual é a largura da faixa de incerteza? Isso fará com que o processador seguinte nunca receba tarefas? Se a evidência de entrada for truncada, é possível escalar explicitamente em vez de adivinhar? Em nossa implementação, o construtor de state registra evidence_truncated e faz com que o chamador trate o caminho com falta de evidência como incerto; cálculos determinísticos como contagem e ordenação são feitos primeiro no código, e não deixados para o Jev adivinhar. As limitações conhecidas oficiais do Jev 1.13 também recomendam deixar contagem e aritmética no código.

Onde os guardrails de LLM devem ficar?

O cookbook de guardrails de LLM da TypeSafe coloca o Jev nos dois lados da entrada e da saída do LLM. Ele usa um conjunto de Noul para identificar diferentes riscos, usa Score para medir a gravidade, e então o código decide, segundo a política, liberar, revisar manualmente, bloquear ou encaminhar ao suporte. A saída também precisa ser verificada, porque uma entrada comum ainda pode produzir um resultado de geração inadequado.

A fronteira desse tipo de guardrail também é clara: o Jev pode verificar conteúdo com perguntas previamente escritas, mas não é uma prova de segurança universal. O documento oficial de limitações menciona explicitamente que conteúdo malicioso pode influenciar o julgamento, exigindo criteria bem escritos e testes de fronteira. Em nossas amostras sintéticas, fizemos 16 sondagens de injeção contra parâmetros candidatos e registramos 0 inversões de ordenação; a amostra é pequena demais para concluir que “resistência a prompt injection está resolvida”. O que realmente determina o que a ferramenta pode fazer continua sendo a lista de permissões no código, os portões por estágio e as verificações antes da submissão.

Quando é adequado usar e quando não usar?

O Jev é adequado quando: o conjunto de candidatos é conhecido, a pergunta pode ser dividida em alguns julgamentos curtos, e o software precisa de probabilidades para decidir entre processamento automático ou escalada para humano. Por exemplo, roteamento de atendimento, filtragem de parágrafos RAG, pontuação de ações candidatas de agente e verificação de citações em resultados gerados. Se a tarefa exigir escrever uma resposta, alterar um trecho de código ou explicar um processo de raciocínio complexo, o LLM assume. Se a tarefa for calcular dinheiro com precisão, comparar datas ou verificar controle de acesso, o programa deve calcular diretamente. A página de modelos também explica que o Jev só aceita texto, e que inglês é atualmente a língua de treinamento com melhor desempenho; cenários em chinês precisam ser avaliados com seus próprios dados, e não se deve copiar os limiares do cookbook em inglês.

Se você quiser observar como um agente real lida com permissões e chamadas de ferramentas, pode começar por Agente PandaNpc; sobre os limites e casos de uso de agentes de codificação, também pode consultar Comparação entre Claude Code e Codex.

O leitor pode começar com um conjunto de validação bem pequeno: prepare quatro tipos de amostras — “claramente pode ser processado automaticamente”, “claramente deve ser recusado”, “semanticamente ambíguo” e “contém instruções maliciosas”; primeiro defina a anotação humana, depois registre as probabilidades de cada pergunta do Jev e os resultados de roteamento. O critério de sucesso não é que todos passem automaticamente, mas que a taxa de erro do caminho de processamento automático e o volume de escalada humana fiquem dentro do que você pode aceitar. Se muitas amostras ambíguas travarem na mesma pergunta, verifique primeiro se a pergunta mistura vários julgamentos, se o state é longo demais ou se os limiares foram calibrados com dados locais.

FAQ

O Jev pode substituir o Claude Code, o Codex ou um modelo de chat? Não. A TypeSafe o posiciona como um modelo de decisão estruturada dentro de software; chat, escrita e geração de código ainda precisam de um LLM.

Se o tipo de retorno é fixo, ele não erra? Não. Tipos fixos reduzem problemas de parsing e de saída fora do escopo, mas classificação, pontuação e julgamento de fatos ainda podem errar. Caminhos de baixa confiança e alto risco devem manter revisão humana.

Quantas perguntas podem ser feitas na mesma requisição? Vários Choice, Score e Noul independentes que compartilham o mesmo state podem ser colocados em uma única requisição. As perguntas são avaliadas individualmente; julgamentos complexos ainda devem ser separados e depois combinados pelo código.

Chinês pode ser usado? A documentação oficial afirma suporte a linguagens naturais, incluindo caracteres CJK, mas o inglês tem atualmente a melhor precisão. Cargas de trabalho em chinês precisam de validação e calibração separadas.