Cosa abbiamo imparato usando il ChatGPT Apps SDK

• L’Apps SDK è una soluzione pratica se vi serve presto un flusso di lavoro in ChatGPT o se volete testare lì i vostri strumenti prima di investire in uno stack personalizzato per agenti. Di solito non lo è, invece, se dovete controllare ogni aspetto del comportamento dell’agente.

• Scegliete l’Apps SDK quando ChatGPT deve essere l’interfaccia principale e volete combinare strumenti e piccoli elementi di UI senza creare un prodotto di chat completo. Scegliete uno stack per agenti proprietario quando vi serve uno stretto controllo su flusso, memoria, prompt e operazioni di scrittura.

• L’Apps SDK è adatto ai prodotti che combinano la chat con pochi e brevi passaggi nell’interfaccia. Si pubblica più rapidamente, rinunciando però a parte del controllo.

• Nel nostro caso hanno funzionato strumenti chiari, un comportamento chiaro dei widget e passaggi successivi ben definiti. Per definire il flusso ci siamo affidati a questi elementi, non all’LLM. Il modello è stato particolarmente utile per spiegare gli esiti già stabiliti dal sistema.

• Di seguito vedremo come scegliere, poi cosa ha funzionato e cosa no.

La maggior parte dei team conduce ancora progetti pilota di IA o la impiega in ambiti marginali, con un basso rapporto tra rischi e benefici. Pochi pubblicano un prodotto critico per l’azienda che gli utenti usano ogni settimana. Il ChatGPT Apps SDK può contribuire a colmare questa lacuna se l’obiettivo è entrare in ChatGPT anziché creare da zero l’intero assistente.

Le nostre conclusioni derivano da un progetto per un cliente i cui requisiti indicavano ChatGPT come interfaccia principale e richiedevano una soluzione rapida, senza finanziare un prodotto di chat completo e su misura.

Rispetto a questi requisiti, l’Apps SDK era adatto perché al cliente servivano:

• Nessun prodotto di chat dedicato da creare e ospitare: voleva raggiungere gli utenti dentro ChatGPT, non sviluppare l’involucro di un altro assistente autonomo.

• Chat e una piccola UI specifica per le attività: pochi passaggi mirati nei widget, non un secondo prodotto completo all’interno del flusso.

• Funzioni di backend esposte tramite strumenti MCP: chiamate standard agli strumenti, non un runtime personalizzato per agenti gestito interamente dal cliente.

• Visibilità dentro ChatGPT: gli utenti dovevano trovare il flusso di lavoro nell’ambiente che già utilizzavano.

Durante lo sviluppo abbiamo convalidato queste scelte insieme al cliente. Il compromesso resta valido: quando ChatGPT ospita la sessione, il runtime esterno non è sotto il vostro controllo. Potete orientarlo, ma non controllarlo completamente.

Un’app basata sull’Apps SDK collega tre elementi:

1. Il runtime per agenti di ChatGPT

2. I vostri strumenti MCP

3. L’interfaccia dei vostri widget

Il flusso in pratica:

1. L’utente chiede qualcosa a ChatGPT.

2. ChatGPT può chiamare uno dei vostri strumenti MCP.

3. Il server restituisce un risultato strutturato dello strumento.

4. ChatGPT legge il risultato e decide il passaggio successivo: altre chiamate agli strumenti, una risposta all’utente o entrambe le cose. Se avete associato un widget allo strumento, può essere visualizzato in questo turno.

5. L’utente prosegue nella chat o nel widget, con un testo di follow-up, una scelta o una chiamata a uno strumento attivata dal widget. Il thread viene aggiornato; ChatGPT esegue un altro turno e i passaggi 2–4 si ripetono finché l’attività non è completata.

Il punto è proprio questa combinazione di chat, azioni di backend e brevi passaggi nell’interfaccia. Significa anche che i punti più fragili sono i passaggi tra chat, strumenti e UI.

Non dovete ricreare da zero l’interfaccia della chat, il collegamento degli strumenti, i modelli di autenticazione o la struttura dei widget. Per molti prodotti, questo riduce notevolmente i tempi di sviluppo e permette di concentrarsi sulla logica di dominio e sui meccanismi di protezione.

Sviluppare dentro ChatGPT non equivale a gestire un agente proprietario. La parte difficile del progetto non riguardava espedienti per i prompt. Consisteva nel rendere strumenti, widget e passaggi successivi abbastanza espliciti da mantenere allineati il modello e la UI.

