Vəziyyətin idarə edilməsi — Widget State, ToolInput, ToolOutput

1. Niyə ümumiyyətlə vidcet vəziyyəti haqqında düşünmək lazımdır

Adi React‑tətbiqində siz buna alışmısınız: lokal state var, API sorğuları var, maksimum — hər hansı bir Zustand/Redux. Hər şey istifadəçinin brauzerində baş verir.

ChatGPT App-da vəziyyət fərqlidir. Sizin vidcetiniz — cəmi bir nazik UI təbəqəsidir və onun altında üç varlıq dayanır:

• ChatGPT modeli — nə vaxt App-ınızı çağıracağını və ona hansı arqumentləri verəcəyini qərarlaşdırır;
• MCP‑server/backend — real məlumatları saxlayır və biznes məntiqini icra edir;
• çat konteksti — bütün bunların yaşadığı mühit; bu kontekst saatlar, günlər və ya həftələr sonra yenidən açıla bilər.

Ona görə də “harada vəziyyət saxlanılır” — akademik deyil, çox praktik bir sualdır. Əgər hər şeyi yalnız React‑state-də saxlasanız, chatdakı ən kiçik dəyişiklikdə istifadəçi seçimini itirəcək. Əgər hər şeyi widgetState-ə yığsanız, model tonlarla JSON oxuyacaq və bunun əsasında şən “halüsinasiyalar” uydura bilər. Əksinə, hər şeyi serverdə saxlayıb hər pikseli yenidən istəsəniz — bu, həm yavaş, həm də baha olacaq.

Rəsmi tövsiyələr ChatGPT App vəziyyətini üç sinfə bölür: biznes məlumatları, efemer UI‑state və uzunömürlü, sessiyalar arası davamlı vəziyyət. Elə bununla da başlayaq.

2. ChatGPT App-da vəziyyət xəritəsi

Apps SDK sənədlərində üç növ state təsvir olunur. Onları bir cədvəl kimi yadda saxlamaq rahatdır:

Vacibdir: avtoritativ məlumatlar vidcetdə yox, serverdə qalmalıdır. Vidcet bu məlumatların görüntüsünü (snapshot) alətlərin (MCP tools) köməyi ilə alır və onu render edir, üzərinə isə lokal UI‑state tətbiq edir.

Bu mühazirədə fokusumuz məhz vidcetin gördükləridir:

• toolInput — çağırılan alətin giriş arqumentləri;
• toolOutput — serverdən gələn structuredContent (əsas məlumatlar);
• toolResponseMetadata — yalnız vidcetə görünən xidmət metaməlumatı _meta;
• widgetState — ChatGPT-nin mesajla birlikdə saxladığı UI‑vəziyyəti.

3. Vidcetə nə gəlir: ToolInput, ToolOutput, Metadata, WidgetState

Bu üç state tipi ChatGPT App-da platformanın window.openai-a yerləşdirdiyi və SDK hook-larına ötürdüyü konkret sahələrdə əks olunur. Praktikada siz onları React‑hook-ları ilə alacaqsınız, amma dəqiq tərifləri bilmək faydalıdır.

toolInput

Bu, alətin (tool) çağırılması zamanı modelin ötürdüyü arqumentlərdən ibarət obyektidir.

Məsələn, istifadəçi yazır:
“30 yaşlı qadın üçün hədiyyə ideyaları seç, büdcə 100 dollar”.
Model sizin gift_search alətinizi bu arqumentlərlə çağırmağa qərar verir:

{
  "recipient": "female",
  "age": 30,
  "budget": 100,
  "occasion": "birthday"
}

Məhz bu obyekti vidcet daxilində toolInput-da görəcəksiniz. Orada ssenarinin ilkin parametrləri saxlanılır — yəni App-ınızın ümumiyyətlə niyə işə salındığının səbəbi.

toolOutput

Bu — alətin icrası zamanı MCP‑serverinizin / backend-in qaytardığı structuredContent-dir.

Adətən bu cür JSON olur:

{
  "gifts": [
    { "id": "1", "title": "İslandiya üzrə bələdçi", "price": 45 },
    { "id": "2", "title": "Səyahətlər haqqında elektron kitab", "price": 20 }
  ],
  "total": 2
}

