Ottimizza: metadati, competenze ed eventi
In questa pagina
Lezione riscritta il 3 novembre 2026 sulla base delle pagine della documentazione dei plugin OpenAI Optimize Metadata, Build Skills, MCP Events e Plugin Extensions. La versione precedente di questa lezione si basava sui moduli
analyticsedexperimentdi un SDK inesistente. Fonti: Optimize Metadata · Build Skills · MCP Events · Plugin Extensions.
I metadati sono testi di prodotto
ChatGPT e Codex decidono quando invocare i tuoi strumenti in base ai metadati che fornisci. Nomi, descrizioni e parametri ben scritti garantiscono che il tuo strumento venga attivato quando necessario ed evitano attivazioni indesiderate. OpenAI consiglia di trattare questi metadati come testi di prodotto: iterali, testali e misurane le prestazioni.
Un set di prompt di riferimento
Prima di toccare i tuoi metadati, costruisci un set etichettato di prompt di test:
- Prompt diretti che nominano esplicitamente il tuo prodotto o la tua fonte dati.
- Prompt indiretti che descrivono il risultato desiderato senza nominare il tuo strumento.
- Prompt negativi che dovrebbero essere gestiti da strumenti integrati o da altri plugin.
Per ogni prompt, documenta il comportamento atteso: chiamare il tuo strumento, non fare nulla o delegare a un’altra soluzione. Utilizza questo set per ogni test di non regressione.
Metadati che guidano il modello
- Il nome dovrebbe combinare il dominio e l’azione, ad esempio
calendar.create_event. - La descrizione dovrebbe iniziare con “Usa quando…” ed elencare esplicitamente i casi esclusi, come “Non usare per i promemoria”.
- Ogni parametro deve essere documentato con esempi e un elenco di valori consentiti se l’input è vincolato.
- Le annotazioni devono riflettere il comportamento effettivo (vedi Lezioni 3 e 11).
Misura, poi itera
Collega il tuo server, installa il plugin, esegui il tuo set di prompt e registra quale strumento è stato selezionato, quali argomenti sono stati passati e se è stato visualizzato qualche componente UI. Traccia due metriche: precisione (è stato chiamato lo strumento corretto?) e richiamo (lo strumento è stato chiamato ogni volta che avrebbe dovuto?). Punta prima a un’alta precisione sui prompt negativi prima di cercare guadagni marginali nel richiamo.
Modifica un solo campo alla volta per isolare ciò che guida il miglioramento. Tieni un registro delle revisioni datato con i risultati e fai rivedere le modifiche da qualcun altro prima del deployment. In produzione, rivedi l’utilizzo degli strumenti settimanalmente. Un picco nelle conferme di “strumento errato” segnala solitamente una deriva dei metadati. Raccogli il feedback degli utenti ed esegui nuovamente i tuoi test sui prompt regolarmente, specialmente dopo aver aggiunto un nuovo strumento o modificato un campo strutturato.
Competenze per flussi di lavoro ricorrenti
Il tuo server fornisce dati, autenticazione e azioni controllate. Una competenza (skill) fornisce la sequenza di chiamate agli strumenti, i punti decisionali, la formattazione dell’output, gli esempi e i modelli. Il modo più veloce per iniziare è utilizzare il creatore integrato @skill-creator, dove descrivi l’obiettivo dell’utente e gli strumenti MCP che lo supportano.
Un file SKILL.md solido specifica quali passaggi seguire, quale risultato dovrebbe ricevere l’utente, quali fatti il modello non deve inventare, quando porre domande, fermarsi o rifiutare, e quali file consultare. Preferisci una competenza focalizzata su un flusso di lavoro specifico rispetto a un ampio insieme di istruzioni disparate. Suddividi i flussi di lavoro che differiscono per trigger, input o criteri di successo. Mantieni SKILL.md conciso e archivia i dettagli altrove: usa references/ per policy, schemi ed esempi; assets/ per modelli da copiare o trasformare; e scripts/ per calcoli deterministici, ma solo se le istruzioni e gli strumenti esistenti sono insufficienti.
Se una competenza dipende da un server MCP, dichiara tale dipendenza in agents/openai.yaml. Questo rende lo strumento disponibile, ma non sostituisce la necessità di istruzioni chiare su quali strumenti usare, in quale ordine e come gestire risultati mancanti o ambigui. Per GPT-6 Astra, OpenAI consiglia di rivedere le sue linee guida sul rispetto delle istruzioni: elimina direttive vaghe o contraddittorie e rendi esplicito che le istruzioni dell’utente hanno la priorità sulle istruzioni della competenza.
Testa l’attivazione della competenza e la qualità dell’output utilizzando prompt diretti, indiretti, incompleti (che dovrebbero triggerare una domanda di chiarimento), fuori tema e casi limite in cui la competenza deve evitare allucinazioni o agire al di fuori del suo ambito. Se una competenza si attiva al momento sbagliato, correggine la descrizione. Se seleziona il flusso di lavoro giusto ma produce risultati incoerenti, correggine le istruzioni.
Eventi MCP: reagire ai cambiamenti
MCP Events consente a ChatGPT di iscriversi agli aggiornamenti dal tuo server, come nuovi messaggi, contenuti modificati o cambiamenti di stato. L’utente sceglie cosa monitorare e come ChatGPT dovrebbe reagire quando arriva un aggiornamento, ad esempio: “Monitora questo documento e applica le correzioni richieste nei commenti”.
- Il tuo server elenca gli eventi che supporta.
- L’utente dice a ChatGPT cosa monitorare e come reagire.
- ChatGPT si iscrive tramite il tuo server MCP, fornendo un URL di callback e un segreto di firma.
- Il tuo server invia gli eventi rilevanti a quell’URL.
- ChatGPT riceve l’evento nella conversazione iscritta e segue le istruzioni dell’utente.
Questa funzionalità è disponibile nelle conversazioni di ChatGPT Work sul web e nell’app desktop con Cloud selezionato. ChatGPT si basa sulla consegna webhook come definito nella bozza delle specifiche MCP Events. Il tuo server deve persistere le iscrizioni ed essere in grado di raggiungere gli URL di callback tramite HTTPS.
Estensioni dell’interfaccia di ChatGPT
Le OpenAI MCP Extensions consentono a un plugin di integrarsi in aree chiave dell’interfaccia di ChatGPT: la barra laterale, l’area di input e i visualizzatori di file. Le menzioni nell’area di input sono disponibili solo nell’app desktop. OpenAI pubblica un plugin di esempio, Bits & Bolts, che dimostra queste estensioni e ne traccia il deployment. È il punto di partenza migliore per esplorare questa capacità.
Punti chiave
- Tratta i metadati come testi di prodotto: usa un set di prompt di riferimento, traccia precisione e richiamo e modifica un campo alla volta.
- Scrivi descrizioni che iniziano con “Usa quando…”, elenca esplicitamente i casi esclusi e documenta tutti i parametri.
- Crea una competenza focalizzata per flusso di lavoro, mantieni
SKILL.mdconciso, archivia le risorse separatamente e dichiara le dipendenze MCP. - MCP Events iscrive ChatGPT agli aggiornamenti del tuo server, consegnati tramite webhook.
- Le estensioni integrano il tuo plugin nella barra laterale, nell’area di input e nei visualizzatori di file.
Metti alla prova le tue conoscenze
Dagli strumenti MCP alla pubblicazione: verifica di aver padroneggiato i fondamenti.
1. Ho bisogno del pacchetto `@openai/apps-sdk` per creare un'app in ChatGPT?
Risposta: No, quel pacchetto non esiste. Costruisci un server MCP utilizzando gli SDK ufficiali del protocollo (@modelcontextprotocol/sdk per TypeScript, mcp per Python), aggiungi opzionalmente un’interfaccia conforme allo standard MCP Apps e distribuisci il tutto come plugin.
2. Uno strumento può esistere senza una UI?
Risposta: Sì, e dovrebbe: uno strumento restituisce structuredContent e un breve riepilogo testuale, che è sufficiente per il modello. La UI, allegata tramite _meta.ui.resourceUri, viene aggiunta solo quando aiuta gli utenti a ispezionare, confrontare, modificare, confermare o navigare le informazioni.
3. Chi decide se un utente ha il permesso di accedere ai dati?
Risposta: Il server MCP decide su ogni richiesta, basandosi sul token OAuth verificato (firma, emittente, pubblico, scadenza, ambiti). Le annotazioni aiutano ChatGPT a scegliere il livello di conferma appropriato, ma non sostituiscono mai l’autorizzazione lato server.
4. Un plugin può vendere un abbonamento al proprio servizio?
Risposta: No. Le regole limitano il commercio ai beni fisici. Un abbonato esistente può accedere e utilizzare le funzionalità incluse nel suo piano. Il plugin può spiegare che una funzionalità non è inclusa e collegarsi a una pagina informativa, ma non deve mai collegarsi a una pagina di pagamento.
5. Come si aggiornano gli strumenti per un plugin pubblicato?
Risposta: Senza un nuovo file ZIP: OpenAI esegue nuovamente la scansione del server e qualsiasi strumento nuovo o modificato diventa disponibile dopo aver superato i controlli automatizzati. Uno strumento eliminato scompare immediatamente. Tuttavia, metadati e competenze richiedono un nuovo file ZIP e una nuova revisione.
Strumenti ben descritti, UI opzionali, autorizzazione lato server e rispetto delle regole: questo è il framework che rende un plugin un servizio affidabile in ChatGPT e Codex.