L’Apps SDK dà al prodotto una forma diversa rispetto a un frontend tradizionale, ma è importante capire per quali scenari è ideale.

Usate l’Apps SDK quando volete

• Pubblicare rapidamente un flusso di lavoro in ChatGPT.

• Lasciare che ChatGPT ospiti la conversazione.

• Combinare il linguaggio naturale con pochi passaggi mirati nell’interfaccia.

• Evitare di creare un’interfaccia di chat, un contenitore per l’agente e un sistema di visibilità proprietari.

Quest’ultimo punto è importante quando i vostri utenti lavorano già in ChatGPT.

Create un agente proprietario quando vi servono

• Un flusso fisso, passo dopo passo, che potete imporre tramite il codice.

• Una UI personalizzata e un percorso di conferma che controllate interamente.

• Un modello proprietario per memoria e stato.

• Un comportamento prevedibile a ogni esecuzione.

• Tracce, log e metriche dell’agente.

Se il pianificatore, i prompt di sistema e l’intero flusso di lavoro costituiscono il vostro prodotto, uno stack personalizzato è in genere la scelta migliore.

Durante il progetto, la parola ricorrente era «controllo»: da una parte velocità e un ambiente familiare, dall’altra il controllo solo parziale del runtime. Era il compromesso accettato dal cliente quando ha privilegiato la possibilità di raggiungere gli utenti in ChatGPT rispetto al controllo dell’intero stack.

Il percorso ideale sembra semplice: l’utente fa una richiesta, lo strumento viene eseguito, arrivano i dati e, quando occorre una scelta, compare il widget.

In pratica, i problemi riguardavano i passaggi tra i componenti. Un widget non è un elemento decorativo. Una volta visualizzato, cambia ciò che il modello vede e fa in seguito. Trattate le azioni dei widget come eventi con un nome, non come messaggi generici in chat.

Lo stack del progetto era semplice: FastMCP, Pydantic, React e TypeScript. La loro integrazione non ha creato problemi. La vera sfida era far concordare modello, strumenti e UI su cosa dovesse accadere dopo.

Rendete evidente ogni passaggio

Abbiamo smesso di considerare i risultati degli strumenti come payload non elaborati del backend. Ogni risultato restituito è diventato un passaggio di consegne.

Un buon risultato dello strumento:

• Fornisce al widget ciò che gli serve per il rendering.

• Fornisce a ChatGPT dati strutturati su cui basare la risposta.

• Quando il flusso lo richiede, indica cosa deve accadere dopo, evitando che il modello debba indovinarlo.

Le azioni dei widget non dovrebbero inserire nel thread testi vaghi. Dovrebbero indicare cosa ha fatto l’utente e cosa deve accadere dopo.

L’affidabilità è aumentata quando i passaggi sono diventati chiari.

Il modello segue istruzioni brevi e chiare quando sono incluse nell’output dello strumento e nelle azioni dei widget.

Di seguito è riportato un piccolo schema Pydantic che abbiamo usato. Il campo output contiene i dati strutturati necessari al widget, quando ne viene mostrato uno, e le informazioni che ChatGPT deve usare nella sessione. Il campo agent_directions contiene una breve indicazione di ciò che l’assistente deve fare dopo. Reason è facoltativo.

1from typing import Generic, TypeVar2
3from pydantic import BaseModel4
5T = TypeVar("T")6
7class AgentDirections(BaseModel):8 assistant_instruction: str9 reason: str | None = None10
11class ToolResults(BaseModel, Generic[T]):12 agent_directions: AgentDirections13 output: T

Mantenete i widget semplici

I widget più efficaci gestivano una sola decisione, poi restituivano il controllo. Elenchi brevi, conferme o una schermata di verifica essenziale hanno funzionato meglio che trasformare il widget in una mini-app. Un po’ di logica nel widget, come una semplice convalida o un passaggio successivo fisso, era comunque utile quando volevamo rendere il flusso più deterministico.

Messaggi dei widget in terza persona

Abbiamo smesso di scrivere i follow-up dei widget come messaggi dell’utente (“I selected…,” “I confirmed…”). Li abbiamo formulati come brevi resoconti delle azioni dell’utente (“The user selected…,” “The user confirmed…”). Abbiamo provato questo approccio perché ChatGPT aggiungeva i messaggi dei widget come messaggi dello strumento anziché dell’utente.

