Керування станом — Widget State, ToolInput, ToolOutput

1. Навіщо взагалі думати про стан віджета

У звичайному React‑застосунку ви до цього звикли: є локальний стан, є API‑запити, максимум — якийсь Zustand або Redux. Усе крутиться навколо браузера користувача.

У ChatGPT App ситуація інша. Ваш віджет — це лише тонкий UI‑шар над трьома іншими сутностями:

• моделлю ChatGPT, яка вирішує, коли взагалі викликати ваш App і які аргументи йому передати;
• MCP‑сервером / бекендом, який зберігає справжні дані та виконує бізнес‑логіку;
• контекстом чату, у якому все це «живе» й може повторно відкриватися за годину, день або тиждень.

Тому питання «де лежить стан» — не академічне, а суто практичне. Якщо тримати все лише в React‑стані, то за найменшої зміни в чаті користувач утратить свій вибір. Якщо скласти все у widgetState, модель почне читати гори JSONʼу й легко «додумає» зайве. Якщо ж, навпаки, зберігати все на сервері та викликати його «на кожен піксель», буде повільно й дорого.

Офіційні рекомендації чітко ділять стан ChatGPT App на три класи: бізнес-дані, ефемерний UI‑стан і довготривалий міжсесійний стан. Із цього й почнемо.

2. Карта станів у ChatGPT App

Документація Apps SDK описує три типи стану. Зручно уявляти їх як одну таблицю:

Важливо: authoritative‑дані мають залишатися на сервері, а не у віджеті. Віджет отримує знімок цих даних через інструменти (MCP tools) і рендерить його, накладаючи зверху свій локальний UI‑стан.

У цій лекції ми зосередимося на тому, що бачить саме віджет:

• toolInput — вхідні аргументи викликаного інструмента;
• toolOutput — structuredContent із сервера (основні дані);
• toolResponseMetadata — службові метадані _meta, видимі лише віджету;
• widgetState — збережений UI‑стан, який ChatGPT тримає разом із повідомленням.

3. Що саме потрапляє у віджет: ToolInput, ToolOutput, Metadata, WidgetState

Ці три типи стану в ChatGPT App якраз відбиваються в конкретних полях, які платформа кладе у window.openai і передає в хуки SDK. На практиці ви отримуватимете їх через React‑хуки, але корисно знати точні визначення.

toolInput

Це об’єкт з аргументами інструмента (tool), які модель передала під час його виклику.

Наприклад, користувач пише:
«Підбери ідеї подарунків для жінки 30 років, бюджет 100 доларів».
Модель вирішує викликати ваш інструмент gift_search з аргументами:

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

Саме цей об’єкт ви побачите в toolInput усередині віджета. Тут зберігаються вхідні налаштування сценарію — те, заради чого взагалі запускали ваш App.

toolOutput

Це structuredContent, який повернув ваш MCP‑сервер / бекенд під час виконання інструмента.

Зазвичай це JSON на кшталт:

{
  "gifts": [
    { "id": "1", "title": "Путівник Ісландією", "price": 45 },
    { "id": "2", "title": "Електронна книга про подорожі", "price": 20 }
  ],
  "total": 2
}

Саме toolOutput — головне джерело даних для рендерингу. В офіційних матеріалах підкреслюють: модель читає це поле дослівно, тож тримайте його компактним і зрозумілим.

toolResponseMetadata

Це _meta з відповіді інструмента, теж доступне через window.openai як toolResponseMetadata. Документація окремо зазначає: вміст _meta бачить лише віджет, модель його не отримує.

Типові приклади:

• внутрішні ID із вашої системи;
• прапорці для UI (наприклад, «чи було кешування»);
• службові повідомлення для налагодження.

Якщо зовсім коротко: toolOutput — це «що сказати користувачу і моделі», а _meta — «що потрібно лише віджету та логам».

widgetState

Це JSON‑об’єкт, у якому ChatGPT зберігає знімок UI‑стану конкретного віджета між рендерами.

Його властивості:

• живе на боці ChatGPT і прив’язаний до конкретного message/widgetId;
• відновлюється під час повторного відкриття цього ж повідомлення;
• видний як віджету, так і моделі (дані з widgetState входять у контекст LLM);
• обмежений за розміром приблизно 4 тис. токенів, тож туди не можна скидати все підряд або зберігати величезні списки.

