Progettare software comprensibile anche dagli agenti AI

Integrare un agente AI in un processo software può sembrare relativamente semplice.

Si sceglie un modello, si prepara un prompt, si espongono alcuni strumenti e si permette all’agente di leggere informazioni o avviare operazioni.

Una prima dimostrazione può funzionare in poco tempo.

L’agente consulta un documento, analizza un repository, genera una query, compila una risposta oppure utilizza un’API per modificare un dato.

Il risultato iniziale è spesso convincente perché mostra una capacità nuova: il software non si limita più a eseguire una sequenza definita in anticipo, ma può interpretare una richiesta e scegliere quali azioni compiere.

Il problema emerge quando quella dimostrazione deve diventare parte di un processo reale.

A quel punto compaiono domande meno spettacolari, ma molto più importanti:

• quali informazioni può utilizzare l’agente;
• come riconosce quelle corrette;
• quali operazioni può eseguire;
• con quali permessi;
• come comprende lo stato corrente del sistema;
• cosa accade se sceglie lo strumento sbagliato;
• come vengono verificati i risultati;
• chi può ricostruire ciò che è avvenuto;
• quando deve fermarsi e chiedere un intervento umano.

Un agente può essere tecnicamente capace e produrre comunque risultati poco affidabili se il sistema che lo circonda è ambiguo.

Per questo l’agent readiness non dipende soltanto dalla qualità del modello.

Dipende dalla capacità del software e dell’organizzazione di rendere espliciti il contesto, i contratti, i permessi, lo stato e le procedure operative.

In altre parole, un sistema comprensibile per un agente deve essere prima di tutto un sistema progettato per essere compreso.

Le persone che lavorano a lungo su un’applicazione accumulano una grande quantità di conoscenza non documentata.

Sanno, per esempio:

• quale servizio possiede un determinato dato;
• quali tabelle non devono essere modificate direttamente;
• quali procedure sono formalmente disponibili ma non più utilizzate;
• quali errori possono essere ignorati;
• quali ambienti contengono dati sensibili;
• quale ordine seguire durante un rilascio;
• chi coinvolgere quando un processo fallisce;
• quali eccezioni derivano da decisioni storiche.

Queste informazioni raramente si trovano tutte nello stesso posto.

Una parte vive nel codice, una nella documentazione, una nei ticket, una nelle conversazioni e una nella memoria delle persone.

Un agente non possiede automaticamente questo contesto.

Può leggere ciò che gli viene fornito, usare gli strumenti disponibili e inferire alcune relazioni. Non può però sapere con certezza quali convenzioni siano ancora valide o quali comportamenti impliciti siano importanti.

Se chiediamo a un agente di “aggiornare il cliente nel gestionale”, la richiesta può nascondere molte decisioni:

• quale gestionale;
• quale cliente;
• identificato attraverso quale campo;
• quali dati devono essere aggiornati;
• quale sistema rappresenta la fonte autorevole;
• se la modifica deve propagarsi altrove;
• quali controlli devono essere eseguiti;
• se è necessaria un’approvazione;
• come verificare che l’operazione sia riuscita.

Per una persona esperta del processo, alcune risposte possono sembrare ovvie.

Per l’agente, ciò che non è esplicito deve essere dedotto. E ogni deduzione introduce incertezza.

Quando un agente produce un risultato errato, è naturale attribuire il problema al modello.

A volte è corretto. Il modello può interpretare male una richiesta, ignorare un vincolo o generare informazioni non attendibili.

In molti casi, però, il problema si trova nell’ambiente in cui gli è stato chiesto di operare.

L’agente può aver ricevuto:

• documentazione incompleta;
• strumenti con descrizioni ambigue;
• permessi troppo estesi;
• dati senza indicazione della provenienza;
• procedure non aggiornate;
• output difficili da verificare;
• errori tecnici privi di contesto;
• obiettivi generici;
• criteri di completamento non definiti.

Migliorare il prompt può attenuare alcuni problemi, ma non sostituisce la progettazione del sistema.

Un prompt molto dettagliato non risolve un’API incoerente. Non definisce la fonte autorevole di un dato. Non impedisce a uno strumento pericoloso di eseguire un’operazione distruttiva. Non rende verificabile un processo che non registra il proprio stato.

Considero quindi l’agent readiness una proprietà distribuita.

