Користувацький сценарій: як GPT пропонує застосунок і викликає його інструменти

1. Вступ

Уявіть, що ви пишете звичайний вебсервіс. Там усе просто: у вас є URL /search, користувач натискає кнопку, а ви викликаєте контролер searchController. У світі ChatGPT Apps користувач не бачить жодного /search. Натомість він пише «людський» текст:

«Підібери подарунок брату‑геймеру до 50$»

А далі:

• модель вирішує: «О, це про подарунки. У мене є GiftGenius, який уміє це робити»;
• GPT сам «натискає кнопки» — викликає інструменти вашого App;
• іноді ще й пропонує користувачеві: «Хочете, відкрию GiftGenius і покажу варіанти?».

Ключова зміна така: користувач висловлює намір, а «кнопки натискає» модель. Якщо цього не розуміти, дуже легко:

• написати інструменти з беззмістовними назвами (run_func, doStuff),
• отримати App, який модель ніколи не пропонує або викликає недоречно,
• створити віджет, який «з’являється нізвідки» й ламає діалог.

Тому в цій лекції ми сформуємо ментальну модель: як GPT узагалі дізнається про ваш App і в яких точках діалогу «вбудовує» його.

Insight: застосунок — це плагін для ChatGPT

На відміну від мобільних застосунків або мінізастосунків у WeChat, застосунки в ChatGPT побудовані інакше.

ChatGPT сам вирішує, коли запускати ваш застосунок і яку його функцію викликати. Застосунки в ChatGPT можуть активно втручатися (хоч і з обмеженнями) в логіку чату. Їхня основна мета й сильна сторона — розширювати можливості самого ChatGPT.

Якщо ChatGPT може ідеально розвʼязати проблему користувача, йому не потрібно викликати ваш застосунок. Якщо ChatGPT узагалі не здатен розвʼязати проблему користувача, то користувач, найімовірніше, про це й не питатиме. Найкращий варіант — коли ChatGPT може закрити запит лише частково. Це означає, що запити є, їх багато, але результату бракує.

Саме тоді ChatGPT викликає ваш застосунок — і ви разом даєте користувачеві кращий результат. Користувач задоволеніший, а ви — із заробітком.

2. Способи запуску ChatGPT App очима користувача

Користувач не має кнопки «викличте MCP‑сервер і call_tool». Натомість є поле введення тексту та (іноді) меню застосунків. З його точки зору, існують дві базові схеми запуску: явна і неявна.

Явний запуск (explicit)

Це сценарій, коли користувач свідомо обирає ваш App.

Типові варіанти:

• користувач знаходить App у Store ChatGPT і натискає «Відкрити»;
• користувач обирає App у лаунчері (наприклад, через кнопку + у полі введення тексту (Composer));
• користувач починає повідомлення з імені застосунку: «GiftGenius, підбери подарунок…» — це називається named mention. Якщо імʼя App стоїть на початку промпту, ChatGPT автоматично додає ваш App у контекст відповіді.

У явному режимі модель від самого початку знає, що користувач прийшов попрацювати саме з цим App. Тому:

• GPT частіше й активніше викликає ваші tools;
• UI‑віджет вашого App цілком може зʼявитися вже в першій відповіді;
• GPT рідше «ігнорує» App і відповідає самостійно.

Показовий приклад: користувач відкриває GiftGenius безпосередньо, бо хоче «погратися» з підбором подарунків. Він натискає на App у списку, і GPT показує вітальне повідомлення, наприклад:

«Привіт! Я GiftGenius, допоможу підібрати подарунок. Розкажіть, кому і на який бюджет шукаємо?»

А далі активно використовує ваші інструменти для пошуку.

Неявний запуск (implicit / suggested)

Інший сценарій: користувач узагалі не думає про App. Він просто пише в звичайному чаті:

«Підібери подарунок на день народження мамі, вона любить садівництво, бюджет до 100$»

GPT аналізує запит і бачить, що:

• в екосистемі є App GiftGenius, інструменти якого описані як «Use this when the user wants to get gift recommendations»;
• завдання й обмеження (подарунок, бюджет, інтереси) добре відповідають можливостям цього App.

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

«Можу використати застосунок GiftGenius, щоб підібрати конкретні варіанти подарунків і показати їх у вигляді карток. Відкрити його?»

Якщо користувач погоджується, GPT викликає потрібний інструмент App і, можливо, рендерить ваш віджет.