Məhz toolOutput — render üçün əsas mənbədir. Rəsmi olaraq vurğulanır: model bu sahəni sözbəsöz oxuyur, ona görə də onu yığcam və anlaşılan saxlayın.

toolResponseMetadata

Bu, alətin cavabındakı _meta-dır; window.openai vasitəsilə toolResponseMetadata kimi də əlçatandır. Sənədləşmə ayrıca qeyd edir ki, _meta-nın məzmununu yalnız vidcet görür, model isə almır.

Tipik nümunələr:

• sisteminizdən daxili ID-lər;
• UI üçün bayraqlar (məsələn, “keşdən istifadə edildimi”);
• sazlama üçün xidmət mesajları.

Qısası: toolOutput — “istifadəçiyə və modelə nə demək lazımdır”, _meta isə — “yalnız vidcet və loglar üçün lazımlı olan şeylər”.

widgetState

Bu, ChatGPT‑nin konkret vidcet üçün renderlər arasında UI‑vəziyyətinin şəklini saxladığı JSON obyektidir.

Onun xüsusiyyətləri:

• ChatGPT tərəfində yaşayır və konkret message/widgetId-ə bağlıdır;
• eyni mesaj yenidən açıldıqda bərpa olunur;
• həm vidcetə, həm də modelə görünür (yəni widgetState-dəki məlumatlar LLM kontekstinə daxil olur);
• təxminən 4k token ölçü məhdudiyyəti var, ona görə də ora hər şeyi yığmaq və ya nəhəng siyahılar saxlamaq olmaz.

Vacibdir: widgetState — sirlər üçün yer deyil. Oraya nə tokenlər, nə də PII‑məlumatlar qoymaq olmaz, çünki model onları görəcək və platforma bunu təhlükəsiz saxlama kimi nəzərdə tutmur.

4. Lokal React‑state: harada hələ də lazımdır

toolOutput və widgetState ətrafındakı sehrə baxmayaraq, vidcet daxilində siz hələ də adi React yazırsınız — useState, useReducer, useRef və s. Fərq yalnız bundadır ki:

• lokal state, konkret render/iframe yaşadığı müddətdə yaşayır;
• model onu ümumiyyətlə görmür;
• vidcet demontaj olunduqda (istifadəçi başqa chata keçdi, yenidən rəngləndi, səhifə yeniləndi) lokal state yox olur.

Lokal state aşağıdakılar üçün çox uyğundur:

• ani şeylər — hover, seçilmiş tab, açıq dropdown;
• “Davam et”/“Yadda saxla” basılana qədər formaya daxil edilən dəyərlər;
• isSubmitting və ya isTooltipOpen kimi müvəqqəti bayraqlar.

Tədris App-ımız GiftGenius — hədiyyə seçimi köməkçisində kiçik bir nümunə:

const [selectedGiftId, setSelectedGiftId] = useState<string | null>(null);

return (
  <div>
    {gifts.map(gift => (
      <button
        key={gift.id}
        onClick={() => setSelectedGiftId(gift.id)}
      >
        {gift.title}
      </button>
    ))}
  </div>
);

“Seçimi təsdiqlə” düyməsinə basılmayana qədər bu, lokal state üçün əla namizəddir. Amma seçim vidcet yenilənmələri arasında “yaşasın” istəyirsinizsə, onda widgetState haqqında düşünmək lazımdır.

5. widgetState: renderlər arasında vidcet yaddaşı

widgetState — platformanın özü tərəfindən saxlanan həmin “yaddaşdır”. UI-də mühüm hərəkət zamanı setWidgetState çağıraraq bu JSON-u saxlatdıra bilərsiniz: ChatGPT onu mesajla birlikdə saxlayır. Eyni vidcet növbəti dəfə render olunanda (məsələn, istifadəçi çat tarixçəsini geri çəkib sonra qaytaranda) SDK bu obyekti bərpa edib sizə ötürəcək.

Dəqiq desək, birbaşa window.openai.widgetState və window.openai.setWidgetState ilə işləmək olar, amma bu mühazirədə tövsiyə olunan yolu — SDK qatındakı React‑hook-larını istifadə edirik.

useWidgetState hook-u

Belə hook-lardan biri məhz widgetState-i örtür. O:

• başlanğıc dəyəri ya window.openai.widgetState-dən, ya da ötürülən defaultState-dən götürür;
• hostdan gələn yeniləmələrə abunə olur;
• sizin hər setWidgetState çağırışınızda yeni dəyəri window.openai.setWidgetState vasitəsilə yuxarı sinxronlaşdırır.

Vidcet komponenti daxilində tipik istifadə nümunəsi (sintaksis şablonda bir az fərqlənə bilər, ideya eynidir):

import { useWidgetState } from "@openai/chatgpt-apps-sdk/react";

type GiftUiState = { likedIds: string[] };

const [uiState, setUiState] = useWidgetState<GiftUiState>(() => ({
  likedIds: [],
}));

İndi uiState aşağıdakı hallardan sonra belə bərpa olunacaq:

• çat yığılıb/açılıbsa;
• başqa dialoqa keçilib qayıdılıbsa;
• səhifə yenilənibsə (platforma həmin vidceti bərpa etməyi qərar verərsə).

Nümunə: seçilmiş hədiyyəni yadda saxlamaq

toolOutput-dakı hədiyyə siyahısını götürək və seçilmiş hədiyyəni widgetState-də yadda saxlayaq ki, itirilməsin.

type Gift = { id: string; title: string; price: number };

const [uiState, setUiState] = useWidgetState<{ selectedId: string | null }>(() => ({
  selectedId: null,
}));

return (
  <ul>
    {gifts.map(gift => (
      <li
        key={gift.id}
        style={{
          fontWeight: uiState?.selectedId === gift.id ? "bold" : "normal",
        }}
        onClick={() => setUiState({ selectedId: gift.id })}
      >
        {gift.title}
      </li>
    ))}
  </ul>
);

Burada vacib məqam: setUiState təkcə lokal React‑state-i dəyişmir, həm də, əgər mümkündürsə, pərdəarxasında window.openai.setWidgetState çağırır.

İstifadəçi sonradan bu vidcet altında follow‑up düyməsinə basarsa, ChatGPT eyni widgetId və eyni widgetState ilə dialoqu davam etdirə bilər və model hansı hədiyyənin seçildiyini görəcək.

6. Alət məlumatlarını React-də oxumaq: useWidgetProps və analoqları

Hər komponentin window.openai.toolOutput-a əl ilə girməməsi üçün Apps SDK-da daha bir faydalı qat var — useWidgetProps hook-u. O, toolOutput-u qlobaldan götürür, sizə tiplənmiş obyekt verir və istəsəniz defolt dəyərlər də əlavə edir.

Simplifikasiya olunmuş siqnatursu belə görünür:

export function useWidgetProps<T>(defaultState?: T | () => T): T {
  const toolOutput = useOpenAIGlobal("toolOutput") as T;
  return toolOutput ?? defaultState ?? null;
}

Yəni içəridə sizə sadəcə toolOutput T tipi kimi qaytarılır.

Tutaq ki, bizim MCP‑alət structuredContent-i belə qaytarır:

type GiftToolOutput = {
  gifts: { id: string; title: string; price: number }[];
  currency: string;
};

Vidcet bunu belə oxuya bilər:

import { useWidgetProps } from "@openai/chatgpt-apps-sdk/react";

export function GiftListWidget() {
  const { gifts, currency } = useWidgetProps<GiftToolOutput>(() => ({
    gifts: [],
    currency: "USD",
  }));

  if (!gifts.length) {
    return <div>Hələ uyğun ideyalar yoxdur. Başqa sorğu verin.</div>;
  }

  return (
    <ul>
      {gifts.map(gift => (
        <li key={gift.id}>
          {gift.title} — {gift.price} {currency}
        </li>
      ))}
    </ul>
  );
}

Burada bir neçə yaxşı praktika var:

• toolOutput-un artıq mütləq gələcəyini fərz etmirik — defolt dəyər veririk;
• boş siyahını səliqə ilə emal edirik;
• window.openai-a birbaşa giriş yoxdur — hər şey hook vasitəsilədir.

7. UI‑ni toolOutput ilə sinxronlaşdırmaq: yüklənmə, boş məlumat, xətalar

