Progettare un harness per agenti: scegliere il modello giusto

L’instradamento dei modelli è un problema di controllo operativo, non un esercizio di classifica. I requisiti di privacy e residenza dei dati definiscono prima l’insieme dei modelli ammissibili; il successo delle attività e la qualità dei risultati stabiliscono quali funzionano al suo interno; solo dopo si ottimizzano token, latenza e costo. I modelli locali possono essere efficaci, ma in genere richiedono una scomposizione più rigorosa, un migliore recupero delle informazioni e verifiche deterministiche.

L’ambiente di esecuzione è l’unità produttiva

Un agente aziendale non è un modello con un lungo prompt di sistema. È un ambiente di esecuzione (harness): acquisizione delle richieste, composizione del contesto, verifiche vincolanti delle regole, esecuzione del modello, accesso agli strumenti, stato, verifica, logica dei nuovi tentativi, osservabilità e passaggio al livello competente. Il modello è un componente sostituibile del sistema.

I confronti tra modelli condotti fuori dall’ambiente di esecuzione spesso non permettono di prevedere i risultati in produzione. Un modello può ottenere buoni risultati in un benchmark ma faticare con formati, autorizzazioni, lessico o flussi di lavoro aziendali. Un altro può sembrare meno capace nella conversazione aperta, ma funzionare in modo affidabile quando l’attività viene scomposta, le evidenze vengono recuperate e i risultati vengono verificati rispetto a vincoli deterministici.

Scegliere «il modello migliore» è quindi l’astrazione sbagliata. Scegliamo un percorso di esecuzione ammissibile per un’attività definita. Il percorso può usare un modello, più chiamate specializzate, un modello locale, uno ospitato oppure nessun modello. Ha successo solo quando l’attività raggiunge uno stato aziendale verificato.

L’architettura deve rendere esplicita questa sostituibilità. Un livello operativo IA basato su thread separa il contesto dell’utente dall’esecutore, mantenendo stabili instradamento, stato, autorizzazioni e verifiche quando cambia il modello.

Prima verifica: privacy, residenza e ammissibilità contrattuale

L’instradamento precede la valutazione della qualità. Occorre prima stabilire se un endpoint del modello sia autorizzato a ricevere i dati ed eseguire l’azione.

Per ogni classe di attività definiamo un profilo di ammissibilità. Comprende:

classificazione dei dati e presenza di informazioni personali, riservate, regolamentate o soggette a controlli all’esportazione;
regioni richieste per l’elaborazione e l’archiviazione;
condizioni di conservazione, registrazione, uso per l’addestramento ed eliminazione;
sub-responsabili del trattamento e vincoli ai trasferimenti transfrontalieri;
requisiti di cifratura, identità e controllo degli accessi;
obblighi relativi ai registri delle operazioni e alle notifiche degli incidenti;
possibilità per gli strumenti di leggere o modificare sistemi in produzione;
possibilità di trasferire i documenti recuperati fuori da un ambiente controllato.

Sono vincoli di instradamento, non un paragrafo di regole aggiunto dopo il lancio. Se un’attività contiene dati soggetti a restrizioni, il sistema di instradamento deve escludere gli endpoint che non soddisfano il profilo. L’oscuramento dei dati può talvolta produrre un’attività derivata meno soggetta a restrizioni, ma deve essere affidabile, registrato e testato sui formati interessati. Sostituire un nome lasciando un numero di conto univoco o una combinazione di informazioni commercialmente sensibili non costituisce un’anonimizzazione efficace.

La residenza riguarda anche l’ambiente di esecuzione. Inviare prompt a un endpoint regionale approvato non risolve il problema se tracce, indici vettoriali, log degli errori o code di revisione umana sono archiviati altrove. Esaminiamo l’intero percorso dei dati: acquisizione, file temporanei, recupero delle informazioni, inferenza, risultati degli strumenti, osservabilità, backup e accessi dell’assistenza.

Questa verifica produce percorsi consentiti, non un vincitore. Un modello locale può essere obbligatorio per un’attività, facoltativo per un’altra e inadatto per una terza. Le regole restringono la scelta; le evidenze la completano.

Seconda verifica: successo dell’attività, poi qualità

Nell’insieme ammissibile valutiamo prima il successo dell’attività: il flusso di lavoro ha raggiunto lo stato previsto? Per la ricerca può essere una risposta supportata da citazioni consultabili; per l’estrazione, un record valido rispetto allo schema e collegato ai passaggi della fonte; per un’azione operativa, un piano valido di simulazione senza modifiche, una modifica approvata e una verifica riuscita dello stato risultante.