Важливо: widgetState — не місце для секретів. Ні токени, ні PII‑дані туди класти не можна, тому що модель їх побачить, а сама платформа не позиціонує це як безпечне сховище.

4. Локальний React‑стан: де він усе ще потрібен

Попри всю «магію» навколо toolOutput і widgetState, усередині віджета ви все ще пишете звичайний React з useState, useReducer, useRef тощо. Різниця лише в тому, що:

• локальний стан живе стільки, скільки живе конкретний рендер/iframe;
• модель його не бачить узагалі;
• під час демонтування віджета (користувач перейшов до іншого чату, повторний рендер, оновлення) локальний стан зникає.

Локальний стан чудово підходить для:

• миттєвих речей — hover, обраної вкладки, відкритого дропдауна;
• введення у формі до натискання «Продовжити»/«Зберегти»;
• тимчасових прапорців на кшталт isSubmitting або isTooltipOpen.

Міні‑приклад усередині нашого навчального застосунку GiftGenius — помічника з добору подарунків:

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

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

Поки ми не натиснули «Підтвердити вибір», це чудовий кандидат на локальний стан. Але щойно захочемо, щоб вибір «переїхав» між оновленнями віджета, треба думати про widgetState.

5. widgetState: пам’ять віджета між рендерами

widgetState — це та сама «пам’ять» віджета, яку зберігає сама платформа. Під час кожної важливої дії в UI ви можете викликати setWidgetState, і ChatGPT збереже цей JSON разом із повідомленням. Під час наступного рендеру цього ж віджета (наприклад, користувач прокрутив історію чату назад, а потім повернувся) SDK відновить цей об’єкт і передасть його вам.

Строго кажучи, можна було б напряму звертатися до window.openai.widgetState і window.openai.setWidgetState, але в лекції ми дотримуємося рекомендованого шляху — React‑хуків на рівні SDK.

Хук useWidgetState

Один із таких хуків якраз обгортає widgetState. Він:

• бере початкове значення або з window.openai.widgetState, або з переданого defaultState;
• підписується на оновлення від хоста;
• під час кожного вашого setWidgetState синхронізує нове значення з хостом через window.openai.setWidgetState.

Приклад типового використання всередині компонента віджета (синтаксис може трохи відрізнятися у шаблоні, але ідея така):

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

type GiftUiState = { likedIds: string[] };

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

Тепер uiState відновиться навіть після того, як користувач:

• згорнув/розгорнув чат;
• перейшов до іншого діалогу й повернувся;
• оновив сторінку (якщо платформа вирішила відновити цей віджет).

Приклад: пам’ятаємо обраний подарунок

Візьмемо список подарунків із toolOutput і запам’ятаємо обраний подарунок у widgetState, щоб він не губився.

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>
);

Тут важливий момент: setUiState не просто змінює локальний React‑стан. Він ще й викликає window.openai.setWidgetState «під капотом», якщо той доступний.

Якщо користувач пізніше натисне follow‑up під цим віджетом, ChatGPT може продовжити діалог із тим самим widgetId і тим самим widgetState, і модель побачить, який подарунок було обрано.

6. Читання даних інструмента в React: useWidgetProps та аналоги

Щоб кожен компонент не «ліз» руками в window.openai.toolOutput, в Apps SDK є ще один корисний шар — хук useWidgetProps. Він бере toolOutput із глобальної змінної, дає вам типізований об’єкт і, за потреби, підмішує значення за замовчуванням.

Спрощена сигнатура виглядає так:

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

Тобто всередині вам просто повертається toolOutput як тип T.

Припустімо, наш MCP‑інструмент повертає такий structuredContent:

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

Віджет може прочитати це так:

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

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

  if (!gifts.length) {
    return <div>Поки немає відповідних ідей. Спробуйте інший запит.</div>;
  }

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

Тут одразу кілька хороших практик:

• ми не припускаємо, що toolOutput уже точно є, — задаємо значення за замовчуванням;
• акуратно обробляємо порожній список;
• жодного доступу до window.openai напряму — усе через хук.

7. Синхронізація UI з toolOutput: завантаження, порожні дані, помилки

У реальному світі toolOutput не завжди надходить миттєво й не завжди виглядає «красиво». Документація Apps SDK прямо рекомендує продумати три стани: завантаження, нормальні дані та помилка/порожньо.