Dipende contemporaneamente da:

• qualità e accessibilità del contesto;
• chiarezza dei contratti;
• progettazione degli strumenti;
• gestione dei permessi;
• osservabilità;
• possibilità di verifica;
• procedure di escalation;
• supervisione umana.

Il modello è soltanto uno dei componenti.

Alcuni problemi diventano visibili già durante le prime prove.

Se ogni attività richiede un prompt molto lungo che ricostruisce architettura, regole, convenzioni e vincoli, il contesto non è realmente disponibile all’agente.

Il prompt sta compensando una mancanza strutturale.

Una certa quantità di istruzioni sarà sempre necessaria. Il problema emerge quando le informazioni essenziali devono essere copiate manualmente per ogni richiesta.

Questo approccio produce:

• duplicazioni;
• istruzioni incoerenti;
• documentazione difficile da aggiornare;
• dipendenza dalla persona che prepara il prompt;
• risultati differenti per attività simili.

Il contesto stabile dovrebbe vivere vicino al sistema e poter essere recuperato in modo controllato.

Il prompt dovrebbe descrivere soprattutto l’obiettivo specifico, non ricostruire ogni volta l’intera organizzazione.

Uno strumento chiamato execute_query, run_command o update_record può essere molto potente.

Può anche essere troppo ambiguo.

L’agente deve decidere autonomamente:

• quale comando generare;
• quali dati coinvolgere;
• quali controlli eseguire;
• come interpretare il risultato;
• quali conseguenze aspettarsi.

Più uno strumento è generico, più la correttezza dipende dalla capacità dell’agente di ricostruire vincoli non espressi.

In molti contesti è preferibile esporre operazioni più specifiche, come:

• get_customer_by_external_id;
• preview_order_update;
• create_support_draft;
• list_failed_synchronizations;
• retry_sync_item;
• request_deployment_approval.

Questi strumenti incorporano parte del contratto operativo e riducono lo spazio delle azioni possibili.

Un agente può produrre una risposta plausibile senza aver completato realmente il processo.

Può modificare un file senza eseguire i test. Può inviare una richiesta senza verificarne l’esito. Può generare una query corretta sintatticamente, ma non controllare i dati restituiti.

Se il sistema non definisce criteri di completamento, l’agente tende a fermarsi quando il risultato appare ragionevole.

Per un’attività tecnica, invece, il completamento può richiedere:

• validazione dell’input;
• esecuzione dell’operazione;
• controllo del risultato;
• esecuzione dei test;
• confronto con lo stato precedente;
• registrazione delle modifiche;
• approvazione umana.

Senza una definizione esplicita di “fatto”, l’output dell’agente rimane difficile da valutare.

Durante una demo è comune fornire all’agente credenziali ampie per evitare ostacoli.

In un processo reale, questa scelta rende difficile limitare l’impatto di un errore.

Un agente che può leggere e modificare qualsiasi risorsa non è necessariamente più utile. È semplicemente più difficile da controllare.

I permessi dovrebbero riflettere l’attività specifica:

• sola lettura quando è sufficiente;
• accesso limitato a determinate risorse;
• operazioni distruttive escluse;
• approvazione per le modifiche critiche;
• credenziali separate per ambiente;
• durata limitata delle autorizzazioni.

Un agente dovrebbe poter fare ciò che serve, non tutto ciò che tecnicamente è possibile.

Quando un agente utilizza più strumenti, è importante poter ricostruire almeno:

• quale obiettivo ha ricevuto;
• quali informazioni ha consultato;
• quali strumenti ha utilizzato;
• con quali parametri;
• quali risultati ha ottenuto;
• quali modifiche ha proposto o applicato;
• quali controlli sono stati eseguiti;
• dove è intervenuta una persona.

Non è necessario registrare ogni dettaglio interno del modello.

È però necessario conservare una traccia operativa sufficiente a comprendere il comportamento del sistema.

Se un risultato non può essere ricostruito, diventa difficile correggere un errore, migliorare il workflow o attribuire responsabilità.

Fornire più informazioni non garantisce risultati migliori.

Un agente può ricevere una grande quantità di documenti e trovare comunque difficile individuare quelli rilevanti.

Il problema non è soltanto la disponibilità del contesto, ma la sua qualità.

Un contesto utile dovrebbe essere:

• pertinente;
• aggiornato;
• attribuito a una fonte;
• coerente con l’ambiente corrente;
• sufficientemente specifico;
• accessibile al momento giusto;
• distinguibile dalle informazioni storiche o obsolete.

Supponiamo che un agente debba modificare un servizio.

Potrebbe aver bisogno di:

• descrizione del dominio;
• repository corretto;
• convenzioni di sviluppo;
• contratti API;
• istruzioni per i test;
• dipendenze;
• decisioni architetturali;
• procedure di rilascio;
• vincoli di sicurezza.

Se questi materiali esistono ma contengono versioni contraddittorie, l’agente deve scegliere autonomamente quale seguire.

La quantità di informazioni aumenta, ma aumenta anche l’ambiguità.

È utile distinguere tra informazioni relativamente stabili e informazioni legate alla singola esecuzione.

Il contesto stabile può comprendere:

• architettura;
• responsabilità dei servizi;
• convenzioni;
• modelli dati;
• regole di sicurezza;
• procedure standard.

Il contesto operativo può comprendere:

• ticket corrente;
• stato dell’ambiente;
• versione distribuita;
• errori recenti;
• dati coinvolti;
• approvazioni disponibili.

Questa separazione rende più semplice aggiornare le informazioni e fornire all’agente soltanto ciò che serve.

Un’informazione senza fonte è difficile da valutare.

L’agente dovrebbe poter distinguere, per esempio, tra:

• documentazione ufficiale;
• commento in un ticket;
• output di un sistema;
• ipotesi generata durante l’analisi;
• dato aggiornato in tempo reale;
• documento storico.

La provenienza aiuta a stabilire il livello di affidabilità e a gestire eventuali conflitti.

La documentazione obsoleta è pericolosa perché appare autorevole pur descrivendo un sistema che non esiste più.

Per ridurre questo rischio sono utili:

• data dell’ultimo aggiornamento;
• proprietario del documento;
• versione del sistema a cui si riferisce;
• collegamento al codice o al contratto;
• stato esplicito di validità;
• procedure per segnalare incongruenze.

La manutenzione del contesto diventa quindi una parte dell’infrastruttura dell’agente.

Un agente interagisce con il software attraverso strumenti.

Uno strumento può essere una funzione, un endpoint, un comando, una query predefinita o un workflow.

Per essere utilizzabile in modo affidabile, dovrebbe avere un contratto chiaro.

Nome dello strumento
    ↓
Scopo
    ↓
Input ammessi
    ↓
Precondizioni
    ↓
Effetti
    ↓
Output
    ↓
Errori possibili

Il nome dovrebbe esprimere l’operazione dal punto di vista del dominio.

update_data comunica poco.

update_customer_shipping_address rende più evidente:

• quale entità viene modificata;
• quale parte dell’entità;
• quale effetto aspettarsi.

Nomi più specifici aiutano l’agente a scegliere lo strumento corretto e rendono più leggibile la traccia delle operazioni.

Gli input dovrebbero essere strutturati e, quando possibile, vincolati.

Invece di accettare una stringa generica, uno strumento può richiedere:

• identificatore del cliente;
• campo da modificare;
• nuovo valore;
• motivazione;
• riferimento alla richiesta;
• modalità di esecuzione.

La validazione riduce gli errori prima che l’operazione raggiunga il sistema destinatario.

Uno strumento dovrebbe chiarire se:

• legge dati;
• prepara una proposta;
• modifica uno stato;
• invia una comunicazione;
• crea una risorsa;
• avvia un processo asincrono;
• esegue un’azione irreversibile.

Questa distinzione è importante per applicare permessi, approvazioni e controlli differenti.

Un messaggio come operation failed fornisce poche informazioni.

È più utile distinguere tra:

• input non valido;
• risorsa non trovata;
• conflitto con lo stato corrente;
• autorizzazione insufficiente;
• dipendenza non disponibile;
• operazione già eseguita;
• errore temporaneo;
• intervento umano necessario.

L’agente può reagire correttamente soltanto se il sistema rende comprensibile la natura del fallimento.

Una delle decisioni principali riguarda il livello al quale esporre il sistema.

Un agente potrebbe ricevere accesso diretto al database, alla shell o a un’API amministrativa.

Questo offre grande flessibilità, ma trasferisce all’agente molte responsabilità:

• conoscere lo schema interno;
• costruire operazioni corrette;
• evitare modifiche pericolose;
• rispettare vincoli non applicati tecnicamente;
• comprendere gli effetti indiretti.

Un’alternativa consiste nell’esporre capacità più delimitate.

Accesso generico
Database → qualsiasi query

Capacità delimitata
Servizio clienti → recupera cliente
                 → mostra ordini aperti
                 → prepara correzione
                 → richiede approvazione
                 → applica modifica

La seconda soluzione può sembrare meno potente, ma è spesso più affidabile.

Le capacità delimitate:

• riducono l’ambiguità;
• incorporano controlli;
• semplificano i permessi;
• rendono più chiari gli audit;
• permettono test più mirati;
• limitano l’impatto degli errori.

L’obiettivo non dovrebbe essere offrire all’agente il massimo numero di possibilità.

Dovrebbe essere offrirgli il minimo insieme di capacità sufficiente a completare il processo.

Non tutte le attività devono essere automatizzate allo stesso livello.

Una distinzione utile è quella tra:

1. raccolta delle informazioni;
2. elaborazione di una proposta;
3. applicazione della modifica.

Osservazione
    ↓
Proposta
    ↓
Verifica
    ↓
Esecuzione

Un agente può essere autorizzato a leggere dati e preparare una soluzione senza poterla applicare direttamente.

Questo schema è utile quando:

• l’operazione ha conseguenze economiche;
• coinvolge dati personali;
• modifica sistemi di produzione;
• invia comunicazioni esterne;
• produce effetti difficili da annullare;
• il processo è ancora in fase sperimentale.

L’agente raccoglie informazioni e ricostruisce lo stato.

In questa fase può:

• interrogare sistemi;
• consultare documentazione;
• confrontare dati;
• individuare anomalie;
• preparare una diagnosi.

I rischi operativi sono limitati, ma rimangono importanti quelli relativi alla riservatezza e all’accesso ai dati.

L’agente prepara un’azione senza eseguirla.

Può generare:

• una modifica al codice;
• una query;
• un aggiornamento;
• una risposta;
• un piano di intervento;
• un insieme di operazioni.

La proposta deve essere rappresentata in una forma verificabile da una persona o da un controllo automatico.

L’azione viene applicata soltanto quando sono soddisfatte le condizioni previste.

Queste possono includere:

• approvazione umana;
• test completati;
• validazioni automatiche;
• assenza di conflitti;
• finestra operativa corretta;
• permesso temporaneo.

Separare le fasi rende più semplice introdurre gradualmente l’automazione senza affidare immediatamente all’agente il controllo completo del processo.

La gestione dei permessi non dovrebbe essere aggiunta dopo la realizzazione del workflow.

Fa parte del suo comportamento.

L’agente dovrebbe disporre soltanto dei permessi necessari per l’attività corrente.

Un agente che analizza errori non ha necessariamente bisogno di modificare dati. Un agente che prepara una pull request non deve poter distribuire direttamente in produzione.

Ridurre i privilegi limita l’impatto di:

• interpretazioni errate;
• istruzioni ambigue;
• dati malevoli;
• bug negli strumenti;
• compromissione delle credenziali.

La stessa operazione può richiedere autorizzazioni differenti in base all’ambiente o ai dati coinvolti.

Per esempio:

• lettura libera in sviluppo;
• dati anonimizzati in test;
• sola lettura in produzione;
• modifica in produzione solo dopo approvazione;
• esclusione completa di alcuni clienti o dataset.

I confini dovrebbero essere applicati dal sistema, non affidati esclusivamente alle istruzioni testuali.

Alcune capacità possono essere concesse soltanto per una singola attività o per un periodo limitato.

Questo riduce il rischio che credenziali ampie rimangano disponibili oltre il necessario.

Le azioni distruttive richiedono una gestione specifica.

Quando possibile, considero preferibile:

• utilizzare cancellazioni logiche;
• produrre un’anteprima;
• richiedere conferma;
• conservare lo stato precedente;
• prevedere compensazioni;
• limitare il numero di elementi modificabili.

Un agente non dovrebbe poter eseguire un’operazione irreversibile soltanto perché ha interpretato una richiesta come autorizzazione sufficiente.

Molti processi funzionano perché le persone conoscono l’ordine corretto delle attività.