Важливо, що ви ніде не пишете if (prompt.includes("подарунок")) openApp(). Рішення модель ухвалює сама, спираючись на:

• текст запиту й історію діалогу;
• метадані ваших інструментів (назви, описи, схеми параметрів);
• стан підключення користувача до App (чи авторизований він), а також те, чи це користувач корпоративного облікового запису.

Ви впливаєте не на алгоритм, а на те, як ваш App і tools «описані» для моделі.

Гібрид: коли GPT уточнює, а потім пропонує App

Іноді користувач пише щось дуже загальне:

«Треба щось придумати колезі, взагалі не знаю що»

Модель розуміє, що GiftGenius може допомогти, але інформація надто розмита. Частий патерн (шаблон) такий:

1. GPT ставить 1–2 уточнювальні запитання текстом.
2. Після цього пропонує запустити App: «У мене є інструмент підбору подарунків. Хочете, я відкрию його і покажу варіанти?».

Це хороший UX: користувач не відчуває, що його силоміць «перевели в інший застосунок».

3. Discovery: як GPT знаходить ваш App

Тепер подивімося, як усе це виглядає з точки зору самої моделі.

У документації Apps SDK це називається Discovery — усі способи, якими користувач і модель узагалі дізнаються про ваш App. Це і природні запити в чаті, і каталог застосунків, і спеціальні точки входу на кшталт лаунчера.

Звідки модель узагалі знає, що ваш App існує

Під час реєстрації ChatGPT запускає ваш App, а він (через MCP) розповідає про себе: перелічує доступні інструменти з їхніми схемами — імʼя, опис, JSON‑схему вхідних параметрів. Інформацію про застосунок потрібно буде вказати під час реєстрації, а інформацію про інструменти ChatGPT сам отримає через MCP‑метод list_tools.

Модель не бачить ваш вихідний код. Їй доступні лише:

• імʼя інструмента (name);
• опис (description);
• сигнатура входу (inputSchema).

Саме це стає «API для моделі». Якщо ви назвали інструмент run_func з описом «Executes the function», модель не зрозуміє, коли його викликати. А якщо назвете suggest_gifts з описом «Use this when the user wants gift ideas based on recipient, occasion and budget» — усе стає прозоро.

Named mention і in‑conversation discovery

Офіційна специфікація Apps SDK виокремлює два ключові механізми:

• Named mention — коли користувач починає повідомлення з імені вашого App. У цьому разі App майже гарантовано буде запущено й використано у відповіді.
• In‑conversation discovery — коли користувач просто пише запит, а модель вирішує, чи варто підключати App. При цьому враховуються:
  • контекст розмови (історія повідомлень, результати попередніх tools, уподобання користувача);
  • явні згадки бренду в тексті;
  • метадані ваших tools — назви, описи, документація параметрів;
  • стан підключення — чи підʼєднаний користувач до App (чи авторизований він, чи надано потрібні дозволи).

Розробник впливає на цей процес опосередковано: через якісні метадані й UX‑патерни, а не через if/else у коді.

Каталог і лаунчер

Окрім діалогового способу, існують ще Store у ChatGPT і лаунчер, доступний із композера. Через них користувачі можуть явно обирати App — як звичайний застосунок у магазині.

Для нас це важливо концептуально: коли ми продумуємо сценарій GiftGenius, маємо памʼятати, що:

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

Усе це — про discovery самого App: моменти, коли модель вирішує, чи варто взагалі запустити ваш застосунок і запропонувати його користувачеві в поточній розмові.

4. Анатомія циклу взаємодії: від фрази до віджета

Пора зібрати всі рівні з попередньої лекції — від ChatGPT UI і віджета до Apps SDK і MCP‑сервера — в один зрозумілий логічний цикл.

Високорівнева схема

З погляду процесу цикл виглядає так:

sequenceDiagram
    participant U as Користувач
    participant G as ChatGPT (модель)
    participant A as App / MCP-сервер

    U->>G: Текстовий запит
    G->>G: Аналіз запиту + вибір tools
    G->>A: Виклик інструмента (call_tool)
    A-->>G: Відповідь (дані / structuredContent)
    G->>U: Текстова відповідь + (опціонально) віджет App

Людською мовою:

1. Користувач пише повідомлення в ChatGPT.
2. Модель аналізує запит і поточний контекст та вирішує:
   • відповідати самій,
   • чи викликати один або кілька інструментів.
