Какво научихме от работата с ChatGPT Apps SDK

• Apps SDK е практичен избор, ако скоро ви трябва работен процес в ChatGPT или искате да изпробвате инструментите си там, преди да инвестирате в собствен стек за агенти. Но обикновено не е подходящ, ако трябва да контролирате всяка стъпка от поведението на агента.

• Изберете Apps SDK, когато ChatGPT трябва да е основният интерфейс и искате инструменти и малки елементи на потребителския интерфейс, без да създавате цялостен продукт за чат. Изберете собствен стек за агенти, когато ви е необходим строг контрол върху потока, паметта, подканите и операциите за запис.

• Apps SDK е подходящ за продукти, които съчетават чат с няколко кратки стъпки в потребителския интерфейс. Пускате продукта по-бързо, но се отказвате от част от контрола.

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

• По-долу ще разгледаме как да изберете, а след това – какво проработи и какво не.

Повечето екипи все още провеждат пилотни проекти с ИИ или го използват за периферни задачи с нисък риск и малка потенциална полза. Малко от тях пускат критично важен за бизнеса продукт, който потребителите използват всяка седмица. ChatGPT Apps SDK е един от начините да преодолеете тази разлика, ако целта ви е да присъствате в ChatGPT, вместо сами да изграждате целия асистент.

Изводите ни са от проект за клиент, чиито изисквания насочваха към ChatGPT като основен интерфейс и към бързо решение, което не изисква финансиране на изцяло персонализиран продукт за чат.

Apps SDK отговаряше на заданието, защото клиентът се нуждаеше от:

• Без необходимост от създаване и хостване на отделен продукт за чат – клиентът искаше обхват в ChatGPT, а не още една самостоятелна обвивка за асистент.

• Чат плюс малък, специализиран потребителски интерфейс – няколко целеви стъпки в уиджети, а не втори цялостен продукт в работния процес.

• Функции на сървъра, достъпни чрез MCP инструменти – стандартно извикване на инструменти, а не собствена среда за изпълнение на агент, управлявана изцяло от клиента.

• Откриване в ChatGPT – потребителите трябва да намират работния процес там, където вече работят.

Потвърждавахме тези решения с клиента в хода на разработката. Компромисът остава: когато ChatGPT хоства сесията, външната среда за изпълнение не е под ваш контрол. Можете да я насочвате, но не и да я контролирате изцяло.

Приложението с Apps SDK свързва три неща:

1. Средата за изпълнение на агенти на ChatGPT

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

3. Потребителския интерфейс на вашия уиджет

Потокът на практика:

1. Потребителят иска нещо от ChatGPT.

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

3. Сървърът ви връща структуриран резултат от инструмента.

4. ChatGPT прочита резултата и избира следващата стъпка: още извиквания на инструменти, отговор до потребителя или и двете. Ако към инструмента е свързан уиджет, той може да се покаже в тази стъпка.

5. Потребителят продължава в чата или в уиджети – с допълнителен текст, избор или извикване на инструмент, задействано от уиджета. Това актуализира нишката; ChatGPT изпълнява нова стъпка и стъпки 2–4 се повтарят до приключване на задачата.

Целта е именно това съчетание от чат, действия на сървъра и кратки стъпки в потребителския интерфейс. Това означава и че уязвимите места са преходите между чата, инструментите и потребителския интерфейс.

Не изграждате от нулата интерфейса за чат, свързването на инструментите, моделите за удостоверяване или обвивката на уиджета. При много продукти това значително съкращава разработката и ви позволява да се съсредоточите върху логиката на предметната област и защитните механизми.

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

Apps SDK предлага продуктова структура, различна от обичайния ви интерфейс, затова е важно да знаете за кои сценарии е най-подходящ.

Използвайте Apps SDK, когато искате да

• Пуснете бързо работен процес в ChatGPT.

• Оставите ChatGPT да хоства разговора.

• Съчетаете естествен език с няколко целеви стъпки в потребителския интерфейс.

• Избегнете създаването на собствен интерфейс за чат, контейнер за агенти и механизъм за откриване.

Последното е важно, когато потребителите ви вече работят в ChatGPT.

Създайте собствен агент, когато ви трябва

• Фиксиран поетапен поток, който можете да наложите чрез код.

• Персонализиран потребителски интерфейс и процес за потвърждение, които контролирате изцяло.

• Собствен модел за паметта и състоянието.

• Поведение, което трябва да е предвидимо при всяко изпълнение.

• Трасета, регистрационни файлове и показатели за агента.

Ако планиращият модул, системните подкани и целият работен процес са вашият продукт, персонализираният стек обикновено е по-подходящ.

По време на проекта постоянно се връщахме към думата „контрол“: от едната страна бяха скоростта и познатата среда, а от другата – частичният контрол върху средата за изпълнение. Клиентът прие този компромис, когато предпочете да достигне до потребителите в ChatGPT, вместо да контролира целия стек.

Идеалният сценарий звучи лесно: потребителят отправя заявка, инструментът се изпълнява, данните се връщат и при необходимост от избор се появява уиджет.