Real dünyada toolOutput həmişə ani gəlmir və həmişə “ideal” olmur. Apps SDK sənədləşməsi açıq-aşkar üç vəziyyəti nəzərdə saxlamağı tövsiyə edir: yüklənmə, normal məlumat, xəta/boş.

Ən sadə pattern:

type GiftToolOutput = {
  gifts: { id: string; title: string }[];
  error?: string;
};

const data = useWidgetProps<GiftToolOutput | null>(() => null);

if (data === null) {
  return <div>Hədiyyə ideyaları yüklənir…</div>;
}

if (data.error) {
  return <div>Xəta: {data.error}</div>;
}

if (!data.gifts.length) {
  return <div>Kriteriyalarınıza uyğun heç nə tapılmadı.</div>;
}

return (
  <ul>
    {data.gifts.map(gift => (
      <li key={gift.id}>{gift.title}</li>
    ))}
  </ul>
);

Bu yanaşma serverin və modelin aləti yenidən çağırması ilə yaxşı birləşir — siz yeni toolOutput alacaqsınız. Vidcet onda sadəcə useWidgetProps vasitəsilə yeni dəyəri götürüb yenidən render edəcək.

Ümumi axın təxminən belə görünür:

İstifadəçi → sorğu
      ↓
Model → MCP alətini çağırır
      ↓
Server → hesablama aparır, DB/inteqrasiyalara gedir, structuredContent və _meta qaytarır
      ↓
ChatGPT → structuredContent-i toolOutput-a yerləşdirir
      ↓
Vidcet → UI-ni toolOutput + widgetState-dən render edir

Server üzrə rəsmi bələdçi “User → Model → MCP tool → widget iframe” diaqramına çox bənzər bir şəkil çəkir; burada toolOutput — vidcet üçün əsas girişdir.

8. Çoxaddımlı ssenari: cari addım widgetState-də

Bizim GiftGenius yəqin ki, bir kartla məhdudlaşmayacaq. Çox vaxt “wizard” lazımdır: əvvəlcə üstünlükləri toplamaq, sonra büdcəni müəyyənləşdirmək, sonda isə konkret variantlar təklif etmək.

Wizard addımının nömrəsini saxlamağın məntiqli yolu — widgetState-dədir. Sənədlərdə və nümunələrdə də məhz belə tövsiyə olunur.

İki addımlı mini‑wizard nümunəsi:

type GiftWizardState = {
  step: 1 | 2;
  budget?: number;
};

const [state, setState] = useWidgetState<GiftWizardState>(() => ({ step: 1 }));

if (state.step === 1) {
  return (
    <div>
      <label>
        Büdcə, $
        <input
          type="number"
          defaultValue={state.budget ?? 50}
          onBlur={e =>
            setState({ step: 2, budget: Number(e.target.value) || 50 })
          }
        />
      </label>
    </div>
  );
}

return (
  <div>
    <div>{state.budget} $-dək hədiyyələr axtarıram…</div>
    {/* burada artıq hədiyyələrlə toolOutput-u render edə bilərdik */}
  </div>
);

Burada maraqlı məqamlar:

• ilk göstərilişdə step 1-dir, istifadəçi büdcəni daxil edir;
• onBlur-dan sonra widgetState-i { step: 2, budget: … } olaraq yeniləyirik;
• növbəti renderdə (hətta bir dəqiqə sonra və ya eyni mesaj yenidən açıldıqda) vidcet dərhal addım 2‑yə keçəcək və büdcə yadda saxlanmış olacaq.

Daha inkişaf etmiş versiyada siz ikinci addımda artıq useCallTool ilə aləti işə salır, ora budget ötürür və nəticəni toolOutput-dan oxuyursunuz. Amma bu, alətlər mövzusuna (Modul 4) istinaddır; bu gün əsas məsələ — addım məlumatını harada saxladığımızdır.

9. Nə hara qoyulur: “nazik UI, qalın backend” pattern-i

Rolların bölgüsünü ümumiləşdirək:

• avtoritativ məlumatlar (hədiyyə siyahısı, sifariş statusları) serverdə yaşayır və toolOutput ilə gəlir;
• müvəqqəti vizual şeylər (spoylerin açıq olub-olmaması, tamamlanmamış girişin cari məzmunu) lokal React‑state-də yaşayır;
• eyni vidcet daxilində davamlı UI qərarları (cari addım, seçilmiş element, çeşidləmə) widgetState-də yaşayır;
• istifadəçinin uzunmüddətli parametrləri (çatlar arasında; sevimli kateqoriya, son valyuta) sizin backend-də persistent state kimi yaşayır.

