Come si implementano routing LLM e guardrail? Un esempio di collaborazione tra Jev e i modelli linguistici

Informativa su interessi e prove: PandaNpc sta sviluppando un livello decisionale Agent che usa Jev. Di seguito citiamo separatamente la documentazione ufficiale di TypeSafe, il cookbook ufficiale, nonché chiamate reali a Jev e la calibrazione di scenari sintetici dal nostro repository. La nostra calibrazione usa un provider LLM fittizio scriptato e non può rappresentare il traffico reale degli utenti o le prestazioni dell'intera catena di produzione.

Il routing LLM può funzionare così: prima si lascia che Jev determini a quale categoria appartiene la richiesta e quanto è alto il rischio; poi il codice decide se affidarla a una funzione normale, a un LLM specializzato o alla revisione umana. Jev può anche essere inserito tra recupero e generazione per filtrare le prove, oppure dopo l'output dell'LLM per controllare i risultati. Restituisce opzioni chiuse, punteggi e probabilità; risposte aperte, generazione di codice e ragionamenti lunghi restano compito dell'LLM. La spiegazione di TypeSafe sugli agenti di programmazione afferma esplicitamente che Jev non può sostituire direttamente il modello di chat dietro Claude Code o Codex.

Questo articolo usa una richiesta di assistenza clienti, una pipeline RAG di domande e risposte e i nostri registri di calibrazione dell'Agent per spiegare dove avviene esattamente il passaggio di consegne tra i due tipi di modello e perché i risultati a bassa confidenza devono avere una destinazione esplicita.

Che cosa può giudicare Jev e di che cosa continua a occuparsi l'LLM?

Al 23 settembre 2026, il modello stabile elencato nella pagina dei modelli TypeSafe è jev-1.13.0. L'API accetta uno state e un insieme di questions e restituisce le corrispondenti answers strutturate tramite POST /v1/systemone. In quella data jev-latest puntava a 1.13.0, ma gli alias cambiano con le versioni; i sistemi con soglie calibrate dovrebbero fissare la versione e registrare l'ID effettivo del modello nella risposta.

Noul non ha un campo confidence separato; non si può scrivere direttamente una probabilità Noul come "confidenza del modello". Anche Score non dovrebbe essere usato per calcolare importi precisi. Importi, confronti di date, quote e controlli dei permessi dovrebbero restare in programmi deterministici; la documentazione ufficiale elenca questi limiti di Jev 1.13.

La forma minima di una chiamata

La forma della richiesta seguente è coerente con il riferimento API ufficiale; la domanda di esempio è una configurazione illustrativa costruita per questo articolo e non è stata testata online per questo articolo:

Il JSON riportato di seguito usa un messaggio cliente in inglese; in italiano, il cliente direbbe “Il mio ordine è stato addebitato due volte, per favore aiutami a ottenere un rimborso.”

{
  "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?"
    }
  }
}

Un sistema reale dovrebbe anche verificare prima con il codice se i movimenti di addebito appartengono allo stesso ordine e se il rimborso è consentito. L'esempio precedente serve solo a interpretare l'intento dell'utente; il fatto che l'utente chieda un rimborso non significa che il diritto al rimborso sia stato dimostrato, né costituisce un'autorizzazione a eseguire direttamente il rimborso.

Usare Jev per il routing LLM: tre percorsi di passaggio di consegne

L'esempio ufficiale TypeSafe di routing delle intenzioni affida prima a Jev la richiesta di assistenza clienti per determinare intento e complessità, poi il codice smista: la verifica dello stato dell'ordine passa a una funzione di database; le domande sui prodotti e i resi/cambi passano rispettivamente a LLM specializzati caricati con materiali diversi; i reclami complessi o i risultati a bassa confidenza finiscono in coda per la revisione umana. Questa è la collaborazione più facile da comprendere tra Jev e LLM: il primo fornisce giudizi strutturati, il secondo entra in scena solo quando serve generare spiegazioni o conversazione.

In fase di implementazione si può progettare secondo l'ordine seguente, invece di lasciare che il modello decida liberamente tutte le azioni:

1. Definisci prima i percorsi: elenca chiaramente le richieste che funzioni normali, LLM specializzati e revisione umana possono gestire, e lascia per Choice un'opzione di fallback other o simile.
2. Metti i fatti nello state: le parole originali dell'utente, lo stato dell'account e i registri degli ordini diventano campi separati; non trattare testo web di provenienza ignota come istruzione di sistema.
3. Fai una domanda ristretta alla volta: usa Choice per l'intento, Score per il rischio o l'urgenza, Noul per un singolo fatto da confermare. La documentazione ufficiale consiglia di valutare in parallelo più domande indipendenti sullo stesso state nella stessa richiesta.
4. Lascia che il codice faccia il routing finale: controlla prima permessi e regole rigide, poi le probabilità di Jev e le soglie calibrate per questo business; le richieste a bassa confidenza o prive di prove vanno alla revisione umana o a una domanda di chiarimento.
5. Registra i risultati e riesamina: salva versione del modello, versione delle domande, probabilità, destinazione finale ed esiti delle correzioni umane, per poter giudicare se le soglie sono adeguate.