3. Якщо обрано інструмент вашого App, ChatGPT формує структурований запит (call_tool) і надсилає його MCP‑серверу.
4. Ваш бекенд (або MCP‑сервер) виконує дію: звертається до бази даних, зовнішніх API, ACP тощо, формує результат.
5. Результат повертається у вигляді структурованих даних (і, можливо, JSON для віджета).
6. Модель використовує ці дані, щоб:
   • згенерувати зрозумілий користувачеві текст,
   • за потреби — намалювати віджет App прямо у відповіді.

Усе багатокрокове планування — «коли викликати що», «чи спитати уточнення», «чи зробити ще один виклик» — відбувається на боці ШІ‑моделі. Apps SDK і MCP лише надають єдиний контракт для інструментів.

Де тут ми пишемо код

У цьому циклі є три точки, де ви справді пишете TypeScript‑код:

1. Конфігурація App і інструментів — описи tools (імʼя, опис, схема) і метадані App (імʼя, іконка, категорії). У вашому проєкті це, найімовірніше, файл на кшталт openai/app-config.ts.
2. MCP‑сервер / бекенд — обробка call_tool: звертаємося до бази даних, фільтруємо товари, за потреби викликаємо інші API тощо.
3. Віджет (UI) — React‑компонент у застосунку Next.js, який відображається в чаті й читає результати інструментів через window.openai або хуки Apps SDK.

Усе інше — справа моделі й платформи.

5. GiftGenius у дії: два сценарії користувацької взаємодії

Перейдемо до конкретніших сценаріїв, щоб ви могли «побачити» цей процес.

Сценарій 1: користувач відкриває GiftGenius явно

Сценарій:

1. Користувач у ChatGPT відкриває каталог App і знаходить GiftGenius.
2. Натискає «Відкрити».
3. ChatGPT запускає діалог уже у контексті GiftGenius.

Діалог приблизно такий:

Користувач:

Відкриває GiftGenius із каталогу.
І пише: «Привіт! Я хочу підібрати подарунок другу»

GPT:

«Чудово, допоможу підібрати подарунок. Розкажіть, кому, на який бюджет і з якого приводу ви шукаєте подарунок?»

На цьому кроці GPT може відразу викликати перший інструмент, наприклад start_gift_session, щоб ініціалізувати сесію у вашому бекенді (створити тимчасовий кошик, згенерувати sessionId тощо).

Ваш код на боці MCP‑сервера може виглядати так (поки що — дуже умовно):

// Псевдоприклад future-TS: опис інструмента GiftGenius
const suggestGiftsTool = {
  name: "suggest_gifts",
  description: "Use this when the user wants gift ideas by recipient, occasion and budget",
  inputSchema: {
    type: "object",
    properties: {
      recipient: { type: "string" },
      occasion: { type: "string" },
      budgetUsd: { type: "number" },
    },
    required: ["recipient", "occasion", "budgetUsd"],
  },
};
    

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

Після відповіді користувача GPT викликає suggest_gifts, отримує від вас масив варіантів, а далі:

• оформлює резюме текстом;
• вбудовує віджет GiftGenius, де картки з подарунками можна гортати й фільтрувати.

Сценарій 2: користувач просить «підібрати подарунок» у звичайному чаті

Тепер інший варіант: користувач узагалі не знає про GiftGenius.

Він пише у звичайному чаті:

«Потрібен подарунок братові, він обожнює настільні ігри, 50 баксів максимум»

Усередині ChatGPT приблизно відбувається таке:

1. Модель аналізує запит і список доступних інструментів.
2. Вона бачить інструмент suggest_gifts з відповідним описом.
3. Розуміє, що App GiftGenius створений спеціально для таких завдань.
4. Перевіряє, чи встановлював користувач уже цей застосунок, чи був авторизований і які дозволи надав.

Подальша поведінка може бути різною:

• якщо запит достатньо конкретний, GPT може мовчки викликати suggest_gifts і повернути відповідь із віджетом;
• якщо чогось бракує (наприклад, не вказано привід або вік), GPT може спочатку поставити уточнювальні запитання текстом, а потім запропонувати App.

Така гнучкість — те, що відрізняє Apps від «жорстких» UI з формами: модель сама обирає, коли використовувати інструменти, а коли просто поговорити.

6. Семантична маршрутизація: «LLM як диспетчер»