Il successo dell’attività va oltre la qualità della risposta. Una risposta elegante che non può essere analizzata automaticamente, cita evidenze inaccessibili o richiama uno strumento vietato costituisce un’esecuzione fallita. Un risultato conciso può invece avere successo se completa il processo in modo affidabile.

Definiamo un set di valutazione a partire da attività rappresentative. Ogni caso contiene input, evidenze consentite, transizione di stato attesa, condizioni di fallimento vincolanti e griglia di valutazione. Il set deve coprire:

casi ordinari che rappresentano la maggior parte del volume;
casi limite vicini a una soglia delle regole o della qualità;
input mancanti, non aggiornati, duplicati o contraddittori;
guasti a strumenti e dipendenze;
tentativi di prompt injection o di attacco tramite contenuti non fidati;
casi che impongono astensione o passaggio al livello competente;
variazioni linguistiche o di formato, dove pertinenti.

Valutiamo i vincoli obbligatori prima delle preferenze soggettive. Validità dello schema, scelta corretta degli strumenti, rispetto delle autorizzazioni, sostegno delle citazioni e astensione obbligatoria hanno esito positivo o negativo. Completezza semantica, chiarezza e utilità si possono valutare con una griglia. Una prosa più curata non compensa un tasso inferiore di attività completate e verificate.

Le skill per agenti specifiche di dominio aiutano a stabilizzare questa valutazione perché procedure e controlli obbligatori sono rappresentati in artefatti espliciti, anziché essere riscoperti a ogni conversazione.

Terza verifica: token, latenza e costo

Ottimizziamo l’efficienza solo dopo che i percorsi soddisfano le soglie di successo e qualità. La misura pertinente è il costo per attività verificata, non il prezzo per token di input.

Un modello economico può costare di più se richiede nuovi tentativi, revisioni o correzioni a valle. Una prima risposta rapida può nascondere una latenza complessiva elevata se l’ambiente di esecuzione corregge ripetutamente risultati invalidi. Una finestra di contesto più ampia può incoraggiare caricamenti indiscriminati, aumentando costi e possibilità di errore.

Misuriamo:

Dimensione	Misura nell’ambiente di esecuzione
Successo	completamenti verificati per tentativo ammissibile
Qualità	accettazione al primo tentativo, gravità dei difetti e tasso di difetti sfuggiti ai controlli
Token	token di input, input in cache, output e nuovi tentativi per completamento verificato
Latenza	tempi mediani e nella coda della distribuzione dall’evento iniziale allo stato verificato
Costo	inferenza, recupero delle informazioni, strumenti, revisione e rilavorazione per completamento verificato
Stabilità	variazione delle prestazioni nel tempo, tra formati e classi di domanda

Gli indici normalizzati rendono leggibili i confronti interni senza suggerire una precisione falsa. Imposta il percorso approvato corrente a Baseline = 100 per il costo corretto per la qualità e la latenza complessiva. Un candidato è utile solo se l’indice di costo inferiore non nasconde un tasso di successo delle attività peggiore, un carico maggiore di eccezioni o più tempo di revisione. Conserviamo conteggi e definizioni sottostanti per l’audit anche quando la reportistica esterna usa valori normalizzati.

L’ottimizzazione diventa quindi mirata. La cache dei prompt può ridurre la ripetizione del contesto delle regole. Passaggi recuperati più brevi possono ridurre le distrazioni. Letture parallele tramite gli strumenti possono migliorare la latenza. Un modello più piccolo può gestire la classificazione, mentre un percorso più capace gestisce sintesi ambigue. Il codice deterministico può eliminare del tutto una chiamata di inferenza.

Instradare le attività, non gli utenti

L’instradamento statico per reparto spreca capacità e denaro. Una persona può chiedere una sintesi pubblica, un confronto riservato, una riconciliazione e una scrittura in produzione: classi di attività con requisiti diversi di ammissibilità, qualità e autorità.

L’instradamento si basa su una descrizione strutturata dell’attività:

task_type: extract | classify | synthesize | plan | act | verify
data_class: public | internal | confidential | restricted
residency: approved_regions
authority: read | recommend | dry_run | approved_write
evidence: source_ids and freshness requirements
output_contract: schema or rubric version
risk: consequence and reversibility
latency_budget: interactive | asynchronous | batch