Fonte dell'immagine: TypeSafe AI, «Introduzione a System One Models e Jev», 15 settembre 2026. I quattro workflow sono stati costruiti internamente da TypeSafe e le metriche sono aggregate con uguale peso per workflow; per il metodo di valutazione vedere valutazioni dei workflow TypeSafe.

Questo grafico ufficiale può aiutare a capire perché si sottolinea "inserire più giudizi ristretti in un workflow software". L'asse verticale del grafico mantiene la denominazione "accuracy" del fornitore, ma il suo riferimento deriva dal consenso delle probabilità previste da due grandi modelli, non da un'unica risposta corretta verificata manualmente; costi e metriche dipendono anche da questi quattro workflow e dal metodo di valutazione del fornitore, e non possono essere convertiti in "quanto si risparmia in qualsiasi scenario".

Generazione aumentata dal recupero: Jev filtra le prove prima che l'LLM risponda

Il cookbook TypeSafe per i passaggi RAG fornisce un esempio multi-modello più concreto: l'embedding OpenAI recupera prima i passaggi; Jev, per ogni "domanda + passaggio", pone quattro Noul — se è pertinente, se contiene prove utilizzabili per rispondere, se confuta la premessa nella domanda, se tenta di impartire istruzioni al modello che risponde. Il codice elabora in ordine le quattro probabilità e decide se inserire il passaggio nell'area delle prove, in quella delle prove in conflitto o scartarlo; infine Claude Sonnet 5 scrive la risposta.

Questo passo risolve un problema comune: i passaggi con alta similarità vettoriale non sono necessariamente utilizzabili. Potrebbero usare solo parole simili, oppure essere un post di forum che contiene un prompt injection del tipo "ignora quanto precede". L'esempio del cookbook mette il controllo di injection all'inizio delle regole di routing, e allo stesso tempo avverte che la soglia è un punto di partenza scelto per quel corpus, non un valore predefinito per tutte le applicazioni RAG. I numeri dimostrativi provengono da jev-1.12 del 27 agosto 2026 e non possono essere considerati nuovi risultati di valutazione dell'attuale jev-1.13.0.

Dopo la generazione si può aggiungere un ulteriore livello di verifica. Il cookbook TypeSafe per il controllo delle citazioni usa prima un programma per trovare il testo originale della citazione, poi Jev per giudicare se quel passaggio supporta, confuta o non menziona l'affermazione generata. Può individuare le citazioni che meritano una revisione; il giudizio del modello può comunque sbagliare, quindi "supera il controllo" non va scritto come garanzia di fatto.

La nostra calibrazione dellAgent: dove si blocca l'escalation aa confidenza?

Nel repository PandaNpc, il client Jev, la libreria di domande e l'orchestratore usano Jev per il riconoscimento dell'intento dell'Agent, il punteggio delle modifiche candidate, la verifica delle condizioni di completamento e la decisione di invio. Il client gestisce anche timeout, 429 e 5xx con retry limitati, e impone limiti al budget di richieste e ai risultati scaduti; i permessi di esecuzione sono in mano all'orchestratore e al livello di strumenti controllati, e non vengono concessi direttamente da un singolo giudizio di Jev.

Il 22 settembre 2026 abbiamo usato jev-1.13.0 per eseguire una volta in shadow e una volta in enforce su 19 turn sintetici, per un totale di 38 esecuzioni, registrando 165 decisioni reali di Jev. Questo rapporto di calibrazione interno e le risposte reali salvate usano un provider LLM fittizio scriptato, quindi questi dati descrivono solo il comportamento decisionale in scenari controllati. Non possono dimostrare il tasso di successo complessivo, la percentuale di risparmio o la latenza end-to-end con richieste di utenti reali.

La scoperta più preziosa non è la velocità media, ma un blocco causato da una soglia "apparentemente sicura": nei 19 turn in enforce, 13 sono stati escalati in Q2 "le informazioni sono sufficienti per iniziare la modifica" perché la probabilità Noul cadeva nell'intervallo di incertezza previsto 0,15–0,85; l'LLM Worker non ha avuto modo di eseguire i passaggi successivi. I registri di calibrazione mostrano che, tra 34 decisioni Q2 etichettate come informazioni sufficienti, molte probabilità erano nella fascia intermedia. Il rapporto suggerisce di scomporre il complesso Q2 in giudizi più atomici o di modificare le regole di escalation; questi sono suggerimenti, non soglie già distribuite.

