Ce am învățat lansând cu SDK-ul ChatGPT Apps

• SDK-ul Apps este o opțiune practică dacă ai nevoie rapid de un flux de lucru în ChatGPT sau dacă vrei să-ți testezi instrumentele acolo înainte de a investi într-o infrastructură personalizată de agenți. Dacă trebuie să controlezi fiecare aspect al comportamentului agentului, nu este alegerea potrivită, de regulă.

• Poți alege SDK-ul Apps când ChatGPT trebuie să fie interfața principală și dorești instrumente plus mici elemente de UI, fără să creezi un produs complet de chat. Alege-ți propria infrastructură de agenți când ai nevoie de control strict asupra fluxului, memoriei, solicitărilor și operațiunilor de scriere.

• SDK-ul Apps este potrivit pentru produsele care combină chatul cu câțiva pași scurți în UI. Lansezi mai repede, dar renunți la o parte din control.

• Pentru noi au funcționat instrumentele clare, comportamentul clar al widgeturilor și pașii următori bine definiți. Pe ele ne-am bazat pentru a defini fluxul, nu pe LLM. Modelul a fost cel mai util când a explicat rezultate pe care sistemul le alesese deja.

• Mai jos: cum să alegi, apoi ce a funcționat și ce nu.

Majoritatea echipelor încă derulează proiecte-pilot de IA sau folosesc IA în scopuri periferice, cu riscuri și beneficii reduse. Puține lansează un produs esențial pentru afacere pe care utilizatorii îl folosesc săptămânal. SDK-ul ChatGPT Apps este o modalitate de a reduce acest decalaj dacă obiectivul este să ajungi în ChatGPT, nu să construiești singur întregul asistent.

Concluziile noastre provin dintr-un proiect pentru un client ale cărui cerințe indicau ChatGPT drept interfață principală și impuneau o cale rapidă, fără finanțarea unui produs de chat complet personalizat.

SDK-ul Apps a corespuns acestor cerințe deoarece clientul:

• Nu avea nevoie să dezvolte și găzduiască un produs de chat dedicat, ci să intre în ChatGPT, nu să creeze un alt asistent independent.

• Avea nevoie de chat cu un UI restrâns și adaptat sarcinii, câțiva pași bine definiți în widget și nu încă un produs complet în cadrul fluxului de lucru.

• Avea nevoie de funcționalități backend expuse prin instrumente MCP, adică apelarea standard a instrumentelor, nu un mediu de execuție personalizat pentru agenți, gestionat integral.

• Avea nevoie de descoperire în ChatGPT, deci utilizatorii trebuiau să găsească fluxul de lucru acolo unde lucrau deja.

Am validat aceste alegeri împreună cu clientul pe parcursul dezvoltării. Compromisul rămâne valabil: când ChatGPT găzduiește sesiunea, nu controlezi mediul de execuție exterior. Îl îndrumi, dar nu îl controlezi complet.

O aplicație bazată pe SDK-ul Apps conectează trei elemente:

1. Mediul de execuție pentru agenți al ChatGPT

2. Instrumentele MCP

3. UI-ul widgetului

Fluxul în practică:

1. Utilizatorul îi solicită ceva lui ChatGPT.

2. ChatGPT poate apela unul dintre instrumentele tale MCP.

3. Serverul tău returnează un rezultat structurat al instrumentului.

4. ChatGPT citește rezultatul și decide pasul următor: alte apelări de instrumente, un răspuns pentru utilizator sau ambele. Dacă ai asociat un widget instrumentului respectiv, acesta poate apărea în această tură.

5. Utilizatorul continuă în chat sau în widget, printr-un mesaj ulterior, o opțiune sau o apelare de instrument declanșată de widget. Astfel se actualizează firul; ChatGPT execută o nouă tură, iar pașii 2–4 se repetă până la finalizarea sarcinii.

Tocmai această combinație de chat, acțiuni backend și pași scurți în UI este esențială. Înseamnă și că punctele fragile sunt transferurile dintre chat, instrumente și UI.

Nu trebuie să reconstruiești de la zero UI-ul de chat, conectarea instrumentelor, mecanismele de autentificare sau cadrul widgetului. Pentru multe produse, aceasta reduce considerabil timpul de dezvoltare și-ți permite să te concentrezi pe logica domeniului și pe mecanismele de protecție.

