Un errore non è testo: per un agente è parte dell’API

Abbiamo passato anni a trattare i messaggi di errore come testo di servizio: qualcosa che deve spiegare a uno sviluppatore che cosa è andato storto e, possibilmente, suggerirgli come rimediare. Con gli agenti AI questa abitudine smette di essere innocua.

Uno studio pubblicato il 28 settembre 2026 ha analizzato 3.001 messaggi di errore provenienti da 150 server MCP molto utilizzati. In 949 casi il messaggio non si limita a descrivere il problema: dice anche al chiamante che cosa fare dopo. La metà di questi suggerimenti dipende però da capacità che il server non può sapere se il chiamante possiede.

Per una persona è normale leggere «esegui questo comando nel terminale», «apri questa pagina», «modifica la configurazione» oppure «aspetta e riprova». Per un agente che può agire soltanto attraverso gli strumenti che gli sono stati concessi, la stessa frase può descrivere un’azione letteralmente impossibile.

La parte interessante non è che l’agente fallisca. È perché fallisce: spesso prende sul serio l’istruzione, constata di non poterla eseguire e si ferma, anche quando tra i suoi tool esiste un’altra strada per risolvere il problema.

Un errore non è più soltanto testo

Quando il consumatore di un’API era uno sviluppatore, potevamo permetterci una certa confusione tra due piani diversi: descrivere lo stato del sistema e dare istruzioni alla persona che lo sta usando. Il programmatore leggeva entrambi, capiva il contesto e decideva.

Un agente tool-only non ha quella libertà. Ha un action space preciso: l’insieme delle operazioni che il runtime gli espone in quel momento. Può magari chiamare login, create_ticket e search, ma non può aprire un terminale, modificare una variabile d’ambiente o visitare una pagina di autenticazione se nessuno gli ha dato quegli strumenti.

Questo trasforma il messaggio di errore in qualcosa di più vicino a una parte del contratto dell’API. Non basta che la remediation sia corretta in assoluto. Deve essere eseguibile dal soggetto che riceve il messaggio.

È una distinzione piccola solo in apparenza. Se un server restituisce «credenziali scadute: esegui foo --auth», sta implicitamente assumendo che dall’altra parte ci sia qualcuno con una shell. Se invece il chiamante dispone di un tool login, la remediation utile per quel sistema è «chiama login e poi ripeti l’operazione».

I numeri mostrano quanto costa un suggerimento sbagliato

Gli autori hanno costruito 168 scenari a partire dai task della Berkeley Function Calling Leaderboard e hanno confrontato cinque modelli OpenAI, limitandoli deliberatamente ai tool disponibili nel task. Non avevano terminale, browser o orologio esterno: una configurazione che assomiglia a molti agenti integrati dentro applicazioni e connettori.

Sui casi di credenziali scadute, aggiungere al messaggio la richiesta di eseguire un comando da terminale ha portato la recovery media dall’82% al 45%. Quando la stessa remediation veniva riscritta indicando il tool di login effettivamente disponibile, la recovery saliva all’84%.

Il caso del rate limit è ancora più netto. Un generico «Wait before retrying» lasciava la recovery media al 6%. Specificare quale chiamata ripetere portava il risultato all’88% nei loro scenari. Non perché il secondo testo contenesse una spiegazione più sofisticata, ma perché rendeva esplicita un’azione compatibile con ciò che l’agente poteva davvero fare.

Va mantenuto il contesto: è uno studio controllato, basato su specifici task BFCL, cinque modelli e sette tipi di errore. Non dimostra che ogni agente in produzione si comporterà con le stesse percentuali. Dimostra però molto bene un meccanismo: il testo di errore orienta il comportamento dell’agente, e una remediation fuori dal suo action space può essere peggiore della sola descrizione della causa.

Il paradosso: il modello più capace può fermarsi di più

Uno dei risultati più provocatori dello studio è che l’effetto negativo non diminuisce necessariamente con modelli più capaci. Nel test sulle credenziali scadute, la perdita associata al comando da terminale cresce da 18 punti per GPT-5.5 a 69 punti per GPT-6 Astra.

Gli autori parlano di literal compliance: il modello prende seriamente l’istruzione che riceve. Se l’errore dice che la soluzione è un comando che non può eseguire, non sempre decide di ignorarlo e inventarsi un percorso alternativo. Può invece concludere correttamente — rispetto al testo che gli abbiamo dato — che il prossimo passo spetta all’utente.