La nostra libreria di domande classifica l'ingresso come answer_only, inspect, modify o out_of_scope; sul percorso di scrittura, le modifiche candidate proposte dal Worker vengono prima ordinate da Score, e il contenuto finale con il riepilogo delle modifiche passa poi per l'accettazione e la decisione di invio. Questi sono solo punti decisionali: se sia possibile leggere o scrivere effettivamente un oggetto lo decide ancora l'esecutore controllato, che concede i permessi per fase. Jev non ha il potere di allargare da solo la whitelist degli strumenti, né di aggirare i controlli di coerenza prima dell'invio.

I dati di calibrazione rivelano un altro compromesso. In modalità shadow, Jev fornisce la risposta e la distribuzione completa, ma non modifica il percorso di esecuzione originale del Worker; in modalità enforce, la risposta influenza se continuare, escalare o scartare. Prendere direttamente l'accuratezza shadow come tasso di completamento enforce significa fraintendere il sistema: l'escalation di Q2 interrompe il compito in anticipo, facendo sì che le successive domande di punteggio delle candidate, accett e invio non abbiano nemmeno la possibilità di comparire. Perciò questo rapporto legge separatamente la distribuzione per domanda, la direzione dell'escalation e lo stato finale.

Tra le modifiche candidate c'è un confronto concreto: nello stesso turn, una candidata che modificava con precisione l'obiettivo ha ottenuto 2,94 punti, mentre una candidata che sovrascriveva l'intero file ha ottenuto 0,38 punti; la candidata con punteggio più alto è stata scelta. Questo esempio mostra solo che, in quello scenario sintetico, la domanda di punteggio distingueva due alternative. Al contrario, una candidata con prove troncate ha ottenuto 2,27 punti; non si devono ignorare la sua bassa confidenza e il marcatore di troncamento solo perché il valore sembra "buono". Il nostro codice segnala separatamente le prove incomplete, per evitare che il modello prenda una decisione di scrittura definitiva basandosi solo sul prefisso conservato.

Abbiamo anche separato in due passaggi distinti "quale candidata scegliere" e "permetterle di scrivere". Dopo che una candidata ha superato il punteggio di Jev, l'esecutore controllato apre gli strumenti di scrittura solo nella fase ACT/modify; il ticket monouso emesso è vincolato all'ID della chiamata allo strumento, al numero di revisione corrente, all'hash dell'oggetto di destinazione e al riepilogo dei parametri. Anche se il testo della candidata induce il modello a "ignorare i limiti", non ottiene i permessi degli strumenti per superare questi controlli. Questa è l'esperienza che abbiamo tratto dall'integrazione a livello di codice: il giudizio probabilistico decide quale strada vale la pena seguire, mentre i permessi con effetti collaterali sono determinati da condizioni programmatiche riesaminabili.

Anche i percorsi di fallimento vanno progettati. Il client riprova in modo limitato solo in caso di timeout, errore di rete, 429 o 5xx; le risposte annullate o oltre la scadenza del turn vengono scartate direttamente. Se Jev non è disponibile in modalità enforce, non si può continuare senza autorizzazione al degrado; quando è consentito passare a llm_only, l'esecutore si blocca in sola lettura. Se il ramo ha già subito modifiche e poi perde Jev, l'orchestratore segna l'intero turn come fallito, invece di lasciare che l'LLM successivo completi la scrittura in assenza del livello decisionale. Questi percorsi hanno un costo per l'esperienza utente, ma fanno sì che "modello temporaneamente non disponibile" non diventi silenziosamente "permessi di scrittura come prima".

Il rapporto di calibrazione distingue anche tra "escalation a bassa confidenza" e "rifiuto di eseguire". Per esempio, un discard corretto, se la confidenza non raggiunge la soglia uniforme di 0,85, viene registrato come caso che richiede input dell'utente; questo non equivale a un'autorizzazione errata. Il rapporto suggerisce quindi di separare le soglie di invio e di scarto, ma per ora restano suggerimenti. Quando si scrive un workflow bisogna distinguere chiaramente i tre esiti — autorizzazione errata, rifiuto errato e attesa di revisione — altrimenti lo stesso insieme di dati porta a conclusioni sbagliate sulle soglie.