Il sistema di instradamento deve essere il più deterministico possibile. Classe dei dati, residenza e autorità sono decisioni dettate dalle regole. Non devono dipendere da una valutazione del modello su quanto una richiesta «sembri sensibile». Un classificatore può aiutare nell’acquisizione, ma l’incertezza deve portare al percorso più sicuro o a una richiesta di chiarimento specifica.

Il modello viene poi scelto nel ramo consentito. Il percorso viene registrato insieme alle versioni delle regole, del modello, del prompt o della skill, agli identificativi delle evidenze recuperate, alle chiamate agli strumenti, ai risultati dei verificatori e allo stato finale. Questa registrazione rende diagnosticabili gli errori e riproducibili i confronti.

Perché i modelli locali richiedono un ambiente di esecuzione diverso

Spesso si parla di inferenza locale come se bastasse trasferire lo stesso prompt da un endpoint ospitato all’hardware locale. Raramente è così. I modelli locali possono offrire un forte controllo sulla privacy, costi marginali prevedibili, funzionamento offline e bassa latenza per attività circoscritte. Rispetto alle migliori alternative ospitate disponibili in un dato momento, possono però essere meno affidabili nel seguire istruzioni, scegliere strumenti, gestire contesti lunghi o mantenere coerenza multilingue.

La risposta corretta non è nascondere queste differenze, ma modificare l’ambiente di esecuzione.

Scomporre di più

Assegna al modello una trasformazione circoscritta alla volta. Separa selezione dei documenti, estrazione, classificazione, stesura e verifica. Ogni fase deve avere un contratto ristretto di input e output. La scomposizione riduce il numero di istruzioni simultanee e crea punti di controllo in cui verifiche deterministiche possono fermare la propagazione degli errori.

Un percorso locale può prima identificare le sezioni rilevanti, poi estrarre le affermazioni in uno schema, collegare ciascuna a un passaggio della fonte e infine redigere il testo usando soltanto quelle accettate. Richiede più orchestrazione di un unico grande prompt, ma è più facile da valutare e correggere.

Recuperare meno, ma meglio

Caricare un intero repository o una raccolta di documenti nel contesto non significa recuperare informazioni: trasferisce al modello il problema della selezione. I percorsi locali beneficiano di indici strutturati, filtri sui metadati, vincoli sull’aggiornamento dei dati e pacchetti di evidenze brevi. Il recupero deve restituire identificativi e passaggi delle fonti, così i controlli successivi possono verificare il fondamento della risposta.

Gli schemi pratici per costruire un assistente IA locale con recupero delle informazioni e ricerca web mostrano perché l’inferenza locale dipende da un livello di strumenti ed evidenze, oltre che dalla sola memoria del modello.

Verificare deterministicamente

Usa schemi, parser, elenchi di elementi consentiti, vincoli del database, calcoli, motori di regole e verifiche dello stato risultante quando possibile. Un modello può proporre una modifica; il codice deve confermare che i campi obbligatori esistano, gli identificativi siano risolvibili, i totali siano riconciliati, le autorizzazioni consentano l’azione e lo stato successivo corrisponda al piano approvato.

Per i controlli semantici non deterministici, usa una griglia e un percorso di revisione indipendente. Non chiedere alla stessa chiamata di generare, valutare e approvare il proprio risultato. Se usi un valutatore basato su un modello, calibralo sui giudizi umani e mantienilo fuori dal confine dell’autorità finale.

Sequenze a cascata, percorsi alternativi e astensione

Un sistema di instradamento utile non invia ogni attività ammissibile al modello più capace. Può usare una sequenza a cascata: partire dal percorso meno costoso che soddisfa già i criteri di accettazione della classe di attività, poi passare a un livello superiore in caso di errore osservabile.

I segnali per passare al livello superiore devono essere concreti: schema invalido dopo la correzione, evidenze mancanti, fonti discordanti, basso grado di confidenza calibrato, strumento indisponibile, limite delle regole o errore del verificatore. Il numero di token da solo non indica la qualità; neppure l’incertezza dichiarata dal modello, se tale dichiarazione non è stata calibrata per l’attività.

I percorsi alternativi devono mantenere la coerenza semantica. Se il percorso principale fallisce perché non soddisfa i requisiti di residenza, l’alternativa non può ignorarli. Se una chiamata a uno strumento non è disponibile, un percorso basato sulla sola chat non deve fingere che l’azione sia avvenuta. Se le evidenze non sono aggiornate, un modello più capace non può aggiornarle.