На практика проблемът бяха преходите. Уиджетът не е украса. Щом се появи на екрана, той променя какво вижда моделът и какво прави след това. Третирайте действията в уиджета като именувани събития, а не като свободен чат.

Стекът в проекта беше ясен: FastMCP, Pydantic, React и TypeScript. Интегрирането им не създаде проблеми. Истинската задача беше моделът, инструментите и потребителският интерфейс да постигнат съгласие за следващата стъпка.

Направете всеки преход недвусмислен

Спряхме да третираме резултатите от инструментите като необработени данни от сървъра. Всеки върнат резултат се превърна в преход.

Добрият резултат от инструмент:

• Предоставя на уиджета необходимото за визуализиране.

• Предоставя на 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

Поддържайте уиджетите малки

Успешните уиджети обработваха едно решение и след това връщаха контрола. Кратките списъци, потвържденията и компактните екрани за преглед работеха по-добре от превръщането на уиджета в миниприложение. Малко логика в уиджета – например проста проверка или фиксирана следваща стъпка – все пак помагаше, когато искахме потокът да е по-детерминиран.

Трето лице в съобщенията от уиджета

Спряхме да пишем последващите съобщения от уиджета като чат от потребителя („Аз избрах…“, „Аз потвърдих…“). Пишехме ги като кратки отчети за действията на потребителя („Потребителят избра…“, „Потребителят потвърди…“). Изпробвахме този подход, защото ChatGPT добавяше съобщенията от уиджета като съобщения от инструмент, а не от потребител.

Директни действия, когато следващата стъпка е очевидна

Ако даден бутон ясно предполага следващото извикване на инструмент, по-добре работеше уиджетът да го задейства директно, вместо да налагаме още една стъпка в чата. Това важи само ако следващото извикване на инструмент не изисква входни данни от ChatGPT.

Така по-лесно налагахме детерминирани потоци и намалявахме забавянето, като избягвахме още една стъпка в чата.

Обработка на грешки

Когато извикването на инструмент се провалеше, връщахме правилните MCP кодове за грешки и кратки, ясни съобщения от инструмента. Така при неуспешни извиквания ChatGPT получаваше реална информация, за да обясни проблема на потребителя и/или да избере разумна следваща стъпка.

Управление на контекста на инструментите

Съхранявахме състоянието на сесията на нашия сървър. ChatGPT изпраща контекст за конкретната сесия с извикванията на инструменти; във FastMCP зададохме на всеки инструмент параметър Context, за да може обработващият модул да чете и актуализира това състояние.

• Стабилните идентификатори и предишните резултати се съхраняваха в сесията, вместо да искаме от ChatGPT отново да ги подава като аргументи при всяко извикване.

• Когато възникваха цикли при извикване на инструменти, можехме да засечем дублираните извиквания и да върнем ясна грешка чрез резултата от инструмента.

• Регистрационните файлове на сесиите оставаха при нас за отстраняване на грешки и поддръжка.

В началото показвахме уиджет, предполагахме, че моделът „е разбрал“, и чакахме правилното последващо извикване на инструмент. Понякога това се случваше. Често не се случваше.

Без ясен преход ChatGPT можеше да обобщи, когато очаквахме действие, да поиска от потребителя да повтори избора си или да продължи да планира, когато трябваше да спре.

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

Опитахме се да следваме документацията на Apps SDK и умело да разделим отговорите между резултата от инструмента, скритите метаданни и текста в чата. Но уиджетите нямаха достъп до скритите метаданни. Затова не можехме да използваме този подход.

Документацията на Apps SDK описва инструменти, които могат да бъдат скрити от списъка с инструменти на агента, за да не ги избира той, но да могат да се извикват от уиджета. Когато зададохме видимост само за приложението, тези инструменти станаха недостъпни и от уиджета, а не само от агента. Така и не постигнахме конфигурация, при която агентът не вижда даден инструмент, но уиджетът все още има достъп до него.

Мълчанието или общото съобщение „успех“, когато не се е случило нищо полезно, беше по-лошо от директна грешка. Затова третирахме неуспехите на инструментите и уиджетите като пълноценни резултати: ако дадена стъпка не можеше да продължи, го заявявахме ясно и връщахме изрична грешка, вместо да оставяме потребителите пред уиджет, който се е визуализирал, но не им помага да продължат. Това подобри използваемостта и направи поведението на модела по-надеждно.

Ако целта ви е работен процес в ChatGPT с по-малко персонализирана работа по платформата, Apps SDK е практичен начин да я постигнете. Отказвате се от част от контрола в замяна на скорост и възможност да достигнете потребителите там, където вече работят.

Ако трябва да контролирате всяко разклонение на потока, потребителския интерфейс и решението за всяка стъпка, планирайте собствен стек за агенти още отначало. Вероятно в даден момент разработването само в ChatGPT вече няма да ви е достатъчно.

Можете също да използвате Apps SDK, за да изпълнявате своя MCP сървър в ChatGPT, преди сами да изградите чата, удостоверяването и инфраструктурата за агенти, а след това да преминете към собствен стек, когато продуктът го изисква.

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