Progettazione: Casi d'uso e Strumenti
In questa pagina
Lezione riscritta il 3 novembre 2026 sulla base delle pagine della documentazione di OpenAI Brainstorm plugin use cases e Define tools. La lezione precedente installava un pacchetto
@openai/apps-sdkinesistente e un manifestchatgpt-app.json; l’installazione degli strumenti reali (SDK MCP ufficiali) avviene nella Lezione 4. Fonti: Brainstorm plugin use cases · Define tools.
Parti dalle aspettative, non dall’API
La documentazione di OpenAI consiglia di iniziare a costruire un plugin prima di scrivere una singola riga di codice: elencando ciò che le persone si aspetteranno da esso. Il nome del plugin, la descrizione, le competenze, gli strumenti e il prodotto a cui si collega creano tutte delle aspettative; la tua implementazione deve soddisfarle, oppure devi avere una ragione deliberata per non farlo.
Immagina qualcuno che ha installato il tuo plugin senza leggerne la documentazione. Cosa gli chiederà di fare? Per scoprirlo, attingi dalle attività che i tuoi utenti già svolgono nel tuo prodotto, dai ticket di supporto, dalle query di ricerca, dalle richieste di funzionalità, dal vocabolario che usano e dalle soluzioni alternative che li costringono a copiare dati da uno strumento all’altro. Prendi nota delle richieste dirette che nominano il plugin e di quelle indirette che dichiarano solo l’obiettivo: un plugin di gestione progetti deve gestire «Mostra la bacheca di lancio Acme» esattamente come «Cosa sta bloccando il lancio?».
Non limitare questo inventario a ciò che la tua API fa già. Elenca prima le aspettative, poi confrontale con ciò che puoi fornire in modo sicuro e affidabile.
L’inventario dei casi d’uso
Per ogni caso d’uso, OpenAI raccomanda di rispondere a sette domande:
| Campo | Domanda |
|---|---|
| Obiettivo | Cosa sta cercando di realizzare la persona? |
| Richieste di esempio | Come lo formulerebbero, direttamente o indirettamente? |
| Risultato atteso | Cosa renderebbe l’interazione un successo? |
| Contesto richiesto | Quali informazioni, accesso all’account o stato precedente sono necessari? |
| Capacità | Una competenza (skill) è sufficiente o è necessario uno strumento MCP? |
| Limite di sicurezza | Potrebbe esporre dati, modificare stati, spendere denaro o influenzare terze parti? |
| Decisione | Prima versione, più tardi o esclusione intenzionale? |
Raggruppa le richieste che condividono un obiettivo: «Elenca i miei task aperti», «Cosa devo fare oggi?» e «Mostra il lavoro scaduto» appartengono probabilmente allo stesso caso d’uso di revisione dei task, con filtri diversi.
Verifica poi la copertura. Ogni caso d’uso selezionato deve avere un percorso completo dalla richiesta al risultato; le scritture devono includere autorizzazione e conferma; e il plugin deve sapere come dire ciò che non fa, offrendo al contempo un prossimo passo utile. Un plugin che ti permette di creare progetti ma non di elencarli, visualizzarli o modificarli promette più di quanto fornisca: o lo completi o ne restringi il posizionamento.
Escludi e documentalo
Non devi implementare tutto, ma ogni grande esclusione merita una motivazione: rischio inaccettabile per la sicurezza o la privacy, un’API che non può supportarlo in modo affidabile, permessi non verificabili, risultati fuorvianti dovuti a informazioni mancanti o un ambito della prima versione chiaramente dichiarato nell’elenco del plugin. Registra queste decisioni: informano i limiti delle competenze, le descrizioni degli strumenti, i rifiuti, i test e il testo dell’elenco pubblico.
Dai casi d’uso agli strumenti
Uno strumento deve servire un obiettivo dell’utente. Non copiare semplicemente la tua API interna così com’è. Per ogni caso d’uso selezionato, scrivi il risultato atteso, elenca le informazioni richieste, identifica letture, scritture e azioni esterne, raggruppa ciò che forma un’azione coerente e separa ciò che differisce per permessi, rischio o necessità di conferma.
L’esempio di OpenAI per un plugin di progetti:
list_projectsper trovare i progetti;get_projectper esaminarne uno;create_projectper crearne uno;update_projectper modificare i dettagli;archive_projectper un cambiamento di stato ad alte conseguenze.
Letture e scritture sono separate affinché il modello e l’utente possano distinguere la consultazione dalla modifica.
Il contratto di ogni strumento
| Campo | Definizione |
|---|---|
| Nome | Un identificatore stabile e orientato all’azione |
| Titolo | Un’azione concisa e leggibile dall’uomo |
| Descrizione | L’obiettivo dell’utente e le condizioni che dovrebbero attivare lo strumento |
| Schema di input | Parametri richiesti e opzionali, tipi, valori consentiti, limiti |
| Schema di output | Campi strutturati che il modello può ispezionare e riutilizzare |
| Autorizzazione | L’account, il ruolo o l’accesso che il server deve verificare |
| Effetti collaterali | Dati o stato esterno che lo strumento potrebbe modificare |
| Fallimenti | Errori che il modello può spiegare o da cui può riprendersi |
Tre regole completano questa tabella. Input espliciti: non fare affidamento sul modello per indovinare un ID o un ambito di account. Output riutilizzabili: restituisci ID stabili e informazioni sufficienti per la prossima chiamata. Output puliti: niente segreti, token di accesso, diagnostica interna o dati personali non necessari.
Descrizioni scritte per essere scelte
Il modello seleziona gli strumenti in base alla loro descrizione: descrivi l’intento dell’utente, non l’implementazione. Una buona descrizione dice cosa fa lo strumento, quando usarlo, come si differenzia dai suoi vicini e quali sono i suoi limiti o prerequisiti. Evita quelle che ripetono il nome dello strumento o usano gergo interno che i tuoi utenti non conoscono.
Annotazioni di sicurezza
Ogni strumento porta con sé delle annotazioni, impostate in base al suo comportamento effettivo:
readOnlyHintètruesolo se lo strumento non può modificare alcuno stato;destructiveHintètruese lo strumento può produrre un risultato irreversibile o difficile da annullare;openWorldHintètruese lo strumento accede a internet pubblico o entità esterne aperte, anche in sola lettura come una ricerca web. Un account o uno spazio di lavoro privato e delimitato non è «aperto» solo perché è ospitato altrove.
Le annotazioni aiutano ChatGPT e Codex a scegliere il giusto livello di conferma, ma non sostituiscono l’autorizzazione lato server, la convalida dell’input o la conferma per azioni importanti.
Un piano che funge da piano di test
Conserva l’inventario e il piano degli strumenti: diventano la tua checklist. Aggiungi richieste dirette, indirette, casi limite e fuori ambito, e verifica che il plugin finito si comporti come previsto per ciascuna di esse. Cerca anche strumenti che non servono a nessun caso d’uso documentato, letture mancanti prima delle scritture e descrizioni troppo simili tra loro che potrebbero confondere il modello.
Punti chiave
- Inizia da ciò che gli utenti si aspetteranno, poi confrontalo con ciò che puoi fornire in sicurezza
- Un inventario di sette domande per caso d’uso, incluse le esclusioni intenzionali
- Uno strumento per azione coerente; letture e scritture separate
- Un contratto per strumento: nome, titolo, descrizione, schemi, autorizzazione, effetti collaterali, fallimenti
- Le annotazioni (
readOnlyHint,destructiveHint,openWorldHint) seguono il comportamento effettivo e non sostituiscono l’autorizzazione