Чого ми навчилися, запускаючи продукт із ChatGPT Apps SDK

• Apps SDK — практичний варіант, якщо вам потрібно швидко запустити робочий процес у ChatGPT або випробувати там свої інструменти, перш ніж інвестувати у власний стек агента. Але якщо вам потрібен повний контроль над кожним кроком агента, зазвичай це не найкращий вибір.

• Вибирайте Apps SDK, якщо основним інтерфейсом має бути ChatGPT і вам потрібні інструменти та невеликі елементи UI без створення повноцінного чат-продукту. Вибирайте власний стек агента, якщо потрібен жорсткий контроль над процесом, пам’яттю, запитами та операціями запису.

• Apps SDK підходить продуктам, що поєднують чат із кількома короткими кроками в UI. Ви запускаєте продукт швидше, але поступаєтеся частиною контролю.

• Нам допомогли чітко визначені інструменти, поведінка віджетів і наступні кроки. Саме на них, а не на LLM, ми покладалися під час проєктування процесу. Модель була найкориснішою, коли пояснювала результати, які система вже визначила.

• Далі — як зробити вибір, а також що спрацювало, а що ні.

Більшість команд досі лише тестують ШІ або застосовують його в другорядних сценаріях із низьким співвідношенням ризику й користі. Мало хто запускає критично важливий для бізнесу продукт, яким користувачі послуговуються щотижня. ChatGPT Apps SDK допомагає подолати цей розрив, якщо ви прагнете працювати всередині ChatGPT, а не самостійно створювати всього асистента.

Наші висновки ґрунтуються на проєкті для клієнта, вимоги якого передбачали ChatGPT як основний інтерфейс і швидкий запуск без фінансування повноцінного чат-продукту на замовлення.

Apps SDK відповідав цим вимогам, адже клієнтові були потрібні:

• Відсутність окремого чат-продукту, який треба розробляти й розміщувати — клієнт хотів охопити аудиторію в ChatGPT, а не створювати ще одну окрему оболонку асистента.

• Чат і невеликий UI для конкретних завдань — кілька цільових кроків у віджетах, а не ще один повноцінний продукт усередині процесу.

• Доступ до функцій бекенду через інструменти MCP — стандартний виклик інструментів, а не власне середовище виконання агента з наскрізним контролем.

• Пошук у ChatGPT — користувачі мають знаходити цей процес там, де вже працюють.

Під час розробки ми перевіряли ці рішення разом із клієнтом. Компроміс залишається: коли сеанс розміщено в ChatGPT, зовнішнє середовище виконання вам не належить. Ви спрямовуєте його, але не контролюєте повністю.

Застосунок на Apps SDK поєднує три складники:

1. Середовище виконання агента ChatGPT

2. Ваші інструменти MCP

3. UI вашого віджета

Як це працює на практиці:

1. Користувач звертається до ChatGPT із запитом.

2. ChatGPT може викликати один із ваших інструментів MCP.

3. Ваш сервер повертає структурований результат інструмента.

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

5. Користувач продовжує роботу в чаті або віджеті: вводить уточнення, робить вибір чи запускає з віджета виклик інструмента. Це оновлює гілку; ChatGPT виконує наступний хід, а кроки 2–4 повторюються до завершення завдання.

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

Вам не потрібно з нуля створювати UI чату, підключення інструментів, схеми автентифікації чи оболонку віджета. Для багатьох продуктів це істотно скорочує час розробки й дає змогу зосередитися на предметній логіці та захисних обмеженнях.

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

Apps SDK надає продукту іншу форму, ніж звичний фронтенд, тому важливо розуміти, для яких сценаріїв він підходить найкраще.

Використовуйте Apps SDK, якщо хочете

• Швидко запустити робочий процес у ChatGPT.

• Передати ведення розмови ChatGPT.

• Поєднати природну мову з кількома цільовими кроками в UI.

• Не створювати власний інтерфейс чату, контейнер агента й механізм пошуку.

Останній пункт особливо важливий, якщо ваші користувачі вже постійно працюють у ChatGPT.

Створюйте власного агента, якщо вам потрібні

• Фіксований покроковий процес, який можна примусово забезпечити в коді.

• Власний UI та повністю контрольований вами процес підтвердження.

• Власна модель пам’яті та стану.

• Поведінка, що має бути передбачуваною під час кожного запуску.

• Трасування, журнали й метрики агента.

Якщо планувальник, системні запити та весь робочий процес і є вашим продуктом, власний стек зазвичай підходить краще.

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

Ідеальний сценарій здається простим: користувач робить запит, інструмент запускається, дані повертаються, а коли потрібен вибір — з’являється віджет.

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

