Czego nauczyło nas wdrożenie ChatGPT Apps SDK?

• Apps SDK to praktyczne rozwiązanie, jeśli szybko potrzebujesz przepływu pracy w ChatGPT albo chcesz najpierw przetestować tam swoje narzędzia, zanim zainwestujesz we własny stos agenta. Jeśli potrzebujesz pełnej kontroli nad każdym etapem działania agenta, zwykle nie będzie to właściwy wybór.

• Wybierz Apps SDK, gdy głównym interfejsem ma być ChatGPT i potrzebujesz narzędzi oraz niewielkich elementów UI oraz nie chcesz tworzyć całego produktu czatowego. Wybierz własny stos agenta, gdy potrzebujesz ścisłej kontroli nad przepływem, pamięcią, poleceniami i operacjami zapisu.

• Apps SDK sprawdza się w produktach łączących czat z kilkoma krótkimi działaniami obsługiwanymi w UI. Szybciej wdrażasz produkt, ale rezygnujesz z części kontroli.

• W naszym przypadku sprawdziły się jasno zdefiniowane narzędzia, zachowanie widżetów i kolejne kroki. To na nich, a nie na LLM, opieraliśmy logikę przepływu. Model był najbardziej przydatny przy objaśnianiu wyników, które system już wcześniej wybrał.

• Poniżej wyjaśniamy, jak dokonać wyboru, a następnie opisujemy, co się sprawdziło, a co nie.

Większość zespołów nadal prowadzi pilotażowe projekty AI lub wdraża AI w pobocznych zastosowaniach o niskim ryzyku i niewielkich korzyściach. Niewiele z nich wdraża produkt o krytycznym znaczeniu dla firmy, z którego użytkownicy korzystają co tydzień. ChatGPT Apps SDK może pomóc zmniejszyć tę lukę, jeśli chcesz działać wewnątrz ChatGPT, zamiast samodzielnie tworzyć całego asystenta.

Nasze wnioski pochodzą z projektu dla klienta, którego wymagania wskazywały na ChatGPT jako główny interfejs oraz oczekiwał on szybkiego rozwiązania niewymagającego finansowania pełnego, tworzonego od podstaw produktu czatowego.

Apps SDK odpowiadał tym założeniom, ponieważ klient potrzebował:

• Gotowego produktu czatowego, którego nie trzeba hostować — klient chciał docierać do użytkowników w ChatGPT, a nie budować kolejny niezależny interfejs asystenta.

• Czatu uzupełnionego niewielkim UI do konkretnych zadań — kilku precyzyjnie opracowanych widżetów, a nie drugiego kompletnego produktu osadzonego w przepływie pracy.

• Udostępnienia funkcji backendu przez narzędzia MCP — standardowego wywoływania narzędzi zamiast własnego, pełnego środowiska wykonawczego agenta zarządzanego.

• Możliwości odkrycia rozwiązania w ChatGPT — użytkownicy powinni korzystać z procesów w rozwiązaniu, w którym już pracują.

W trakcie prac potwierdzaliśmy te decyzje z klientem. Nadal wiąże się to z kompromisem: gdy sesję obsługuje ChatGPT, nie masz kontroli nad zewnętrznym środowiskiem wykonawczym. Możesz nim kierować, ale nie masz nad nim pełnej kontroli.

Aplikacja oparta na Apps SDK łączy trzy elementy:

1. Środowisko wykonawcze agenta ChatGPT

2. Twoje narzędzia MCP

3. UI twojego widżetu

Przebieg w praktyce:

1. Użytkownik prosi ChatGPT o wykonanie zadania.

2. ChatGPT może wywołać jedno z twoich narzędzi MCP.

3. Twój serwer zwraca ustrukturyzowany wynik działania narzędzia.

4. ChatGPT odczytuje wynik i wybiera kolejny krok: dalsze wywołania narzędzi, odpowiedź dla użytkownika albo jedno i drugie. Jeśli z narzędziem powiązano widżet, może on pojawić się na tym etapie rozmowy.

5. Użytkownik kontynuuje interakcję na czacie lub w widżecie, wpisując kolejną wiadomość, dokonując wyboru albo uruchamiając z widżetu wywołanie narzędzia. Powoduje to aktualizację wątku. ChatGPT wykonuje kolejny cykl, a kroki 2–4 powtarzają się aż do ukończenia zadania.

Istotą rozwiązania jest właśnie połączenie czatu, działań backendu i krótkich etapów obsługiwanych w UI. Oznacza to również, że najbardziej podatne na błędy są informacje przekazywane między czatem, narzędziami i UI.

Nie musisz od podstaw tworzyć interfejsu czatu, integracji narzędzi, mechanizmów uwierzytelniania ani struktury widżetu. W wielu produktach znacznie skraca to czas tworzenia, dzięki czemu możesz skupić się na logice domenowej i zabezpieczeniach.

