Agent Experience per SDK: misurare gli errori degli agenti

Agent Experience per SDK significa verificare come un agente di programmazione scopre e usa una tecnologia concreta. Il problema emerge quando il codice sembra credibile ma impiega una versione sbagliata, un metodo deprecato o una configurazione che il team non vorrebbe distribuire. Per migliorare il risultato servono scenari, criteri e prove di esecuzione: aggiungere altra documentazione senza misurare il comportamento può lasciare intatto il difetto.

Il nuovo AX Practitioner Playbook, disponibile dal 9 ottobre 2026, propone un metodo per valutare gli agenti, riconoscere le cause degli errori e correggere le superfici che li orientano. La parte utile per chi sviluppa SDK e API è trasformare un giudizio vago, codice buono o cattivo, in una verifica ripetibile. Vediamo come impostare una prima valutazione su un progetto di test, senza inventare percentuali di affidabilità o confondere una risposta plausibile con un risultato eseguito.

Agent Experience per SDK: il prodotto va oltre il modello

Un agente coding sceglie pacchetti, interpreta esempi e combina istruzioni con strumenti. Il risultato dipende dal modello, ma anche da ciò che il prodotto rende scopribile. Documentazione, file di istruzioni, strumenti MCP, CLI e messaggi di errore possono orientare il lavoro verso un percorso corretto oppure ambiguo.

SDK indica un insieme di strumenti e librerie pensato per sviluppare con una tecnologia. API indica una interfaccia attraverso cui un programma accede a funzioni o dati. Un agente può conoscere il concetto generale e sbagliare il dettaglio che decide se una specifica versione funziona. La familiarità con il linguaggio non garantisce la correttezza del pacchetto.

Il taglio AX riguarda questo percorso di uso. Una documentazione chiara per una persona esperta può lasciare impliciti requisiti che un agente non ricostruisce. Per esempio, il nome del pacchetto corrente può comparire soltanto in una pagina separata, mentre un esempio storico resta più facile da trovare. La valutazione deve mostrare quale informazione mancava nel momento della scelta.

Scegliere uno scenario piccolo ma rappresentativo

Parti da un compito che un utilizzatore reale chiederebbe. Un esempio ipotetico può essere creare un client che legge una lista paginata, gestisce una risposta vuota e restituisce un errore comprensibile quando il servizio non risponde. Il compito deve essere abbastanza limitato da poter verificare ogni passaggio.

Specifica linguaggio, versione del runtime e versione del prodotto quando fanno parte del requisito. Indica anche quale ambiente di test è disponibile e quali risorse sono consentite. Non usare una richiesta generica come costruisci una integrazione moderna se il risultato atteso richiede condizioni precise.

Prepara il progetto iniziale e conserva una copia identica per ogni prova. Se una sessione eredita file prodotti da quella precedente, il confronto misura anche quelle modifiche. Una baseline ripristinabile consente di attribuire il cambiamento alla variabile che stai valutando.

Che cosa deve contenere la scheda dello scenario

• Obiettivo concreto del codice.
• Ambiente e versioni richieste.
• Dati sintetici disponibili.
• Risorse che il sistema può consultare.
• Comandi di build e test previsti.
• Risultati che devono essere verificati.
• Condizioni che rendono la prova non valida.

Questa scheda deve essere leggibile anche da chi non ha seguito la discussione iniziale. Se un collega non sa come verificare il risultato, i criteri non sono ancora abbastanza precisi.

Scrivere criteri che distinguano forma e comportamento

Un criterio utile deve descrivere una proprietà osservabile. Usa il pacchetto richiesto nella versione prevista è più verificabile di segue le migliori pratiche. Gestisce una seconda pagina è più concreto di supporta la paginazione, soprattutto se il test include soltanto una pagina di dati.

Separare criteri semantici e controlli di esecuzione evita punteggi ingannevoli. La struttura può apparire corretta, ma il progetto può non compilare. Il codice può compilare, ma usare un endpoint errato. Un test può passare perché non esercita il comportamento che voleva misurare.

Per lo scenario ipotetico definisci almeno versione del pacchetto, richiesta corretta, elaborazione di più pagine, gestione della lista vuota e comportamento in caso di errore. A ogni criterio associa la prova: lettura del file delle dipendenze, controllo del codice o test con un servizio simulato.

Non delegare interamente la definizione dei criteri allo stesso modello che deve essere valutato. Il team che conosce il prodotto deve stabilire ciò che è corretto. Un assistente può aiutare a organizzare la griglia, ma i requisiti restano una scelta tecnica da confermare.

Eseguire build e test senza dare per veri i resoconti

Se una sessione dichiara di aver compilato, conserva comando, codice di uscita e output pertinente. La sola frase build riuscita non costituisce evidenza. Verifica che il comando abbia usato il progetto e la configurazione attesi e che non abbia saltato il componente rilevante.

I test devono controllare il comportamento richiesto con dati sintetici. Nel caso della paginazione, prepara almeno due pagine e verifica il risultato completo. Nel caso di un errore di rete, controlla che il codice non restituisca una lista vuota come se il servizio avesse risposto correttamente.

Distinguere questi casi ha un effetto pratico: una lista davvero vuota e una richiesta fallita richiedono decisioni diverse da parte di chi usa il programma. Una valutazione che li unisce può premiare codice che nasconde un problema operativo.