Un agente ha bisogno che quell’ordine sia rappresentato.

Un workflow operativo può specificare:

Obiettivo
   ↓
Precondizioni
   ↓
Raccolta delle informazioni
   ↓
Scelta dell’azione
   ↓
Controlli
   ↓
Approvazione eventuale
   ↓
Esecuzione
   ↓
Verifica
   ↓
Registrazione dell’esito

Prima di iniziare, deve essere possibile verificare che il sistema si trovi in uno stato compatibile con l’operazione.

Per esempio:

• il ticket è assegnato;
• il dato esiste;
• l’ambiente è disponibile;
• non è presente un’altra elaborazione;
• la richiesta è stata approvata;
• la versione del sistema è quella attesa.

Un agente deve sapere anche quando non procedere.

Può essere necessario fermarsi quando:

• mancano informazioni obbligatorie;
• due fonti autorevoli sono in conflitto;
• il risultato supera una determinata soglia;
• l’operazione richiede un permesso non disponibile;
• il sistema restituisce uno stato inatteso;
• la verifica fallisce;
• l’impatto non può essere determinato.

Fermarsi non rappresenta necessariamente un fallimento.

In un processo controllato, riconoscere l’incertezza è spesso il comportamento corretto.

Il workflow deve definire quale evidenza dimostra che l’attività è conclusa.

Una modifica al codice può essere considerata completa quando:

• il codice è stato modificato;
• i test rilevanti sono stati eseguiti;
• il risultato è stato revisionato;
• non sono emerse regressioni note;
• la modifica è stata registrata;
• il riepilogo descrive limiti e impatti.

Questi criteri aiutano l’agente a non confondere la produzione di un output con il completamento del lavoro.

La supervisione umana non deve essere necessariamente presente in ogni passaggio.

Dovrebbe concentrarsi nei punti in cui il giudizio, il rischio o l’ambiguità sono maggiori.

Molti risultati possono essere controllati attraverso regole deterministiche:

• validazione dello schema;
• test;
• linting;
• controlli sui permessi;
• confronto con soglie;
• vincoli nel database;
• simulazioni;
• verifica delle dipendenze;
• controllo della presenza di campi obbligatori.

Questi controlli sono particolarmente utili perché non dipendono dalla stessa capacità probabilistica che ha generato la proposta.

La revisione umana è più utile quando riguarda:

• decisioni con impatto elevato;
• casi nuovi;
• comunicazioni sensibili;
• conflitti tra obiettivi;
• eccezioni non previste;
• modifiche irreversibili;
• dati che richiedono interpretazione.

Il revisore deve però ricevere informazioni sufficienti.

Una richiesta di approvazione generica, priva del contesto e delle conseguenze, trasferisce semplicemente il problema alla persona.

Una buona richiesta dovrebbe includere:

• obiettivo;
• stato iniziale;
• azione proposta;
• motivazione;
• impatto previsto;
• controlli eseguiti;
• rischi residui;
• possibilità di annullamento.

L’autonomia può crescere nel tempo.

Un possibile percorso è:

1. l’agente osserva e sintetizza;
2. propone azioni;
3. esegue azioni reversibili dopo approvazione;
4. esegue autonomamente attività a basso rischio;
5. richiede supervisione soltanto per eccezioni definite.

Questa progressione permette di raccogliere evidenze prima di aumentare i privilegi.

Un workflow con agenti deve essere osservabile come qualsiasi altro processo operativo.

La presenza di un modello non riduce questa necessità. La rende più importante, perché alcune decisioni non derivano da una sequenza completamente deterministica.

Una traccia operativa dovrebbe includere almeno:

• identificativo dell’attività;
• utente o sistema che l’ha richiesta;
• obiettivo;
• modello e configurazione utilizzati;
• fonti consultate;
• strumenti invocati;
• parametri rilevanti;
• risultati restituiti;
• approvazioni;
• modifiche applicate;
• verifiche eseguite;
• esito finale;
• eventuali errori o interruzioni.

Ogni passaggio dovrebbe essere collegato allo stesso identificativo.

Task: TASK-2048
    ↓
Contesto recuperato
    ↓
Repository analizzato
    ↓
Modifica proposta
    ↓
Test eseguiti
    ↓
Revisione approvata
    ↓
Pull request creata