Bəzən “böyük bir hər şey obyekti” hazırlayıb onu widgetState-ə qoymaq və rahat yaşamaq istəyirsiniz. Amma bu, pis fikirdir. Sənədləşmə vurğulayır ki, widgetState vasitəsilə ötürdüyünüz vəziyyət tam şəkildə modelin kontekstinə daxil olur və yüngül, əsasən UI ilə bağlı olmalıdır.

Eyni şey toolOutput-a da aiddir: ora yalnız vidcetə və modelə istifadəçiyə baş verənləri izah etmək üçün lazım olan məlumatları qoyun. Böyük ağaclar, binar bloblar, digər API-lərin xam cavabları — bunlar modeldən qəribə və baha başa gələn cavablara aparan birbaşa yoldur.

Insight

ChatGPT vidceti daxilində klassik kliyen identifikasiyası mexanizmlərinə etibar etmək mümkün deyil. Cookies faktiki olaraq əlçatan deyil: vidcet ChatGPT-də sandbox kimi üçüncü tərəf resursu olaraq yüklənir və müasir brauzerlər üçüncü tərəf cookie-lərini (third-party cookies) defolt olaraq bloklayır. Buna görə də cookie vasitəsilə vəziyyəti saxlamaq cəhdləri işləmir.

Eksperimental olaraq yoxlanılıb: localStorage əla işləyir, tətbiqlərinizi layihələndirərkən ona arxalana bilərsiniz.

10. Kiçik ucdan-uca nümunə: davamlı seçimlə GiftGenius

Hamısını bir mini‑vidcetdə birləşdirək, hansı ki:

• toolOutput-dan məlumatları oxuyur;
• istifadəçi seçimini widgetState-də saxlayır;
• boş məlumatı səliqə ilə emal edir.

import {
  useWidgetProps,
  useWidgetState,
} from "@openai/chatgpt-apps-sdk/react";

type Gift = { id: string; title: string; price: number };
type GiftToolOutput = { gifts: Gift[]; currency: string; error?: string };

export function GiftWidget() {
  const data = useWidgetProps<GiftToolOutput | null>(() => null);
  const [uiState, setUiState] = useWidgetState<{ selectedId: string | null }>(
    () => ({ selectedId: null })
  );

  if (data === null) {
    return <div>Bir saniyə, ideyalar seçilir…</div>;
  }
  if (data.error) {
    return <div>Xəta: {data.error}</div>;
  }
  if (!data.gifts.length) {
    return <div>Təəssüf ki, heç nə tapılmadı. Başqa sorğu verin.</div>;
  }

  return (
    <ul>
      {data.gifts.map(gift => (
        <li
          key={gift.id}
          style={{
            fontWeight: uiState?.selectedId === gift.id ? "bold" : "normal",
            cursor: "pointer",
          }}
          onClick={() => setUiState({ selectedId: gift.id })}
        >
          {gift.title} — {gift.price} {data.currency}
        </li>
      ))}
    </ul>
  );
}

Bu kod artıq real vidcetə xeyli yaxındır:

• alət hələ icra olunursa, “ideyalar seçilir” görürük;
• server xəta qaytarıbsa — onu dürüst göstəririk;
• hədiyyə yoxdursa — boş nəticəni düzgün emal edirik;
• seçilmiş hədiyyə widgetState-də yadda qalır və model dialoqun növbəti addımlarında onu istifadə edə bilər.

Sonra siz “Bu hədiyyə ilə davam et” (follow‑up) düymələri, yeni alətlərin işə salınması və s. əlavə edə biləcəksiniz — artıq seçim vəziyyətdə oturduğuna söykənərək.

Nəticədə ChatGPT App-da yaxşı vəziyyət arxitekturası sadə bir ideyaya gəlir: biznes məlumatları serverdə yaşayır, cari şəkil toolOutput vasitəsilə gəlir, müvəqqəti UI — lokal useState-də, bir mesaja bağlı, lakin davamlı vidcet konteksti isə widgetState-də. Bu sxemi yadda saxlamaq və “hamısını bir qata” yığmağa cəhd etməmək vidceti həm istifadəçi, həm də model üçün proqnozlaşdırılan edir.