На рівні discovery модель вирішує, чи варто взагалі підʼєднувати ваш App до поточного запиту. А далі, коли App уже запущено, а його інструменти відомі моделі в поточній сесії, вмикається другий рівень — семантична маршрутизація всередині tools: який саме інструмент має обробляти чергову репліку.

У класичному веб‑бекенді маршрут обирається за URL: /checkout — отже, викликаємо checkout‑контролер. У ChatGPT Apps маршрутизації за URL немає. Натомість є семантична маршрутизація: модель порівнює зміст запиту з описами ваших інструментів.

Спрощено процес такий:

1. На старті сесії ChatGPT отримує список tools: їхні імена, описи, схеми.
2. Ці дані вбудовуються в системні інструкції моделі.
3. Коли користувач пише запит, модель порівнює зміст запиту з описами інструментів: де «підбір подарунків», де «пошук готелів», а де «побудувати графік».
4. Якщо знаходить хорошу відповідність, формує структурований виклик потрібного інструмента.

Звідси випливає головний практичний висновок:

• опис інструмента — це ваш API для моделі; перечитайте це ще раз. А потім — іще.
• якщо ви напишете «does stuff», модель справді не зрозуміє, коли його викликати.

Документація й найкращі практики щодо discovery підкреслюють: до метаданих слід ставитися як до продуктової копірайтингової роботи. Саме вони визначають, у яких розмовах модель згадає ваш App.

7. Патерни діалогу навколо App

Тепер подивімося на типові UX‑патерни, що виникають, коли GPT взаємодіє з App у межах однієї розмови. Це важливо, щоб ви не будували App «у вакуумі» — без розуміння ролі GPT‑частини.

Усі практичні посібники з Apps SDK виокремлюють кілька характерних патернів:

«Майстер» (The Wizard)

GPT веде користувача крок за кроком, часто спираючись на App.

На прикладі GiftGenius:

1. GPT: «Розкажіть, кому подарунок?»
2. Користувач: «Брат, 25 років, любить настільні ігри».
3. GPT: «Який бюджет?»
4. Користувач: «До 50 $».
5. GPT викликає suggest_gifts, показує результати у віджеті й пише: «Я підібрав кілька варіантів — подивіться у списку нижче».

У цьому патерні App і його віджет — ніби візуальний шар над багатокроковим діалогом. Користувач більшість часу пише текст, а віджет допомагає візуалізації вибору.

«Адаптивний віджет» (The Adaptive Widget)

Текст лишається основним каналом, а App підключається точково для спеціальних завдань: побудувати графік, показати таблицю, відобразити картки товарів.

Приклад:

• Користувач: «Порівняй три варіанти подарунка: настільна гра, книга, подарунок‑враження».
• GPT спочатку текстом пояснює плюси та мінуси.
• Потім викликає інструмент, який повертає структурований список продуктів, і рендерить невелику таблицю або картки.

Тут App — як візуальне доповнення, а не «режим роботи за замовчуванням».

«Невидимий агент» (Invisible Agent)

App узагалі може не показувати UI. Він працює «під капотом» як джерело даних:

• ви реалізуєте MCP‑tool, який шукає подарунки у вашій базі даних;
• GPT викликає його, отримує список і вже сам переказує результати текстом — без жодного віджета.

Це схоже на класичний «плагін без UI»: користувач бачить лише, що GPT знає актуальні ціни й асортимент.

Такий патерн корисний для tool‑first App, де UI не критичний.

8. Як сценарій взаємодії впливає на дизайн App

Розуміння сценарію важливе не лише «для філософії», а й для цілком практичних рішень: які інструменти створювати, як їх описувати, коли показувати віджет, а коли краще відповісти текстом.

Принцип «chat‑first»

Ключова ідея екосистеми: чат — головний канал взаємодії, а UI‑компоненти — допоміжні.

Це означає:

• не треба намагатися вмістити «цілий сайт» в один віджет;
• віджети мають допомагати там, де чат незручний: вибір зі списку, фільтрація, порівняння, складні форми.

Для GiftGenius це:

• підібрати список подарунків і дати користувачеві можливість натискати на картки;
• візуалізувати фільтри (ціна, категорія, наявність);
• допомогти оформити замовлення (checkout) у кілька зрозумілих кроків.

А от писати у віджеті довгі пояснення на кшталт «як обрати подарунок дівчині‑інтроверту» — не найкраща ідея. Це завдання чату.

Коли запускати App, а коли ні

