Catalogo modelli e route degli agenti

Agents → Models è disponibile all'amministratore di piattaforma. Una route associa attività, ambito e lingua a un modello e ai suoi limiti di esecuzione. Un elemento nel catalogo rende il modello selezionabile; non prova l'accesso al provider e non avvia chiamate.

Percorso e scelte iniziali

Percorso: Amministrazione → Impostazioni globali → Agents → Models (/agents?tab=models). Prepara identificativo del modello, attività da servire e ambito; la credenziale del provider deve essere disponibile nell'ambiente indicato dal riferimento. Per la route FIA serve anche una configurazione runtime di base da cui creare la bozza.

Obiettivo	Dove intervenire	Cosa cambia
Rendere selezionabile un nuovo modello	Gestisci modelli → Aggiungi modello	Aggiunge il catalogo; le route esistenti restano quelle salvate.
Cambiare il modello di un'attività ordinaria	Configura nella riga dell'attività	Modifica la route mostrata e ne verifica la proiezione effettiva.
Creare un'eccezione per un tenant	Route avanzate, con tenant esplicito	Può prevalere sulla route globale per quel tenant. Controllare l'ambito prima di salvare.
Cambiare Investigazione finding	Configura nel binding dedicato FIA	Crea una bozza; l'effetto arriva con Apply dopo il drain dei task.
Limitare le correzioni editoriali	Modifica limiti del flusso	Cambia una policy distinta dal modello, soltanto per nuove catene.
Ritirare un modello dal catalogo	Ritira	Impedisce nuove assegnazioni; non è una migrazione automatica delle route che già lo usano.

Catalogo modelli

Campo	Regola	Effetto
Provider	Nel form di creazione: OpenAI	Provider del modello; non modificabile dopo la creazione.
ID API (model)	Stringa obbligatoria	Identificativo esatto richiesto al provider, non nome commerciale libero; non modificabile dopo creazione.
Nome (displayName)	Stringa obbligatoria	Etichetta nel selettore del portale.
Registra nuova revisione tariffa	Booleano, spento inizialmente	Abilita i campi della tariffa amministrativa.
Input USD / milione	Decimale non negativo, obbligatorio quando si registra una tariffa	Costo dichiarato per un milione di token input. Usare il punto decimale.
Output USD / milione	Come input	Costo dichiarato per un milione di token output.
Cache read / cache write USD / milione	Decimali non negativi facoltativi	Tariffe dichiarate di lettura e scrittura cache. Vuoto non significa costo zero verificato.
Fonte dichiarata	Obbligatoria per la tariffa	Provenienza amministrativa del valore.
Data effettiva	Obbligatoria per la tariffa, formato YYYY-MM-DD	Data di decorrenza del riferimento registrato.

Le tariffe inserite sono dichiarazioni dell'amministratore, non prezzi verificati in tempo reale presso il provider. Lo stato del modello è draft, active o retired; i nuovi modelli creati dal form sono attivi. Solo gli attivi sono assegnabili a nuove route.

Ritira impedisce nuove assegnazioni conservando i riferimenti. Elimina è disponibile per una bozza mai usata e senza riferimenti. Il dettaglio mostra impieghi come primario, fallback e binding runtime, capacità dichiarate, livelli di ragionamento e formati di output; “non verificato” non equivale a “non supportato”.

Aggiungere un modello e assegnarlo

1. In Configurazione per attività apri Gestisci modelli, poi Aggiungi modello.
2. Compila provider, ID esatto e nome. Se registri una tariffa, abilita la relativa revisione e inserisci importi, fonte e data: non usare un importo ipotetico per eliminare l'indicazione “non disponibile”.
3. Salva e verifica che la rilettura mostri il modello attivo. In caso di “salvato, verifica incompleta”, usa Riprova verifica.
4. Torna alla tabella attività e controlla l'ambito selezionato. Apri Configura oppure Aggiungi route sulla riga corretta; per un binding non esposto in tabella usa Route avanzate.
5. Seleziona il modello, ragionamento e gli eventuali dettagli tecnici. Controlla attività, lingua, tenant, output e credenziale prima di salvare.
6. Premi Salva modifiche e verifica modello effettivo, origine e stato nella riga dell'attività. Una route salvata ma non selezionata richiede di controllare precedenza, ambito e abilitazione.
7. Quando l'attività viene eseguita nel normale flusso, controlla nella run modello e risultato. Il salvataggio non prova accesso, capacità o consumo effettivo presso il provider.

Attività e ambito

Agente	Attività	Vincoli
triage	alert_triage	Triage degli alert; ambito globale o tenant.
policy	policy_recommendation	Raccomandazioni di policy; ambito globale o tenant.
optimization	tenant_log_optimization	Ottimizzazione log; ambito globale o tenant.
cluster	cluster_enrichment	Arricchimento cluster; ambito globale o tenant.
editorial	editorial_generation	Globale; IT per originale canonico, EN per traduzione.
editorial	editorial_validation	Globale; lingua tecnica della route EN. La revisione editoriale è sul contenuto canonico italiano.
ioc	ioc_discovery	Globale; output EN.
investigation	incident_soc_investigation	JSON schema, senza fallback aggiuntivo; l'attività esposta è in italiano.
investigation	finding_investigation	Configurazione tramite workflow dedicato, descritto sotto.

Il campo Ambito tenant vuoto indica piattaforma. Per attività editoriali e IOC il campo è disabilitato perché il binding è globale. Il router per le attività tenant preferisce una route tenant abilitata a una globale; la proiezione effettiva del portale mostra quella risultante. Non confondere priorità con autorizzazione all'uso del modello.

Parametri della route

Ingrandisci immagine

Schermata di configurazione; nessuna route o credenziale è stata modificata. Stage, 10 novembre 2026. Dati identificativi oscurati.