11. Widget State, ToolInput və ToolOutput ilə işləyərkən tipik səhvlər

Səhv №1: Biznes məlumatlarını widgetState-də saxlamaq, serverdə yox.
Bəzən widgetState-də bütöv obyekt siyahısını saxlamaq istəyirsiniz ki, serveri təkrar çağırmayasınız. Bu iki səbəbdən pisdir: avtoritativ məlumatı dublikat edirsiniz (server və vidcet fərqli istiqamətlərə gedə bilər) və model kontekstini şişirdirsiniz, çünki widgetState tam halda ora daxil olur. Ən yaxşısı — real məlumatlar serverdə qalır və təzə toolOutput snapshot kimi qaytarılır.

Səhv №2: widgetState-ə sirləri və ya PII qoymaq.
widgetState-in məzmununu model gördüyünə və bu, qorunan saxlama kimi nəzərdə tutulmadığına görə ora tokenlər, loginlər, e‑mail-lər, telefonlar və digər konfidensial məlumatlar qoymaq olmaz. Belə şeylər serverdə yaşamalıdır, widgetState-də isə maksimum işlədiyiniz yazının ID-si saxlanıla bilər, qalanı MCP vasitəsilə həll edilir.

Səhv №3: toolOutput-un həmişə mövcud və həmişə korrekt olduğunu zənn etmək.
toolOutput.gifts[0]-a yoxlamasız girməyə çalışan vidcet gec-tez sıradan çıxacaq: alət xəta qaytara, boş massiv göndərə və ya strukturu dəyişə bilər. “Yüklənmə”, “boş”, “xəta” vəziyyətlərini açıq şəkildə emal etmək, yalnız bundan sonra normal render etmək tövsiyə olunur.

Səhv №4: toolOutput-u zərurət olmadan lokal state-ə kopyalamaq.
Bəzən belə etmək cazibədardır: const [data, setData] = useState(toolOutput) və sonra yalnız bu data ilə yaşamaq. Nəticədə siz ikinci “həqiqət mənbəyi” yaradırsınız: yeni toolOutput gələndə lokal state bunu bilməyəcək və UI köhnə məlumatları göstərməyə davam edəcək. Yaxşısı — toolOutput-u birbaşa useWidgetProps-dan oxumaq və ya render zamanı ondan törəyən vəziyyət (mapping, filter) yaratmaqdır, bütöv obyekti təkrarlamadan.

Səhv №5: Yalnız lokal useState istifadə etmək, halbuki widgetState lazımdır.
Klassik bug: kiçik bir wizard hazırlayırsınız, currentStep-i lokal state-də saxlayırsınız, test edirsiniz — hər şey işləyir. Sonra istifadəçi çatda irəli‑geri hərəkət edir, qayıdır — və birdən-birə yenidən birinci addım. Səbəb sadədir: lokal state vidcet demontajını “yaşamadı”. Ssenaridə önəmli olan addımlar üçün widgetState saxlamaq lazımdır ki, platforma bunu mesajla birlikdə bərpa etsin.

Səhv №6: window.openai-a hər komponentdə birbaşa müraciət etmək.
Formal olaraq bu işləyir, amma siz qlobala sərt bağlılıq, sazlaması çətin kod və əl ilə yazılmış hadisə abunələri əldə edirsiniz. Rəsmi materiallar və nümunələr (useWidgetProps, useWidgetState, useOpenAiGlobal) kimi hook qatından istifadə etməyi məsləhət görür — bunlar bütün detalları kapsullaşdırır və daha rahat test olunur.

Səhv №7: vidcetlərin message‑scoped təbiətini nəzərə almamaq.
İstifadəçi follow‑up basmır, sadəcə chata yeni mesaj yazırsa, ChatGPT yeni vidcet nümunəsi yaradır — yeni widgetId və boş widgetState ilə. “Əbədi” vidcet yaddaşına güvənən ssenarilər qəribə davranmağa başlayır. Burada ya sessiyalar arası konteksti serverdə saxlamaq, ya da UX-i follow‑up və ssenarinin açıq davamı ətrafında qurmaq lazımdır.