Qui c’è una lezione utile anche fuori da MCP. Migliorare il ragionamento del modello non corregge automaticamente un’interfaccia progettata su assunzioni sbagliate. Anzi, un sistema più disciplinato nel seguire le istruzioni può rendere quelle assunzioni più visibili.

È facile liquidare il problema dicendo che «il modello dovrebbe capire». È la stessa scorciatoia con cui per anni abbiamo giustificato API incoerenti perché uno sviluppatore esperto riusciva comunque a usarle. Funzionare non significa essere progettato bene.

L’action space deve entrare nel design dell’errore

Nel mio articolo su Cloudflare cf e il software progettato anche per utenti non umani il tema era la necessità di contratti più espliciti: output strutturati, naming coerente, configurazioni verificabili. Questo studio aggiunge un pezzo meno evidente. Anche il percorso di fallimento deve essere progettato per il consumatore reale.

Per un tool destinato agli agenti, un buon errore dovrebbe separare almeno tre informazioni:

• che cosa è successo, senza ambiguità;
• se esiste una remediation eseguibile attraverso i tool disponibili;
• quale operazione concreta va invocata dopo, quando il server può indicarla in modo affidabile.

Non significa trasformare ogni errore in un piccolo prompt. Al contrario: significa ridurre le istruzioni decorative e smettere di suggerire azioni che appartengono a un altro ambiente operativo.

Lo studio trova, per esempio, che 62 dei 67 next step associati a errori di credenziali chiedono una modifica di configurazione, l’apertura di una pagina web o un comando da terminale. In dodici casi, distribuiti su cinque server, il server offriva già un tool che avrebbe potuto effettuare la riparazione. Il problema quindi non era l’assenza della capacità: era il fatto che l’errore indirizzava il chiamante altrove.

La remediation è controllo di flusso

Questo è il punto che trovo più utile dal punto di vista architetturale. In un sistema agentico, una frase come «fai X e riprova» non è semplice documentazione. È un’indicazione di controllo di flusso che entra nel contesto del modello e può cambiare il percorso di esecuzione.

Se la consideriamo soltanto copy, finiamo per affidare a linguaggio naturale libero una parte del comportamento del sistema. Se la consideriamo parte dell’interfaccia, iniziamo invece a farci domande più sane: il passo suggerito è disponibile? è autorizzato? è idempotente? sappiamo quale chiamata ripetere? serve davvero un intervento umano oppure esiste una capability già esposta?

È lo stesso salto che avviene quando passiamo da un messaggio «qualcosa è andato storto» a un errore tipizzato. Solo che qui non stiamo strutturando soltanto la causa: stiamo strutturando la possibilità di recupero.

Non tutto deve essere risolto dal server

Gli autori testano anche una contromisura lato agente. Prima che il modello legga l’errore, un filtro elimina le frasi che dicono al chiamante che cosa fare e conserva la causa. Nel caso delle credenziali scadute, questa operazione porta la recovery media all’82%, contro il 45% del messaggio con il comando irraggiungibile.

È una soluzione interessante soprattutto quando usiamo server di terze parti che non possiamo correggere. Ma è anche un compromesso: eliminare sistematicamente i next step può buttare via istruzioni buone insieme a quelle incompatibili. Gli stessi risultati mostrano che, per alcuni errori come permessi mancanti o rate limit, una remediation esplicita e corretta è molto utile.

La direzione migliore non è quindi «togliamo tutti i suggerimenti». È rendere i suggerimenti compatibili con le capacità reali, oppure dare al runtime abbastanza struttura per decidere quali istruzioni sono applicabili.

Gli agenti stanno trasformando dettagli di UX in architettura

Più il software agisce autonomamente, più elementi che prima consideravamo marginali diventano parte dell’architettura. Il nome di un tool, la forma dell’output, la granularità dei permessi, il significato di un errore e il modo in cui descriviamo una recovery non sono rifiniture.

Nel pezzo su cosa cambia quando il software comincia ad agire il punto era che autonomia e verifica devono crescere insieme. Qui vediamo lo stesso principio a una scala più piccola: se un agente deve recuperare da un fallimento, non possiamo lasciargli una mappa che descrive porte che nel suo mondo non esistono.

La regola pratica è meno spettacolare di molte discussioni sull’AI, e proprio per questo probabilmente è più utile: un errore destinato a un agente deve descrivere il problema nel contesto delle azioni che quell’agente può realmente compiere.

Non serve insegnare al modello a essere più creativo davanti a un contratto ambiguo. Serve smettere di usare l’intelligenza del modello come toppa per interfacce che non dichiarano correttamente il proprio percorso di recupero.