Tworzenie rozwiązania wewnątrz ChatGPT to nie to samo co obsługiwanie własnego agenta. Najtrudniejszą częścią projektu nie były sztuczki związane z poleceniami. Wyzwaniem było takie jednoznaczne zdefiniowanie narzędzi, widżetów i kolejnych kroków, aby model i UI działały spójnie.

Apps SDK nadaje produktowi inną formę niż typowy frontend, dlatego warto wiedzieć, w jakich scenariuszach sprawdza się najlepiej.

Użyj Apps SDK, jeśli chcesz:

• Szybko wdrożyć przepływ pracy w ChatGPT.

• Powierzyć obsługę rozmowy ChatGPT.

• Połączyć język naturalny z kilkoma precyzyjnie określonymi etapami w UI.

• Uniknąć tworzenia własnego interfejsu czatu, kontenera agenta i mechanizmu odkrywania rozwiązania.

Ten ostatni punkt ma znaczenie, gdy użytkownicy już na co dzień korzystają z ChatGPT.

Zbuduj własnego agenta, jeśli potrzebujesz:

• Ustalonego, etapowego przepływu, który można wymusić w kodzie.

• Własnego UI i ścieżki potwierdzania, nad którymi masz pełną kontrolę.

• Własnego modelu pamięci i stanu.

• Przewidywalnego zachowania przy każdym uruchomieniu.

• Śladów wykonania, dzienników i metryk agenta.

Jeśli mechanizm planowania, polecenia systemowe i cały przepływ pracy stanowią twój produkt, własny stos będzie zwykle lepszym wyborem.

W naszym projekcie wciąż wracaliśmy do kwestii kontroli: po jednej stronie były szybkość i znajome środowisko, a po drugiej — tylko częściowa kontrola nad środowiskiem wykonawczym. Klient zaakceptował ten kompromis, przedkładając dotarcie do użytkowników w ChatGPT nad pełną kontrolę nad całym stosem.

Idealny przebieg wydaje się prosty: użytkownik zadaje pytanie, narzędzie wykonuje działanie, wracają dane, a widżet pojawia się, gdy trzeba dokonać wyboru.

W praktyce problemy sprawiało przekazywanie informacji między elementami. Widżet nie jest dekoracją. Gdy pojawia się na ekranie, zmienia to, co model widzi i robi w następnym kroku. Działania widżetu traktuj jak nazwane zdarzenia, a nie swobodną rozmowę.

Stos użyty w projekcie był prosty: FastMCP, Pydantic, React i TypeScript. Ich integracja nie sprawiała problemów. Wyzwaniem było uzgodnienie dalszych działań między modelem, narzędziami i UI.

Jednoznacznie definiuj wszystkie przekazywane informacje

Przestaliśmy traktować wyniki narzędzi jako surowe dane z backendu. Każdy zwracany wynik stał się informacjami przekazywanymi do kolejnego etapu.

Dobrze przygotowany wynik narzędzia:

• Dostarcza widżetowi dane potrzebne do wyświetlenia zawartości.

• Dostarcza ChatGPT ustrukturyzowane fakty, na których może oprzeć odpowiedź.

• Gdy wymaga tego przepływ, wskazuje też kolejny krok, aby model nie musiał go zgadywać.

Działania widżetu nie powinny dodawać do wątku niejasnych opisów. Powinny informować, co zrobił użytkownik i co ma nastąpić dalej.

Niezawodność wzrosła, gdy przekazywane informacje stały się jednoznaczne.

Model wykonuje krótkie, jasne instrukcje, gdy są one zawarte w wyniku narzędzia i działaniach widżetu.

Poniżej przedstawiamy niewielki model Pydantic, którego używaliśmy. Sekcja output zawiera ustrukturyzowane dane potrzebne widżetowi, jeśli jest wyświetlany, oraz fakty, których ChatGPT powinien użyć w sesji. Sekcja agent_directions zawiera krótką instrukcję określającą, co asystent powinien zrobić dalej. Sekcja reason jest opcjonalna.

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

Twórz niewielkie widżety

Widżety, które się sprawdziły, obsługiwały jedną decyzję, po czym zwracały kontrolę. Krótkie listy, potwierdzenia lub zwięzły ekran weryfikacji sprawdzały się lepiej niż przekształcanie widżetu w mini aplikację. Niewielki zakres logiki w widżecie, na przykład prosta walidacja lub stały kolejny krok, pomagał jednak zwiększyć deterministyczność przepływu.

Trzecia osoba w komunikatach widżetu

Przestaliśmy pisać kolejne komunikaty widżetu tak, jakby były wiadomościami użytkownika („Wybrałem…”, „Potwierdziłem…”). Zaczęliśmy je formułować jako krótkie raporty o działaniach użytkownika („Użytkownik wybrał…”, „Użytkownik potwierdził…”). Wypróbowaliśmy to podejście, ponieważ ChatGPT dodawał komunikaty widżetu jako wiadomości narzędzia, a nie wiadomości użytkownika.

Bezpośrednie działania, gdy kolejny krok jest oczywisty

