AI nella logistica: dietro le quinte di Shipment Exception Commander

Quando si parla di AI nella logistica, le anomalie di spedizione non sono difficili da gestire perché manchino le alternative. Il vero problema è che le evidenze arrivano con livelli di affidabilità diversi, i preventivi di recupero scadono, i costi superano le soglie di approvazione e un nuovo tentativo affrettato può generare una seconda prenotazione anche se la prima è già andata a buon fine.

Shipment Exception Commander è un’applicazione open source di riferimento basata su Claude Managed Agents e progettata proprio per questo delicato passaggio decisionale. Analizza una singola eccezione sintetica, assegna un punteggio meccanico a ogni opzione di recupero, delega a un verificatore indipendente la contestazione del rischio, mostra a una persona l’azione esatta e consente una sola mutazione idempotente nella sandbox dopo l’approvazione nativa.

AI nella logistica: scoring deterministico prima del giudizio del modello

Il coordinatore non inventa mai le tariffe né scambia il testo libero per una policy. Il tool server-side di sola lettura shipment_intelligence espone tre casi sintetici e calcola i punteggi delle opzioni con una formula fissa: 50 punti se la promessa viene rispettata, 20 per la copertura dell’inventario, 20 per l’efficienza dei costi rispetto al tetto assoluto e 10 per il livello di affidabilità. Ogni opzione include versione e scadenza del preventivo, ETA, numero di unità protette e costo incrementale in USD.

Nel caso dimostrativo principale, SCX-2026-071, sono stati messi a confronto tre scenari decisionali realistici: un recupero economico via mare che non rispettava la promessa, un trasporto interamente aereo oltre il tetto assoluto di spesa e una soluzione urgente frazionata via aerea che proteggeva tutte le 240 unità impegnate al costo di $4,200. L’opzione frazionata ha ottenuto 91 punti ed è rimasta entro il limite di $5,000 fissato dall’operatore. Il punteggio rende riproducibile la raccomandazione; a Claude spetta raccogliere le evidenze, mettere in discussione le ipotesi e illustrare il compromesso.

Gestione delle eccezioni nelle spedizioni: le fonti non attendibili non autorizzano azioni

Una nota del vettore contiene deliberatamente un testo simile a un’istruzione, che invita l’agente a ignorare la policy di approvazione e prenotare l’opzione premium. Il workflow contrassegna la nota come non attendibile, la conserva come evidenza e dichiara esplicitamente che non verrà trattata come direttiva. Le regole provengono dal catalogo sintetico versionato e dall’adapter, mai dal testo della spedizione o dall’output di un tool.

Il coordinatore, inoltre, non dispone di memoria scrivibile tra sessioni, vault, integrazione MCP o accesso in uscita alla rete. read, glob e grep sono le sole eccezioni limitate con approvazione automatica. Bash e la scrittura dei deliverable sono impostati su always_ask; modifica, recupero dal web e ricerca sul web restano disabilitati. L’unica mutazione canonica dello stato è il comando execute dell’adapter.

Agenti AI per la logistica: la raccomandazione passa al verificatore

Prima di ogni richiesta di esecuzione, il coordinatore Opus affida il recupero proposto a un verificatore Haiku con un perimetro ristretto. Nel test principale, il verificatore ha restituito NEEDS_CHANGES: non poteva stabilire se il preventivo Q-071-v4 fosse ancora valido, né se capacità e supplementi fossero definitivi. Il coordinatore non ha ignorato l’obiezione. Ha richiamato il validatore deterministico della proposta, che ha ricontrollato l’orologio sintetico, la scadenza del preventivo, la versione della policy, la fascia di spesa e la versione di stato prevista. Solo il risultato autorevole ready_for_human_approval ha fatto passare lo stato complessivo a «pronto».

Il riepilogo per l’approvazione ha quindi esposto gli ID del caso e dell’opzione, la spesa esatta di $4,200, il vecchio e il nuovo ETA, l’impatto sulla promessa al cliente, le 240 unità protette, la scadenza del preventivo, le versioni di policy e stato, il punteggio, lo storico del verificatore, le alternative scartate, la chiave di idempotenza stabile, i campi attesi nella ricevuta e il comportamento previsto in caso di rifiuto o errore.

Un rifiuto non produce alcuna mutazione

La prima scheda di approvazione nativa è stata rifiutata deliberatamente. Non è stato eseguito alcun comando capace di modificare lo stato, che è rimasto detected alla versione 3; non esisteva alcuna ricevuta e la chiave di idempotenza era ancora inutilizzata. L’agente non ha cambiato tool, alterato il comando o creato una nuova chiave.

Su richiesta esplicita dell’operatore, la stessa azione canonica è stata presentata di nuovo. Questa volta è stata autorizzata. Sul confine della mutazione, l’adapter ha ricontrollato lo stato alla versione 3, la validità del preventivo, la policy, la fascia di approvazione e il tetto assoluto di $10,000. L’azione è stata eseguita esattamente una volta, facendo passare il caso da detected versione 3 a resolved versione 4 e restituendo la ricevuta rcpt_37105a2da411aee0391c con il riferimento di prenotazione SBX-56DFC3291972.

Esecuzione replay-safe, entro confini dichiarati