Dezvoltarea în ChatGPT nu este același lucru cu administrarea propriului agent. Partea dificilă a proiectului nu a fost găsirea unor trucuri pentru solicitări. A fost necesar să definim instrumentele, widgeturile și pașii următori suficient de clar pentru ca modelul și UI-ul să rămână sincronizate.

SDK-ul Apps oferă un tip de produs diferit de interfața frontend obișnuită, dar este important să știi pentru ce scenarii este ideal.

Folosește SDK-ul Apps când vrei să

• Lansezi rapid un flux de lucru în ChatGPT.

• Îi permiți lui ChatGPT să găzduiască conversația.

• Combini limbajul natural cu câțiva pași bine definiți în UI.

• Nu-ți crea propria interfață de chat, propriul container pentru agenți și propriul mecanism de descoperire.

Ultimul aspect e important când utilizatorii tăi folosesc deja ChatGPT.

Creează-ți propriul agent când ai nevoie de

• Un flux fix, pas cu pas, pe care să-l poți implementa în cod.

• Un UI personalizat și un proces de confirmare pe care le controlezi integral.

• Propriul model de memorie și stare.

• Un comportament care trebuie să fie previzibil la fiecare rulare.

• Urme, jurnale și indicatori pentru agent.

Dacă produsul tău constă în planificator, mesajele de sistem și fluxul de lucru complet, un stack personalizat este, de obicei, cea mai potrivită soluție.

În proiectul nostru, cuvântul care revenea constant era „control”: pe de o parte, viteză și o platformă familiară; pe de altă parte, control parțial asupra mediului de execuție. Acesta a fost compromisul acceptat de client când a acordat prioritate întâlnirii utilizatorilor în ChatGPT, nu controlului asupra întregii infrastructuri.

Scenariul ideal pare simplu: utilizatorul cere ceva, instrumentul rulează, datele revin, iar widgetul apare când trebuie făcută o alegere.

În practică, problemele au apărut la transferuri. Un widget nu este un simplu element decorativ. Odată afișat, schimbă ceea ce vede modelul și ce face în continuare. Tratează acțiunile widgeturilor ca pe niște evenimente denumite, nu ca pe o conversație informală.

Infrastructura proiectului era simplă: FastMCP, Pydantic, React și TypeScript. Integrarea lor nu a ridicat probleme. Adevărata provocare a fost ca modelul, instrumentele și UI-ul să stabilească împreună ce urmează.

Ne-am asigurat că fiecare transfer este clar

Am încetat să tratăm rezultatele instrumentelor drept simple date brute de la backend. Fiecare rezultat a devenit un transfer.

Un rezultat solid al instrumentului:

• Îi oferă widgetului datele necesare pentru afișare.

• Îi oferă lui ChatGPT date structurate pe care să-și bazeze răspunsul.

• Când fluxul o impune, precizează ce trebuie să urmeze, astfel încât modelul să nu fie nevoit să ghicească.

Acțiunile widgetului nu ar trebui să trimită în fir formulări vagi. Ele trebuie să precizeze ce a făcut utilizatorul și ce urmează să se întâmple.

Fiabilitatea a crescut după ce transferurile au devenit clare.

Modelul urmează instrucțiuni scurte și clare când acestea se află în rezultatul instrumentului și în acțiunile widgetului.

Mai jos este o structură Pydantic simplă pe care am folosit-o. Câmpul output conține datele structurate necesare widgetului atunci când afișați unul, precum și informațiile pe care ChatGPT trebuie să le folosească în sesiune. Câmpul agent_directions conține o instrucțiune scurtă care precizează ce trebuie să facă asistentul în continuare. Câmpul Reason este opțional.

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

Păstrează widgeturile simple

Widgeturile care au funcționat gestionau o singură decizie, apoi returnau controlul. Listele scurte, confirmările și ecranele de verificare concise au funcționat mai bine decât transformarea widgetului într-o miniaplicație. Puțină logică în widget, precum validarea simplă sau un pas următor fix, ne-a ajutat totuși când am dorit un flux mai determinist.

Persoana a treia în mesajele widgetului

Am renunțat să mai scriem mesaje de urmărire pentru widgeturi sub forma unor dialoguri cu utilizatorul („Am selectat…”, „Am confirmat…”). Le-am reformulat sub forma unor rapoarte scurte despre acțiunile utilizatorului („Utilizatorul a selectat…”, „Utilizatorul a confirmat…”). Am încercat această abordare deoarece ChatGPT adăuga mesajele widgeturilor ca mesaje ale instrumentului, în loc de mesaje ale utilizatorului.