Jeśli przycisk jednoznacznie wskazywał kolejne wywołanie narzędzia, lepiej sprawdzało się uruchomienie go bezpośrednio przez widżet niż wymuszanie kolejnego cyklu czatu. Dotyczy to tylko sytuacji, w których następne wywołanie narzędzia nie wymaga danych wejściowych z ChatGPT.

Pomogło to wymusić deterministyczne przepływy i skrócić opóźnienia dzięki uniknięciu kolejnego cyklu czatu.

Obsługa błędów

Gdy wywołanie narzędzia kończyło się niepowodzeniem, zwracaliśmy z niego odpowiednie kody błędów MCP oraz krótkie, zrozumiałe komunikaty. Dzięki temu po nieudanym wywołaniu ChatGPT otrzymywał konkretną informację, na podstawie której mógł wyjaśnić użytkownikowi problem lub wybrać rozsądny kolejny krok.

Zarządzanie kontekstem narzędzi

Stan sesji przechowywaliśmy na naszym serwerze. ChatGPT przesyła wraz z wywołaniami narzędzi kontekst danej sesji. W FastMCP każde narzędzie otrzymało parametr Context, dzięki któremu procedura obsługi mogła odczytywać i aktualizować ten stan.

• Stałe identyfikatory i wcześniejsze wyniki przechowywaliśmy w sesji, zamiast prosić ChatGPT o ponowne przekazywanie ich jako argumentów przy każdym wywołaniu narzędzia.

• Gdy pojawiały się pętle wywołań narzędzi, mogliśmy wykryć duplikaty i zwrócić czytelny błąd w wyniku narzędzia.

• Dzienniki sesji pozostawały po naszej stronie na potrzeby debugowania i wsparcia.

Początkowo wyświetlaliśmy widżet, zakładaliśmy, że model „rozumie sytuację”, i czekaliśmy na właściwe kolejne wywołanie narzędzia. Czasami tak się działo. Często jednak nie.

Bez jednoznacznego przekazania informacji ChatGPT mógł podsumować sytuację, gdy oczekiwaliśmy działania, poprosić użytkownika o powtórzenie wyboru albo dalej planować, choć powinien już zakończyć.

Rozwiązaniem było wyraźne wskazanie kolejnego kroku w ustrukturyzowanych danych wyjściowych i danych widżetu, zamiast liczyć, że model sam go wywnioskuje.

Próbowaliśmy zgodnie z dokumentacją Apps SDK w pomysłowy sposób dzielić odpowiedzi między wynik narzędzia, ukryte metadane i tekst czatu. Nie mogliśmy jednak odczytać ukrytych metadanych w widżetach. Dlatego nie mogliśmy zastosować tego rozwiązania.

Dokumentacja Apps SDK opisuje narzędzia, które można usunąć z listy narzędzi agenta, aby ich nie wybierał, a jednocześnie nadal wywoływać je z widżetu. Gdy ustawiliśmy widoczność na app-only, narzędzia te przestały być dostępne również z widżetu, a nie tylko dla agenta. Nie udało nam się uzyskać konfiguracji, w której agent nie widział narzędzia, ale widżet nadal miał do niego dostęp.

Brak komunikatu lub ogólne „powodzenie”, gdy nic użytecznego się nie wydarzyło, były gorsze niż bezpośredni błąd. Dlatego awarie narzędzi i widżetów traktowaliśmy jako pełnoprawne wyniki: jeśli nie można było kontynuować danego etapu, informowaliśmy o tym prostym językiem i zwracaliśmy jednoznaczny błąd, zamiast pozostawiać użytkownika przed wyświetlonym widżetem, który nie pozwalał przejść dalej. Poprawiło to użyteczność i zwiększyło niezawodność zachowania modelu.

Jeśli zależy Ci na przepływie pracy w ChatGPT przy mniejszym nakładzie własnych prac w obszarze platformy, Apps SDK jest praktycznym sposobem na osiągnięcie tego celu. Pozwala to zrezygnować z pewnego zakresu kontroli, w zamian uzyskując szybkość i możliwość zapewnienia użytkownikom narzędzi w środowiskach, które już znają.

Jeśli potrzebujesz pełnej kontroli nad każdą gałęzią przepływu, UI oraz tym, kto wybiera poszczególne kroki, od początku zaplanuj własny stos agenta. Prawdopodobnie z czasem rozwiązanie działające wyłącznie wewnątrz ChatGPT przestanie Ci wystarczać.

Możesz również użyć Apps SDK, aby najpierw uruchomić serwer MCP wewnątrz ChatGPT, zanim samodzielnie zbudujesz czat, uwierzytelnianie i infrastrukturę agenta, a następnie przejść na własny stos, gdy produkt zacznie tego wymagać.

Zespołom w podobnej sytuacji zalecamy wybrać jeden przepływ pracy z jasno określonym wynikiem, opisać przekazania między czatem, narzędziami i widżetami, a następnie gruntownie przetestować ponowienia i błędy, zanim poświęcą dużo czasu na dostrajanie poleceń.