Instradamento dei modelli

521 × 625 px · Scorri per esplorare l’immagine senza ridimensionamento. Premi Esc per chiudere.

Il pannello Configura distingue configurazione corrente, scelte di modello/ragionamento e confronto Prima → dopo. Verifica attività, lingua e ambito nella parte superiore prima di salvare; i campi avanzati possono incidere su credenziali e fallback.

I valori iniziali sono quelli del form di creazione, non necessariamente quelli delle route esistenti.

Campo	Valori / iniziale UI	Comportamento
Modello	Modello attivo del catalogo	Seleziona insieme provider e identificativo. Una route esistente può mostrare il proprio modello storico.
Ragionamento	automatic, none, minimal, low, medium, high, xhigh, max; iniziale automatic	Automatico applica la policy per fase o il default del provider per modelli non profilati. Un override vale per tutte le fasi della route e può essere rifiutato dal provider durante l'esecuzione.
Agente / Attività	Coppie della tabella precedente	La coppia deve essere coerente; non modificabile quando si modifica una route esistente o un binding dedicato.
Lingua output	IT / EN	Identità del binding; non un filtro della lingua dell'interfaccia.
Priorità	UI 0–10.000; iniziale 100	Tra route candidate dello stesso ambito precede il numero più basso; a parità il selettore ordina per aggiornamento più recente. Verificare la route effettiva dopo il salvataggio.
Formato output	json_schema / json_object; iniziale json_schema	Contratto di output strutturato. SOC richiede json_schema.
Token output massimi	256–12.000, facoltativo	Budget di output della route; un campo vuoto lascia al runtime la scelta prevista. Non è il budget di token input.
Timeout ms	1.000–120.000; iniziale 30.000	Limite temporale della richiesta secondo il runtime.
Temperatura	0–1, facoltativa	Parametro di generazione, soggetto al supporto del modello.
Round strumenti	UI 0–20; iniziale 4	Limite dei passaggi con strumenti per i workflow che lo utilizzano.
Modello fallback	Facoltativo	Modello alternativo con provider e credenziale propri; non disponibile per il workflow SOC, né ammesso per l'investigazione Finding.
Ragionamento fallback	Stesse opzioni del primario	Richiede un modello fallback quando impostato esplicitamente.
Abilitata	Switch; iniziale acceso	Governa disponibilità della route al selettore.

Credenziali primarie e fallback

Il form gestisce riferimenti, non il contenuto delle chiavi. Per OpenAI il riferimento ammesso dalla UI è env:OC_OPENAI_API_KEY.

Azione	Significato
Mantieni	Conserva un riferimento già configurato; non è valida come sostituto di una credenziale mancante.
Sostituisci	Richiede il nuovo riferimento esplicito ammesso. Non incollare la chiave segreta nel campo.
Nessuna credenziale / clear	Rimuove il riferimento quando si passa a un provider che non lo usa o si elimina il fallback.

Primario e fallback hanno controlli separati. Togliere il modello fallback non deve lasciare un riferimento credenziale incompatibile: scegli l'azione di rimozione richiesta dalla UI.

Salvataggio, conflitti e disabilitazione

Salva verifica i campi, scrive contro la versione letta e rilegge elenco e proiezione effettiva. Se compare “modifica salvata; verifica non completata”, usa Riprova verifica: non inviare nuovamente la modifica. Un conflitto 409 conserva la bozza e consente il confronto/merge con la versione remota; risolvi i campi in conflitto prima di salvare.

Per disabilitare una route, il portale prepara una proiezione dell'effetto: confronta il binding corrente con quello che resterebbe dopo l'esclusione. Un'altra route potrebbe prendere il suo posto; disabilitare una riga non equivale sempre a disattivare l'attività.

Modello dell'investigazione Finding

Il binding FIA mantiene generazione, hash runtime e route in un flusso dedicato:

1. Apri Investigazione finding e scegli un modello attivo dello stesso provider della route di base.
2. Imposta ragionamento automatico o override.
3. Salva bozza: la bozza è associata a generazione/hash e versione route correnti.
4. Verifica che i task precedenti siano terminati, quindi Applica esplicitamente la bozza.
5. Rileggi il modello effettivo e la nuova generazione.

FINDING_RUNTIME_DRAIN_REQUIRED significa che restano task non terminali: la bozza rimane salvata e va applicata dopo la loro conclusione. Una bozza basata su una generazione superata non è applicabile; confronta la nuova versione e crea una scelta coerente. Se l'applicazione è stata inviata ma la rilettura fallisce, ripeti solo la verifica.

L'attivazione del modello non supera i gate globali, la coorte FIA o l'abilitazione di egress del tenant per l'analisi incidenti.

Risolvere gli errori di configurazione

Sintomo	Controllo
Modello assente nel selettore	Verifica che esista e sia attivo nel catalogo; nel workflow FIA controlla anche la corrispondenza del provider di base.
Riferimento segreto rifiutato	Usa il riferimento ammesso e l'azione keep/replace/clear coerente con provider e presenza della credenziale; non inserire il valore della chiave.
Fallback o formato rifiutato per Investigazione SOC	Rimuovi il fallback e scegli json_schema.
Modifica salvata ma modello effettivo diverso	Controlla ambito tenant/globale, priorità, abilitazione e origine risolta.
Conflitto remoto	Confronta la bozza con la versione corrente e risolvi i campi indicati; non forzare un secondo invio della vecchia versione.
FIA richiede drain	Attendi i task non terminali e applica esplicitamente una bozza ancora coerente con la generazione attiva.

Verifica sorgente: catalogo, pannello route, binding, modello FIA, controller route e selettore server; snapshot del 10 novembre 2026. Nessuna chiamata AI è stata avviata per documentare questi campi.