Ще один наслідок: не треба перетворювати App на «загарбника діалогу».

Поганий патерн:

• користувач веде серйозну дискусію;
• App запускається і відкриває величезний повноекранний віджет без попередження;
• користувач губиться: «куди подівся мій чат?».

Краще:

• спочатку все обговорити текстом і поставити кілька уточнювальних запитань;
• потім мʼяко запропонувати відкрити App, якщо це справді покращить UX (порівняння, конфігурація, checkout).

Вплив на набір інструментів

Оскільки модель обирає інструмент за описом, кожен інструмент має:

• розвʼязувати одне зрозуміле завдання;
• бути добре описаним у стилі «Use this when…»;
• мати параметри, які природно випливають із запитань, що GPT ставитиме користувачеві.

Для GiftGenius замість одного гігантського do_everything логічніше мати:

• suggest_gifts — підбір списку варіантів;
• get_gift_details — подробиці за одним ID;
• create_order — оформлення замовлення.

Ми докладніше займатимемося дизайном інструментів у модулі 4, але загальна ідея вже зараз важлива: сценарій діалогу визначає, які інструменти взагалі потрібні.

9. Міні‑приклад: як описи tools впливають на сценарій (TypeScript‑нарис)

Невеликий фрагмент уявного openai/app-config.ts, щоб повʼязати теорію з кодом. Не сприймайте це як точний синтаксис SDK (його розберемо в наступному модулі) — нам зараз важлива ідея імен і описів.

// Умовний фрагмент конфігурації GiftGenius (майбутній код)
const tools = [
  {
    name: "suggest_gifts",
    description: "Use this when the user wants gift ideas based on recipient, occasion, and budget.",
    inputSchema: {/* ... */},
  },
  {
    name: "get_gift_details",
    description: "Use this when the user asks for more information about a specific gift from a previous list.",
    inputSchema: {/* ... */},
  },
];

Якщо ви заміните suggest_gifts на run_func, а опис — на «Main function», GPT:

• гірше зрозуміє, для яких запитів варто викликати цей інструмент;
• може рідше пропонувати ваш App в in‑conversation discovery;
• буде складніше повʼязувати уточнювальні запити користувача з уже показаним списком подарунків.

І навпаки, хороші імена й описи підвищують шанс, що саме ваш App зʼявиться в потрібний момент.

10. Типові помилки під час проєктування користувацького сценарію

Помилка № 1: очікування повного контролю — «я сам вирішу, коли запускати App».
Іноді розробники мислять у парадигмі «я перехоплю всі запити про подарунки й підключу свій App». У світі ChatGPT Apps усе інакше: рішення ухвалює модель. Вона враховує описи інструментів, контекст діалогу, стан дозволів і те, наскільки доречним буде для користувача запуск саме вашого App.

Помилка № 2: беззмістовні імена та описи інструментів.
Інструменти з іменами run, main, tool1 та описами «Calls the main function» — це ідеальний рецепт проблем: модель не розуміє, коли їх викликати, in‑conversation discovery практично не працює, а ваш App стає «невидимим». Хороший опис у стилі «Use this when the user wants…» і зрозуміле імʼя — набагато важливіші, ніж може здатися на перший погляд.

Помилка № 3: спроба втиснути в один App «усе на світі».
Якщо ваш App одночасно «підбирає подарунки, бронює готелі, рахує податки і виводить котиків», модель не зможе надійно маршрутувати запити. Офіційні рекомендації та практичні гіди підкреслюють принцип «one clear job per tool/App»: краще кілька спеціалізованих застосунків, ніж один мегамоноліт.

Помилка № 4: агресивний автозапуск важкого UI.
Розробник у захваті від свого красивого повноекранного віджета й хоче показувати його «з будь‑якого приводу». У результаті користувачеві здається, що чат «ламається» і перетворюється на дивний вебзастосунок. Набагато краще, коли GPT спочатку спілкується текстом, ставить уточнювальні запитання і лише потім пропонує відкрити App, пояснюючи, навіщо це потрібно.

Помилка № 5: ігнорування ролі GPT як UX‑шару.
Можна спроєктувати App як звичайний SPA: усе зробити у віджеті, а ChatGPT має «мовчати й не заважати». Але так не працюватиме. ChatGPT може не відобразити ваш віджет або відображати новий віджет на кожен новий виклик tool. Хочете успішний продукт — підлаштовуйтеся під платформу, а не чекайте, що вона підлаштується під вас.