Azioni dirette quando il passaggio successivo è evidente

Se un pulsante implica chiaramente la chiamata successiva a uno strumento, lasciare che il widget la attivi direttamente ha funzionato meglio che imporre un altro turno di chat. Questo vale solo se la chiamata successiva allo strumento non richiede input da ChatGPT.

La soluzione ha permesso di imporre flussi deterministici e ha ridotto la latenza evitando un altro turno di chat.

Gestione degli errori

Quando una chiamata a uno strumento non riusciva, restituivamo i codici di errore MCP corretti e messaggi brevi e chiari dallo strumento. In questo modo, in caso di chiamata non riuscita, ChatGPT disponeva di informazioni concrete per spiegare il problema all’utente e/o scegliere un passaggio successivo sensato.

Gestione del contesto degli strumenti

Abbiamo mantenuto lo stato della sessione sul nostro server. ChatGPT invia con le chiamate agli strumenti il contesto della sessione; in FastMCP abbiamo assegnato a ogni strumento un parametro Context, così il gestore poteva leggere e aggiornare quello stato.

• Gli ID stabili e i risultati precedenti rimanevano nella sessione, anziché chiedere a ChatGPT di passarli di nuovo come argomenti dello strumento a ogni chiamata.

• Quando si verificavano cicli di chiamate agli strumenti, potevamo intercettare le chiamate duplicate e restituire un errore chiaro nel risultato dello strumento.

• I log delle sessioni rimanevano sui nostri sistemi per il debug e l’assistenza.

All’inizio mostravamo un widget, presumevamo che il modello «avesse capito» e aspettavamo la giusta chiamata di follow-up allo strumento. A volte accadeva. Spesso no.

Senza un passaggio chiaro, ChatGPT poteva riassumere quando volevamo un’azione, chiedere all’utente di ripetere una scelta o continuare a pianificare quando avrebbe dovuto fermarsi.

La soluzione era esplicitare il passaggio successivo nei risultati strutturati e nei payload dei widget, senza sperare che il modello lo deducesse.

Seguendo la documentazione dell’Apps SDK, abbiamo provato a suddividere in modo sofisticato le risposte tra output dello strumento, metadati nascosti e testo della chat. Tuttavia, i widget non potevano leggere i metadati nascosti. Non abbiamo quindi potuto usare questo approccio.

La documentazione dell’Apps SDK descrive strumenti che possono essere esclusi dall’elenco dell’agente, in modo che non li scelga, pur restando richiamabili dal widget. Quando abbiamo impostato la visibilità su app-only, quegli strumenti hanno smesso di essere disponibili anche dal widget, non soltanto dall’agente. Non siamo mai riusciti a configurare il sistema in modo che uno strumento fosse invisibile all’agente ma disponibile al widget.

Il silenzio o un generico «operazione riuscita» quando non accadeva nulla di utile erano peggio di un errore esplicito. Abbiamo quindi trattato gli errori degli strumenti e dei widget come output veri e propri: se un passaggio non poteva continuare, lo indicavamo con parole chiare e restituivamo un errore esplicito, anziché lasciare gli utenti davanti a un widget visualizzato ma incapace di farli proseguire. Questo ha migliorato l’usabilità e reso più affidabile il comportamento del modello.

Se il vostro obiettivo è creare un flusso di lavoro in ChatGPT riducendo lo sviluppo personalizzato della piattaforma, l’Apps SDK è una soluzione pratica. Rinunciate a parte del controllo in cambio di velocità e della possibilità di raggiungere gli utenti dove già lavorano.

Se dovete controllare ogni diramazione del flusso, la UI e chi decide ogni passaggio, prevedete fin dall’inizio uno stack proprietario per agenti. Probabilmente, prima o poi, sviluppare soltanto dentro ChatGPT non vi basterà più.

Potete anche usare l’Apps SDK per eseguire il vostro server MCP dentro ChatGPT prima di creare autonomamente chat, autenticazione e infrastruttura dell’agente, per poi passare a uno stack proprietario quando il prodotto lo richiederà.

Per i team nella stessa situazione, il passo successivo è scegliere un flusso con un risultato chiaro, documentare i passaggi tra chat, strumenti e widget, quindi sottoporre a stress test tentativi ed errori prima di dedicare troppo tempo all’ottimizzazione dei prompt.