Questo consente di ricostruire il percorso completo senza cercare manualmente tra sistemi differenti.

Sapere che l’agente ha chiamato uno strumento non dimostra che l’operazione abbia prodotto il risultato desiderato.

È necessario registrare anche:

• risorsa creata o modificata;
• stato precedente e successivo;
• identificatore restituito;
• esito della verifica;
• eventuali azioni successive.

I log possono contenere informazioni sensibili, prompt, dati personali o credenziali.

L’osservabilità deve quindi essere progettata insieme alle regole di:

• minimizzazione dei dati;
• mascheramento;
• conservazione;
• controllo degli accessi;
• cancellazione;
• separazione tra ambienti.

Registrare tutto senza criteri può creare un nuovo rischio.

Un sistema pronto per gli agenti non richiede necessariamente una documentazione enorme.

Richiede documentazione utilizzabile.

È utile che le informazioni siano:

• vicine al codice o al processo;
• strutturate;
• aggiornabili;
• dotate di un proprietario;
• collegate a versioni e ambienti;
• verificabili attraverso il sistema reale.

Il codice mostra spesso come funziona il sistema, ma non perché sia stato progettato in un certo modo.

Decisioni architetturali brevi possono spiegare:

• perché un servizio possiede un dato;
• perché una comunicazione è asincrona;
• perché un’operazione richiede approvazione;
• perché una libreria non deve essere utilizzata;
• quali alternative sono state escluse.

Queste informazioni aiutano sia le persone sia gli agenti a evitare modifiche che contraddicono vincoli non visibili nel codice.

Una documentazione che descrive manualmente ogni endpoint può diventare obsoleta.

Quando possibile, è preferibile generare o verificare parte delle informazioni attraverso:

• schemi;
• contratti API;
• test;
• configurazioni;
• definizioni dei workflow;
• metadata del repository.

Più il contesto è collegato al sistema effettivo, minore è il rischio che diverga dalla realtà.

La documentazione dovrebbe descrivere anche ciò che il sistema non garantisce.

Per esempio:

• dati aggiornati con ritardo;
• processi non idempotenti;
• ambienti non equivalenti;
• operazioni non supportate;
• casi che richiedono una persona;
• dipendenze esterne non controllabili.

Un limite esplicito è più utile di una promessa generica di affidabilità.

Consideriamo un agente incaricato di assistere nella gestione degli errori tra e-commerce ed ERP.

Un’implementazione poco controllata potrebbe fornirgli:

• accesso ai log;
• accesso al database;
• credenziali dell’ERP;
• istruzione di “risolvere gli ordini bloccati”.

L’agente dovrebbe ricostruire autonomamente:

• quali ordini siano realmente bloccati;
• quale sistema contenga il dato corretto;
• se l’ordine sia già stato creato;
• se una nuova esecuzione generi duplicati;
• quali campi possano essere modificati;
• quando sia necessario coinvolgere una persona.

Un workflow più esplicito potrebbe invece esporre queste capacità:

list_failed_order_syncs
        ↓
get_sync_details
        ↓
classify_sync_error
        ↓
prepare_retry
        ↓
validate_retry
        ↓
request_approval
        ↓
execute_retry
        ↓
verify_order_state

Ogni strumento avrebbe input e output definiti.

L’agente non riceverebbe accesso generico all’ERP. Utilizzerebbe operazioni specifiche che applicano controlli e registrano gli effetti.

Il workflow potrebbe inoltre stabilire che:

• gli errori temporanei possano essere ritentati automaticamente;
• i dati non validi richiedano una proposta di correzione;
• i possibili duplicati richiedano approvazione;
• gli ordini sopra una certa soglia non possano essere modificati autonomamente;
• ogni retry debba essere seguito da una verifica.

In questo scenario, l’agente non sostituisce il processo.

Opera all’interno di un processo progettato per limitare ambiguità e rischio.

Non è necessario riprogettare l’intera architettura prima di sperimentare con gli agenti.

È però utile evitare di compensare ogni mancanza attraverso prompt sempre più complessi.

Un percorso progressivo può partire da alcuni interventi.

Il primo caso d’uso dovrebbe avere:

• obiettivo chiaro;
• input identificabili;
• numero limitato di sistemi;
• impatto controllabile;
• risultati verificabili;
• possibilità di supervisione.