Acțiuni directe când pasul următor este evident

Dacă un buton indică în mod clar următoarea apelare a unui instrument, a funcționat mai bine ca widgetul să-l declanșeze direct, fără a impune încă o tură de chat. Acest lucru este valabil numai dacă următoarea apelare de instrument nu necesită date de la ChatGPT.

Astfel am putut impune fluxuri deterministe și am redus latența, evitând încă o tură de chat.

Gestionarea erorilor

Când un apel de instrument eșua, returnam codurile de eroare MCP corecte și mesaje scurte și clare din instrument. Astfel, ChatGPT primea informații reale despre apelurile eșuate și putea să explice problema utilizatorului și/sau să aleagă un pas următor potrivit.

Gestionarea contextului instrumentelor

Am păstrat starea sesiunii pe serverul nostru. ChatGPT trimite contextul sesiunii odată cu apelurile de instrumente; în FastMCP, i-am oferit fiecărui instrument un parametru Context, astfel încât handlerul să poată citi și actualiza starea.

• ID-urile stabile și rezultatele anterioare au fost păstrate în sesiune, în loc să-i cerem lui ChatGPT să le transmită din nou ca argumente la fiecare apelare.

• Când apăreau bucle de apelare a instrumentelor, puteam detecta apelurile duplicate și returna o eroare clară prin rezultatul instrumentului.

• Jurnalele sesiunilor au rămas la noi pentru depanare și asistență.

La început afișam un widget, presupuneam că modelul „a înțeles” și așteptam apelarea ulterioară corectă a instrumentului. Uneori se întâmpla. Deseori nu se întâmpla.

Fără un transfer clar, ChatGPT putea să rezume când doream o acțiune, să-i ceară utilizatorului să repete alegerea sau să continue planificarea când ar fi trebuit să se oprească.

Soluția a constat în specificarea clară a următorului pas în ieșirile structurate și în conținutul widgeturilor, nu în a spera că modelul îl va deduce.

Am încercat o abordare sofisticată, împărțind răspunsurile între rezultatul instrumentului, metadatele ascunse și textul din chat, conform documentației SDK-ului Apps. Însă nu am putut citi metadatele ascunse în widgeturi. Prin urmare, nu am putut folosi această abordare.

Documentația SDK-ului Apps descrie instrumente care pot fi excluse din lista agentului pentru ca acesta să nu le selecteze, dar care pot fi apelate în continuare din widget. Când am setat vizibilitatea la app-only, instrumentele respective nu au mai fost disponibile nici din widget, nu doar pentru agent. Nu am reușit să obținem o configurație în care agentul să nu vadă un instrument, dar widgetul să-l poată folosi.

Lipsa unui mesaj sau un „succes” generic când nu se întâmplase nimic util erau mai rele decât o eroare directă. De aceea, am tratat eșecurile instrumentelor și widgeturilor drept rezultate de sine stătătoare: dacă un pas nu a putut continua, am explicat clar situația și returnam o eroare explicită, în loc să lăsăm utilizatorii în fața unui widget afișat care nu îi va ajuta să avanseze. Acest lucru a îmbunătățit ușurința în utilizare și a făcut comportamentul modelului mai fiabil.

Dacă obiectivul este un flux de lucru în ChatGPT cu mai puțină dezvoltare personalizată a platformei, SDK-ul Apps oferă o soluție practică. Renunță la o parte din control în schimbul vitezei și al accesului la utilizatori acolo unde lucrează deja.

Dacă trebuie să controlezi fiecare ramură a fluxului, UI-ul și entitatea care decide fiecare pas, planifică-ți de la început propria infrastructură de agenți. Probabil că, în timp, dezvoltarea exclusiv în ChatGPT nu-ți va mai fi suficientă.

De asemenea, poți folosi SDK-ul Apps pentru a rula serverul MCP în ChatGPT înainte de a crea singur chatul, autentificarea și infrastructura agentului, apoi poți trece la propria ta infrastructură când produsul o cere.

Următorul pas pentru echipele aflate în aceeași situație: alege un flux de lucru cu un rezultat clar, documentează transferurile dintre chat, instrumente și widgeturi, apoi testează intens reîncercările și erorile înainte să investești timp în ajustarea solicitărilor.