L’adapter sintetico gestisce una chiave stabile, SCX-2026-071:OPT-071-B:v3, un lock a livello di sistema operativo, l’ispezione dello stato canonico e un registro delle ricevute. Le chiamate duplicate con lo stesso intento restituiscono la ricevuta esistente; un intento in conflitto associato alla stessa chiave fallisce; versioni obsolete, esecuzioni simultanee e possibili scritture parziali richiedono un’ispezione, non un nuovo tentativo alla cieca.

Queste protezioni vengono descritte intenzionalmente entro il loro perimetro reale: lock, stato e registro delle ricevute sono file locali alla sessione in una singola sandbox Managed Agents. Non costituiscono una garanzia distribuita pronta per la produzione. Un vero adapter per un vettore o un TMS avrebbe bisogno di uno storage transazionale condiviso e di un confine di idempotenza nel sistema a valle.

Il valutatore finale ha verificato le evidenze

La sessione ha scritto tre artefatti in /mnt/session/outputs/: un pacchetto di recupero leggibile, un record di audit strutturato e la ricevuta di esecuzione grezza. Un outcome di Managed Agents ha confrontato in modo indipendente questi file con il catalogo, il sorgente dell’adapter, lo stato canonico, lo storico delle approvazioni e il registro delle ricevute. Prima di restituire satisfied, ha richiesto correzioni relative alla comunicazione della scadenza del preventivo, al comportamento esplicito in caso di errore, al manifesto dei deliverable e al limite dovuto allo stato locale alla sessione.

Il pacchetto di recupero è stato poi scaricato tramite il proxy dei file dell’applicazione. Il relativo SHA-256 è 30c8ad1d0d13cf7ad4b7070e67370ea270562c5e4ef44dfa503e3124180bd40b. La sessione capability è sesn_01CcQjCVoWvNQ7VJLFbuDJxh; l’outcome è outc_01GoD4rsLMh93iQNfAUw63KW.

L’esecuzione live dell’outcome ha fatto emergere anche una lacuna nell’interfaccia: i thread figli del valutatore possono richiedere un’approvazione mentre la sessione principale resta inattiva. La release ora ricostruisce le schede di approvazione in sospeso sia dagli eventi requires_action del thread principale sia dagli eventi evaluated_permission: ask dei thread figli, le rimuove quando arriva una conferma o un risultato e impedisce che un replay faccia ricomparire richieste già risolte. Inoltre, inoltra il session_thread_id del valutatore attraverso una allowlist limitata nel browser e verifica quella route rispetto all’esatto evento del tool che l’ha originata prima di trasmettere la decisione.

Una sessione di prova Sonnet configurata separatamente, sesn_01BvSf33BLBbN86w5oDb3BkQ, ha esercitato il percorso corretto. Il tool del valutatore ripubblicato tra thread, sevt_013VnmofY8ytk6QwgDtNSYoq, riportava il thread sthr_018HMgpidoN86Qp4iGLZt1q3; l’interfaccia ha generato la conferma sevt_016ZFv5TdBPKNyEPThzGT36Q con gli stessi ID di tool e thread, il server l’ha accettata e il valutatore ha ripreso l’esecuzione chiedendo il controllo successivo. La prova circoscritta è stata poi interrotta intenzionalmente per non sostenere il costo di ulteriori iterazioni irrilevanti; l’outcome principale della spedizione è rimasto soddisfatto.

Opus in prima linea, Sonnet per la validazione, Haiku per la verifica

Il coordinatore predisposto resta claude-opus-5. Per rendere economicamente sostenibile una validazione a pagamento ripetibile, le sessioni locali possono sostituire esplicitamente solo il modello del coordinatore con claude-sonnet-5; qualsiasi altra sostituzione a runtime fallisce in modo sicuro. Il verificatore indipendente usa claude-haiku-4-5. La sessione smoke a pagamento sesn_01RTs3wLV41odV9p92eWtrHV ha usato Sonnet e restituito la risposta esatta SMOKE OK.

La suite di test per la produzione resta intenzionalmente isolata dalle credenziali anche quando uno sviluppatore dispone di un file .env.local configurato. Dimostra che un deployment nuovo non espone alcun campo per la chiave nel browser, non invia traffico ad Anthropic, riporta configured: false e restituisce 503 dalle route di fatturazione.

Automazione logistica: un riferimento pubblico fail-closed

Il riferimento pubblico su Vercel non contiene chiavi Anthropic né ID di risorse Managed Agents. La landing page e /api/agent/health restano disponibili, mentre la creazione delle sessioni fallisce in modo sicuro. Chi adotta il progetto configura l’agente e l’ambiente nel proprio account Anthropic; qualsiasi istanza configurata deve essere protetta da accessi non autorizzati prima di poter essere raggiunta da altri utenti.

Ogni caso, vettore, preventivo, riferimento di prenotazione, transizione di stato e ricevuta del progetto è sintetico. L’applicazione dimostra un modello di controllo operativo, non una vera integrazione con un vettore.

Evidenze della release

• Repository: dvnc-labs/shipment-exception-commander
• Release: v0.1.0
• CI: esecuzione della release riuscita
• Commit: 1db0329
• Deployment: shipment-exception-commander.vercel.app
• Stato: controllo fail-closed dell’agente

Shipment Exception Commander ha un perimetro volutamente più ristretto di un copilota per la logistica. Si assume una sola promessa verificabile: formulare raccomandazioni sulla base di evidenze versionate, metterle alla prova, chiedere a una persona di approvare l’azione esatta, applicare una sola mutazione e lasciare prove sufficienti per ricostruire quanto accaduto.