Questo caso ci dice che la collaborazione tra Jev e LLM non può essere rappresentata solo come "prima Jev giudica, poi l'LLM lavora". Per ogni giudizio bisogna chiedersi: quanto è ampio l'intervallo di incertezza? Può impedire per sempre ai processori successivi di ricevere il compito? Se le prove in input sono troncate, si può escalare esplicitamente invece di indovinare? Nella nostra implementazione, il costruttore di state registra evidence_truncated e fa sì che il chiamante consideri incerto il percorso con prove mancanti; i calcoli deterministici come conteggi e ordinamenti vengono fatti prima nel codice, e non lasciati indovinare a Jev. I limiti noti ufficiali di Jev 1.13 consigliano anch'essi di lasciare conteggi e aritmetica nel codice.

Dove dovrebbero stare i guardrail LLM?

Il cookbook TypeSafe sui guardrail LLM mette Jev su entrambi i lati dell'input e dell'output dell'LLM. Usa un insieme di Noul per identificare rischi diversi, Score per misurarne la gravità, e poi il codice decide in base alla policy se autorizzare, far revisionare da una persona, bloccare o inoltrare al supporto. Anche l'output va controllato, perché da un input normale può comunque derivare un risultato generato inappropriato.

Anche i confini di questo tipo di guardrail sono chiari: Jev può controllare i contenuti secondo domande scritte in anticipo, ma non è una prova di sicurezza universale. Il documento ufficiale sui limiti menziona esplicitamente che contenuti malevoli possono influenzare il giudizio, e richiede di scrivere chiaramente i criteri e testare i confini. Nei nostri campioni sintetici abbiamo eseguito 16 probe di injection mirate ai parametri delle candidate, registrando 0 inversioni di ordinamento; il campione è troppo piccolo per concludere che "la resistenza al prompt injection è risolta". Ciò che determina davvero cosa possono fare gli strumenti restano la allowlist nel codice, i gate di fase e i controlli prima dell'invio.

Quando è adatto usarlo e quando no?

Jev è adatto quando: l'insieme delle candidate è noto, la domanda può essere scomposta in pochi giudizi brevi, e il software ha bisogno di probabilità per decidere se automatizzare o escalare a una persona. Per esempio routing dell'assistenza clienti, filtro dei passaggi RAG, punteggio delle azioni candidate dell'Agent, controllo delle citazioni nei risultati generati. Se il compito richiede di scrivere una risposta, modificare un pezzo di codice o spiegare un ragionamento complesso, se ne occupa l'LLM. Se il compito è calcolare con precisione importi, confrontare date o verificare controlli di accesso, il programma dovrebbe calcolare direttamente. La pagina dei modelli spiega anche che Jev accetta solo testo e che l'inglese è la lingua di addestramento con le prestazioni migliori al momento; gli scenari in cinese richiedono una valutazione con i propri dati e non possono adottare alla lettera le soglie dei cookbook in inglese.

Se si vuole osservare come un Agent reale gestisce permessi e chiamate agli strumenti, si può iniziare da PandaNpc Agent; per i confini e gli scenari d'uso degli Agent di programmazione, si può consultare anche Claude Code e Codex a confronto.

Il lettore può iniziare con un insieme di validazione molto: preparare quattro categorie di campioni — "chiaramente automatizzabile", "chiaramente da rifiutare", "semanticamente ambiguo" e "contenente istruzioni malevole"; prima definire le etichette manuali, poi registrare le probabilità di Jev per ogni domanda e i risultati del routing. Il criterio di successo non è che ogni elemento passi automaticamente, ma che il tasso di errore del percorso automatico e il volume di escalation umane rientrino in un intervallo accettabile per voi. Se molti campioni ambigui si bloccano sulla stessa domanda, controllare prima se la domanda mescola più giudizi, se lo state è troppo lungo o se le soglie sono calibrate sui dati locali.

FAQ

Jev può sostituire Claude Code, Codex o un modello di chat? No. TypeSafe lo posiziona come modello decisionale strutturato all'interno del software; chat, scrittura e generazione di codice richiedono ancora un LLM.

Se il tipo restituito è fisso, significa che non può sbagliare? No. I tipi fissi riducono i problemi di parsing e di output fuori formato, ma classificazione, punteggio e giudizi sui fatti possono comunque sbagliare. I percorsi a bassa confidenza e ad alto rischio dovrebbero mantenere la revisione umana.

Quante domande si possono fare nella stessa richiesta? Si possono mettere in una sola richiesta più Choice, Score e Noul indipendenti che condividono lo stesso state. Le domande vengono valutate separatamente; i giudizi complessi vanno comunque scomposti e poi combinati dal codice.

Si può usare il cinese? La documentazione ufficiale dichiara il supporto per linguaggi naturali, inclusi i caratteri cinesi, giapponesi e coreani, ma al momento l'accuratezza migliore è in inglese. I workload in cinese richiedono validazione e calibrazione separate.