Найпростіший шаблон:

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

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

if (data === null) {
  return <div>Завантажуємо ідеї подарунків…</div>;
}

if (data.error) {
  return <div>Помилка: {data.error}</div>;
}

if (!data.gifts.length) {
  return <div>Під ваші критерії нічого не знайдено.</div>;
}

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

Такий підхід добре поєднується з тим, що сервер і модель можуть перевикликати інструмент, і ви отримаєте новий toolOutput. Віджет просто отримає нове значення через useWidgetProps і перерендериться.

У загальному потоці це виглядає так:

Користувач → запит
      ↓
Модель → викликає MCP tool
      ↓
Сервер → рахує, ходить до БД/інтеграцій, повертає structuredContent і _meta
      ↓
ChatGPT → кладе structuredContent у toolOutput
      ↓
Віджет → рендерить UI з toolOutput + widgetState

Офіційний гайд по серверу малює майже таку ж діаграму «User → Model → MCP tool → widget iframe», де toolOutput — головний вхід для віджета.

8. Багатокроковий сценарій: поточний крок у widgetState

Наш GiftGenius навряд чи обмежиться однією карткою. Найчастіше хочеться «майстер» із кроків: спочатку зібрати вподобання, потім визначитися з бюджетом, а наприкінці — запропонувати конкретні варіанти.

Найлогічніше зберігати номер кроку майстра у widgetState. Саме так і рекомендують робити в документації та прикладах із цієї теми.

Приклад міні‑майстра з двох кроків:

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

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

if (state.step === 1) {
  return (
    <div>
      <label>
        Бюджет, $
        <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} $…</div>
    {/* тут ми вже могли б рендерити toolOutput із подарунками */}
  </div>
);

Тут є кілька цікавих моментів:

• під час першого показу step дорівнює 1, користувач вводить бюджет;
• після onBlur ми оновлюємо widgetState на { step: 2, budget: … };
• під час наступного рендеру (зокрема за хвилину або під час повторного відкриття цього повідомлення) віджет одразу опиниться на кроці 2 зі збереженим бюджетом.

У більш просунутій версії на другому кроці ви вже запускаєте інструмент через useCallTool, передаєте туди budget і читаєте результат із toolOutput. Але це вже відсилання до модуля про інструменти (Модуль 4). Сьогодні головне — де ми тримаємо інформацію про крок.

9. Куди що класти: патерн «тонкий UI, товстий backend»

Узагальнимо розподіл ролей:

• authoritative‑дані (список подарунків, статуси замовлень) живуть на сервері та приходять у toolOutput;
• тимчасові візуальні речі (чи розкритий спойлер, поточний вміст незавершеного введення) живуть у локальному React‑стані;
• стійкі UI‑рішення усередині одного віджета (поточний крок, обраний елемент, сортування) живуть у widgetState;
• довготривалі налаштування користувача між чатами (улюблена категорія подарунків, остання валюта) живуть у вашому бекенді як persistent state.

Іноді дуже хочеться зробити «великий об’єкт усього», записати його у widgetState й жити спокійно. Але це погана ідея. Документація підкреслює: стан, який ви передаєте через widgetState, повністю входить у контекст моделі. Тому він має бути легким і здебільшого про UI.

Те саме стосується toolOutput: туди варто класти рівно ті дані, які потрібні і віджету, і моделі, щоб пояснити користувачу, що відбулося. Великі дерева, бінарні блоби, сирі відповіді інших API — це пряма дорога до дивних і дорогих відповідей моделі.

Нотатка

Усередині віджета ChatGPT неможливо спиратися на класичні механізми клієнтської ідентифікації. Файли cookie фактично недоступні: віджет завантажується як сторонній ресурс у пісочниці ChatGPT, а сучасні браузери блокують сторонні файли cookie за замовчуванням. Через це будь‑які спроби зберегти стан через cookie не працюють.

Експериментально перевірено: localStorage працює добре, тож ви можете розраховувати на нього під час проєктування своїх застосунків.

10. Невеликий наскрізний приклад: GiftGenius зі стійким вибором

Зберемо все в міні‑віджет, який:

• читає дані з toolOutput;
• зберігає вибір користувача в widgetState;
• акуратно обробляє порожні дані.

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>Секунду, підбираємо ідеї…</div>;
  }
  if (data.error) {
    return <div>Помилка: {data.error}</div>;
  }
  if (!data.gifts.length) {
    return <div>На жаль, нічого не знайшли. Спробуйте інший запит.</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>
  );
}

Цей код уже доволі близький до реального віджета:

• якщо інструмент ще виконується, бачимо «підбираємо ідеї»;
• якщо сервер повернув помилку — чесно її показуємо;
• якщо подарунків немає — коректно обробляємо порожній результат;
• обраний подарунок запам’ятовується в widgetState, і модель може використати його в наступних кроках діалогу.

Далі ви зможете додати кнопки «Продовжити з цим подарунком» (follow‑up), запуск нових інструментів тощо, спираючись на те, що вибір уже збережено в стані.

У підсумку хороша архітектура стану в ChatGPT App зводиться до простої ідеї: бізнес‑дані живуть на сервері, поточний знімок приходить через toolOutput, тимчасовий UI — у локальному useState, а стійкий, але прив’язаний до одного повідомлення контекст віджета — у widgetState. Якщо тримати цю схему в голові й не намагатися «все й одразу» запакувати в один шар, віджет лишається передбачуваним і для користувача, і для моделі.

11. Типові помилки під час роботи з Widget State, ToolInput і ToolOutput

Помилка №1: Зберігати бізнес‑дані у widgetState замість сервера.
Іноді хочеться зберегти цілий список сутностей у widgetState, щоб не викликати сервер повторно. Це погано з двох причин: ви дублюєте authoritative‑дані (сервер і віджет можуть «розʼїхатися»), а також роздуваєте контекст моделі, тому що widgetState входить до нього повністю. Краще зберігати справжні дані на сервері та повертати свіжий toolOutput як знімок.

Помилка №2: Записувати у widgetState секрети або PII.
Оскільки вміст widgetState бачить модель і він не призначений для захищеного зберігання, туди не можна класти токени, логіни, e‑mail‑адреси, телефони та іншу конфіденційну інформацію. Такі речі мають жити на сервері, а в widgetState максимум зберігається ID запису, з яким ви далі працюєте через MCP.

Помилка №3: Вважати, що toolOutput завжди є і завжди коректний.
Віджет, який без перевірки «лізе» в toolOutput.gifts[0], рано чи пізно зламається: інструмент може повернути помилку, порожній масив або змінити структуру. Рекомендують явно обробляти стани «завантаження», «порожньо», «помилка» і лише потім — нормальний рендер.

Помилка №4: Копіювати toolOutput у локальний стан без потреби.
Буває спокуса зробити const [data, setData] = useState(toolOutput) і далі жити лише з цим data. У результаті ви отримуєте дубльоване джерело істини: коли прийде новий toolOutput, локальний стан про це не дізнається, і UI продовжить показувати старі дані. Краще читати toolOutput напряму з useWidgetProps або отримувати похідний стан (мапінг, фільтр) у рендері, не дублюючи весь об’єкт.

Помилка №5: Використовувати лише локальний useState там, де потрібен widgetState.
Класичний баг: ви робите маленького майстра, зберігаєте currentStep у локальному стані, усе тестуєте — працює. Потім користувач прокручує чат, повертається — і раптом знову перший крок. Причина проста: локальний стан не пережив демонтування віджета. Для кроків, важливих у сценарії, варто завести widgetState, тоді платформа відновить їх разом із повідомленням.

Помилка №6: Намагатися звертатися до window.openai напряму в кожному компоненті.
Формально це працює, але ви отримуєте жорстку прив’язку до глобальної змінної, складний для налагодження код і вручну написані підписки на події. Офіційні матеріали та приклади радять використовувати шар хуків (useWidgetProps, useWidgetState, useOpenAiGlobal), які інкапсулюють усі деталі та легше тестуються.

Помилка №7: Не враховувати message‑scoped природу віджетів.
Якщо користувач не натискає follow‑up, а просто пише нове повідомлення в чат, ChatGPT створює новий екземпляр віджета з новим widgetId і порожнім widgetState. Сценарії, які покладаються на «вічну» пам’ять одного віджета, починають поводитися дивно. Тут потрібно або зберігати міжсесійний контекст на сервері, або будувати UX навколо follow‑upʼів та явного продовження сценарію.