Стек проєкту був простим: FastMCP, Pydantic, React і TypeScript. З їх інтеграцією проблем не було. Основна робота полягала в тому, щоб модель, інструменти та UI однаково розуміли наступний крок.

Робіть кожен перехід очевидним

Ми перестали сприймати результати інструментів як необроблені дані від бекенду. Кожне повернення результату стало чітким переходом.

Якісний результат інструмента:

• Надає віджету все потрібне для відображення.

• Надає ChatGPT структуровані факти, на яких можна будувати відповідь.

• Коли цього потребує процес, указує наступну дію, щоб моделі не доводилося здогадуватися.

Дії у віджеті не повинні повертати до гілки нечітко сформульований текст. Вони мають повідомляти, що зробив користувач і що має відбутися далі.

Коли переходи стали чіткими, надійність зросла.

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

Нижче наведено невелику структуру Pydantic, яку ми використовували. Поле output містить структуровані дані, потрібні для відображення віджета, а також факти, які ChatGPT має використовувати в сеансі. Поле agent_directions містить коротку інструкцію про наступну дію асистента. Поле Reason необов’язкове.

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

Робіть віджети невеликими

Успішні віджети допомагали ухвалити одне рішення, а потім повертали керування. Короткі списки, підтвердження чи компактний екран перевірки працювали краще, ніж перетворення віджета на мініатюрний застосунок. Водночас трохи логіки у віджеті — наприклад, проста перевірка або фіксований наступний крок — допомагало зробити процес детермінованішим.

Третя особа в повідомленнях віджета

Ми перестали оформлювати подальші повідомлення віджета як репліки користувача (“I selected…,” “I confirmed…”). Натомість ми писали короткі звіти про дії користувача (“The user selected…,” “The user confirmed…”). Ми випробували цей підхід, оскільки ChatGPT додавав повідомлення віджета як повідомлення інструмента, а не користувача.

Прямі дії, коли наступний крок очевидний

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

Так нам було легше забезпечувати детерміновані процеси, а відмова від зайвого ходу в чаті також зменшила затримку.

Обробка помилок

Якщо виклик інструмента завершувався невдало, ми повертали належні коди помилок MCP і короткі зрозумілі повідомлення від інструмента. Тоді ChatGPT отримував конкретну інформацію про невдалий виклик і міг пояснити проблему користувачеві, вибрати доцільний наступний крок або зробити і те, й інше.

Керування контекстом інструментів

Ми зберігали стан сеансу на своєму сервері. ChatGPT передає з викликами інструментів контекст відповідного сеансу; у FastMCP ми додали до кожного інструмента параметр Context, щоб обробник міг читати й оновлювати цей стан.

• Стабільні ідентифікатори й попередні результати зберігалися в сеансі, тож ChatGPT не доводилося щоразу передавати їх як аргументи інструмента.

• Коли виникали цикли викликів інструментів, ми могли виявити дублікати й повернути чітку помилку в результаті інструмента.

• Журнали сеансів залишалися на нашому боці для налагодження й підтримки.

Спочатку ми показували віджет, припускали, що модель «усе зрозуміла», і чекали на правильний подальший виклик інструмента. Іноді так і ставалося. Але часто — ні.

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

Рішенням було чітко вказувати наступний крок у структурованих результатах і даних віджета, а не сподіватися, що модель визначить його сама.

Ми намагалися, як описано в документації Apps SDK, хитро розподіляти відповіді між результатом інструмента, прихованими метаданими й текстом чату. Проте віджети не могли читати приховані метадані. Тому ми не могли скористатися цим підходом.

У документації Apps SDK описано інструменти, які можна не додавати до списку інструментів агента, щоб він їх не вибирав, але й далі викликати з віджета. Коли ми встановили видимість лише для застосунку, ці інструменти стали недоступними не лише агенту, а й віджету. Нам так і не вдалося налаштувати систему так, щоб агент не бачив інструмент, а віджет бачив.

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

Якщо вам потрібен робочий процес у ChatGPT із меншим обсягом власних платформних робіт, Apps SDK — практичний спосіб його реалізувати. Ви поступаєтеся частиною контролю заради швидкості та можливості працювати з користувачами там, де вони вже перебувають.

Якщо вам потрібен повний контроль над кожною гілкою процесу, UI та вибором наступного кроку, від самого початку плануйте власний стек агента. Імовірно, згодом вам стане затісно в межах розробки лише всередині ChatGPT.

Також Apps SDK дає змогу спочатку запустити сервер MCP у ChatGPT, не створюючи самостійно чат, автентифікацію та інфраструктуру агента, а коли цього вимагатиме продукт — перейти на власний стек.

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