Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Progettazione: Casi d'uso e Strumenti

Lezione 3 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Parti dalle aspettative, non dall’API
  2. L’inventario dei casi d’uso
  3. Escludi e documentalo
  4. Dai casi d’uso agli strumenti
  5. Il contratto di ogni strumento
  6. Descrizioni scritte per essere scelte
  7. Annotazioni di sicurezza
  8. Un piano che funge da piano di test
  9. Punti chiave

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-sdk inesistente e un manifest chatgpt-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:

CampoDomanda
ObiettivoCosa sta cercando di realizzare la persona?
Richieste di esempioCome lo formulerebbero, direttamente o indirettamente?
Risultato attesoCosa renderebbe l’interazione un successo?
Contesto richiestoQuali informazioni, accesso all’account o stato precedente sono necessari?
CapacitàUna competenza (skill) è sufficiente o è necessario uno strumento MCP?
Limite di sicurezzaPotrebbe esporre dati, modificare stati, spendere denaro o influenzare terze parti?
DecisionePrima 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_projects per trovare i progetti;
  • get_project per esaminarne uno;
  • create_project per crearne uno;
  • update_project per modificare i dettagli;
  • archive_project per 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

CampoDefinizione
NomeUn identificatore stabile e orientato all’azione
TitoloUn’azione concisa e leggibile dall’uomo
DescrizioneL’obiettivo dell’utente e le condizioni che dovrebbero attivare lo strumento
Schema di inputParametri richiesti e opzionali, tipi, valori consentiti, limiti
Schema di outputCampi strutturati che il modello può ispezionare e riutilizzare
AutorizzazioneL’account, il ruolo o l’accesso che il server deve verificare
Effetti collateraliDati o stato esterno che lo strumento potrebbe modificare
FallimentiErrori 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 è true solo se lo strumento non può modificare alcuno stato;
  • destructiveHint è true se lo strumento può produrre un risultato irreversibile o difficile da annullare;
  • openWorldHint è true se 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