Attività troppo ampie, come “gestire l’assistenza” o “mantenere il software”, nascondono un numero elevato di decisioni e responsabilità.

È preferibile iniziare da un compito specifico, come classificare anomalie note o preparare una proposta di modifica.

Prima di costruire l’agente è utile chiedersi quali informazioni utilizzi oggi una persona per completare l’attività.

Queste possono provenire da:

• documentazione;
• database;
• ticket;
• repository;
• dashboard;
• conversazioni;
• procedure operative.

La mappa rende visibili le dipendenze informative e le conoscenze ancora implicite.

Le operazioni necessarie possono essere esposte attraverso funzioni specifiche, anche se inizialmente utilizzate soltanto in lettura.

Questo consente di definire:

• contratti;
• permessi;
• errori;
• audit;
• verifiche.

Prima di consentire modifiche automatiche, l’agente può produrre proposte strutturate.

Questa fase permette di valutare:

• correttezza;
• frequenza degli errori;
• casi ambigui;
• qualità del contesto;
• utilità del risultato;
• tempo risparmiato.

Dopo aver osservato un numero sufficiente di esecuzioni, alcuni casi possono essere considerati abbastanza prevedibili da non richiedere sempre approvazione.

L’automazione dovrebbe crescere dove esistono evidenze, non dove esiste soltanto entusiasmo.

Molte proprietà necessarie agli agenti sono già desiderabili nei sistemi tradizionali:

• API coerenti;
• documentazione aggiornata;
• responsabilità chiare;
• permessi limitati;
• errori comprensibili;
• workflow espliciti;
• test;
• osservabilità;
• procedure di ripristino.

Gli agenti rendono più evidenti le lacune perché non possono affidarsi alla conoscenza informale nello stesso modo delle persone.

Se un agente non riesce a stabilire quale sistema possieda un dato, è possibile che anche il team non abbia una risposta realmente condivisa.

Se non esiste un modo sicuro per ripetere un’operazione, il problema riguarda anche gli operatori umani.

Se una modifica può essere verificata soltanto dalla persona che conosce storicamente il sistema, l’organizzazione possiede già una dipendenza fragile.

Da questo punto di vista, progettare per gli agenti può diventare un esercizio utile per migliorare la qualità complessiva dell’architettura.

Costringe a rendere visibili contratti, confini e procedure che in precedenza potevano rimanere impliciti.

Il valore di un agente non dipende dal numero di operazioni che può eseguire senza intervento umano.

Dipende dalla capacità di produrre risultati utili all’interno di confini comprensibili.

Un agente molto autonomo, ma privo di contesto affidabile e controlli, può aumentare il lavoro necessario per verificare e correggere i suoi output.

Un agente più limitato può invece generare valore concreto se:

• recupera le informazioni corrette;
• prepara proposte verificabili;
• utilizza strumenti specifici;
• rispetta i permessi;
• riconosce i casi ambigui;
• documenta le azioni;
• permette di ricostruire il risultato.

Per questo considero l’autonomia una conseguenza della maturità del processo.

Prima vengono il contesto, i contratti, i controlli e la supervisione.

Poi, dove le evidenze lo consentono, può crescere la delega.

Integrare un agente AI non significa semplicemente collegare un modello alle API esistenti.

Significa preparare un ambiente nel quale le decisioni possano essere prese e verificate senza dipendere da conoscenze nascoste.

Un sistema è più pronto per gli agenti quando:

• il contesto è accessibile e attribuito;
• gli strumenti hanno responsabilità limitate;
• i contratti descrivono input, effetti ed errori;
• i permessi riflettono il rischio;
• i workflow definiscono condizioni di arresto e completamento;
• le modifiche possono essere verificate;
• le azioni sono osservabili;
• l’intervento umano è previsto nei punti appropriati.

Queste proprietà non eliminano l’incertezza dei modelli.

La inseriscono però in un processo capace di contenerla.

L’agent readiness nasce quindi meno dalla capacità di “far fare qualcosa all’AI” e più dalla disciplina con cui rendiamo il software comprensibile, interrogabile e governabile.

Un agente può operare bene soltanto quando il sistema gli permette di capire cosa può fare, quali informazioni deve utilizzare, come verificare il risultato e quando deve fermarsi.

Prima di essere autonomo, deve poter essere affidabile.