L’astensione è un esito positivo quando il contratto dell’attività richiede il passaggio al livello competente. Includiamo «rifiutato o inoltrato correttamente al livello competente» nelle metriche di successo delle attività. Altrimenti, la pressione a instradare il lavoro premia i sistemi che tentano di agire oltre le proprie evidenze o autorizzazioni.

Stato, versioni e riproducibilità

Modelli ed endpoint cambiano. Anche quando il nome del modello resta costante, il comportamento può variare con una nuova versione, la configurazione del servizio, il prompt di sistema, l’indice di recupero, la definizione degli strumenti o le regole. L’ambiente di esecuzione deve gestire le versioni dell’intero contratto di esecuzione.

Registriamo almeno:

versioni dell’attività e delle regole;
fornitore del modello, regione dell’endpoint e versione del modello;
versioni di prompt, skill e schemi degli strumenti;
query di recupero, ID delle fonti e timestamp di aggiornamento;
impostazioni di campionamento e timeout;
versioni e risultati dei verificatori;
eventi relativi a nuovi tentativi, percorsi alternativi e revisioni umane;
azione finale ed evidenze dello stato risultante.

La riproducibilità operativa deriva da input, configurazione, azioni esterne ed evidenze di verifica, non dalla conservazione indiscriminata della catena di ragionamento. Le tracce sensibili seguono le regole aziendali di minimizzazione e conservazione.

La disciplina procedurale descritta nell’ottimizzazione di un agente specifico per progetto è pertinente: spazi di lavoro persistenti e procedure riutilizzabili sono utili solo quando modifiche, concorrenza e modalità di guasto sono osservabili.

Un processo pratico di selezione

Usiamo un processo di selezione per fasi:

Definire le classi di attività. Separare estrazione, sintesi, pianificazione, azione e verifica, senza riunirle in un unico punteggio medio.
Applicare le verifiche di ammissibilità. Eliminare i percorsi che non soddisfano privacy, residenza, condizioni contrattuali o requisiti di autorità.
Costruire il set di valutazione. Includere casi rappresentativi, limite, avversariali e con passaggio obbligatorio al livello competente, usando evidenze fissate.
Provare i percorsi nell’ambiente di esecuzione reale. Includere recupero delle informazioni, strumenti, timeout, nuovi tentativi e verificatori.
Controllare i fallimenti vincolanti. Escludere i percorsi che violano i requisiti di schema, evidenze, autorizzazioni o astensione.
Valutare successo e qualità. Esaminare le prestazioni medie e la coda della distribuzione dei difetti gravi.
Misurare l’efficienza complessiva. Confrontare token, latenza, costo di inferenza, tempo di revisione, nuovi tentativi e rilavorazione per completamento verificato.
Avviare un progetto pilota in modalità ombra o in simulazione senza modifiche. Osservare le variazioni della domanda reale senza consentire scritture non verificate.
Approvare per classe di attività. Registrare percorso, limiti, alternativa e scadenza della decisione.
Rivalutare continuamente. Avviare una revisione in caso di modifiche ai modelli, derive, nuove classi di dati, eccezioni ripetute o variazioni rilevanti dei prezzi.

Il risultato è una politica di instradamento versionata, non una classifica permanente.

La regola decisionale

L’ordine delle decisioni è centrale per un instradamento responsabile dei modelli. Privacy, residenza e verifiche contrattuali stabiliscono ciò che è ammesso. Successo verificato delle attività e qualità stabiliscono ciò che funziona. Token, latenza e costo totale stabiliscono l’efficienza dei percorsi rimasti.

Invertire l’ordine produce errori prevedibili. Dare priorità ai costi invia attività sensibili a endpoint inammissibili o risultati scadenti in costosi cicli di revisione. Partire dal modello adatta i processi al fornitore preferito. Partire dai benchmark ottimizza attività che l’azienda potrebbe non svolgere.

Progettiamo l’ambiente di esecuzione affinché i modelli possano cambiare senza perdere regole, stato o evidenze. Modelli ospitati, modelli locali e servizi deterministici hanno ciascuno un ruolo. La scelta giusta è il sistema ammissibile più piccolo che completa l’attività definita, rispetta la soglia di qualità e ne prova il risultato.

Approfondimenti correlati

Architettura di riferimento per un livello operativo IA basato su thread — instradamento, stato tipizzato, autorizzazioni, esecuzione e verifica
Creare skill per agenti IA per flussi di lavoro aziendali specifici di dominio — rendere esplicite le procedure e i controlli specialistici
Costruire un assistente IA locale con ricerca web: configurazione MCP + Ollama — schema pratico per inferenza locale, recupero delle informazioni e strumenti