La guida a sviluppare con Claude Code evitando errori di sicurezza approfondisce i controlli del contesto di lavoro. Per la valutazione AX concentra invece la misura sul compito e sul prodotto: sicurezza del contesto e correttezza del codice integrato sono verifiche complementari.

Come trattare un test che non può essere eseguito

Segna il criterio come non verificato e spiega il requisito mancante. Un servizio indisponibile non dimostra che il codice sia errato, ma impedisce di confermarne il funzionamento. Non sostituire il test reale con una descrizione che presume il risultato.

Puoi separare la compilazione locale da una integrazione remota e usare una simulazione per alcuni casi. Registra però il limite: la simulazione controlla il contratto che hai modellato, mentre il servizio reale può introdurre altri requisiti.

Leggere la sequenza per capire perché il sistema sbaglia

Il risultato finale mostra il sintomo; la sequenza di strumenti e decisioni aiuta a individuare la causa. Un file di istruzioni può non essere stato caricato, può essere stato disponibile ma ignorato oppure può essere stato letto e applicato in modo scorretto. Questi casi richiedono interventi diversi.

Se il contenuto non viene scoperto, rivedi posizione, nome e collegamento con il compito. Se viene letto ma resta ambiguo, chiarisci versione, prerequisiti ed esempi. Se viene applicato male, verifica che il requisito sia espresso in modo operativo e che gli strumenti restituiscano informazioni sufficienti.

Non attribuire automaticamente ogni errore al modello. Un esempio incoerente con la versione corrente può indurre anche una persona a scegliere il metodo sbagliato. Allo stesso tempo, una pagina corretta non prova che ogni agente la troverà o la userà bene. Il controllo deve seguire il percorso osservato.

Conserva soltanto la telemetria necessaria alla diagnosi. Le sequenze possono includere file interni, parametri e risposte di strumenti. Usa dati di prova e un archivio protetto; non pubblicare materiale completo se basta un estratto privo di segreti per descrivere il difetto.

Correggere una superficie alla volta

Formula una ipotesi concreta: il sistema sceglie il pacchetto precedente perché il nome attuale non compare nel punto di ingresso della documentazione. La modifica proposta può essere aggiungere un esempio minimo con versione e dipendenza esplicite. Una ipotesi così precisa permette di verificare se il comportamento cambia.

Evita di aggiornare contemporaneamente istruzioni, esempi, strumenti e criteri. Se il risultato migliora, non saprai quale modifica abbia aiutato. Parti dalla correzione più vicina alla causa osservata e ripeti lo stesso scenario in condizioni confrontabili.

Per gli strumenti MCP, cioè strumenti collegati tramite Model Context Protocol, controlla nome, descrizione, input e output. Se una risposta omette la versione o presenta valori ambigui, il modello può colmare il vuoto con una inferenza sbagliata. Il contratto dello strumento deve fornire ciò che serve alla decisione successiva.

Mantieni gli esempi eseguibili quando possibile. Un frammento isolato senza importazioni o dipendenze può essere utile per illustrare un concetto, ma non deve sembrare un progetto completo. Se mostri un esempio parziale, dichiarane chiaramente il confine nella documentazione.

Confrontare le prove senza inventare affidabilità generale

Una singola sessione riuscita non basta a dichiarare corretto un metodo per tutti i compiti. Ripeti gli scenari rilevanti e conserva numero di prove, condizioni e criteri. Se cambi modello, versione del prodotto o risorse disponibili, il confronto deve rendere visibile la variazione.

La data limite dei dati di addestramento non descrive con precisione ciò che un modello sa fare con uno specifico prodotto. Può sbagliare una funzione precedente a quella data oppure ricostruire una soluzione per un caso più recente. La misura utile resta il lavoro eseguito nelle condizioni previste, insieme alle informazioni aggiuntive fornite.

Per un team che usa automazioni anche fuori dallo sviluppo, la guida a cosa delegare nella automazione SEO con AI offre un contesto complementare. Il principio trasferibile è assegnare un risultato verificabile e mantenere responsabilità per le decisioni; i criteri concreti devono però restare specifici di SDK e API.

Presenta i risultati con limiti chiari. Distinguere riuscito, fallito e non verificato è più utile di un punteggio unico che nasconde build saltate e servizi indisponibili. Un dato misurato descrive il campione testato; una previsione sul lavoro futuro resta una stima da validare.

Rendere la valutazione parte della manutenzione

Quando aggiorni il prodotto, rivedi scenari, esempi e criteri. Un comportamento corretto per una versione può diventare deprecato nella successiva. Versionare la griglia consente di spiegare perché un risultato è cambiato e impedisce che una vecchia valutazione continui a premiare integrazioni superate.

Assegna un responsabile alla documentazione o allo strumento che richiede la correzione. Il report dovrebbe contenere scenario riproducibile, risultato atteso, risultato osservato e modifica proposta. Il team può così valutare questa ipotesi e applicare un intervento che migliori il percorso reale.

Agent Experience per SDK diventa utile quando chiude questo ciclo: scegliere un compito, verificarlo con prove, capire la causa e correggere la superficie pertinente. Parti da uno scenario piccolo che il team conosce bene. Un risultato dimostrabile e un esempio aggiornato offrono una base più solida di molte istruzioni aggiunte senza misurare il loro effetto.