Чему мы научились, выпуская продукт с 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 описаны инструменты, которые можно убрать из списка инструментов агента, чтобы он их не выбирал, но по-прежнему вызывать из виджета. Когда мы устанавливали видимость app-only, эти инструменты становились недоступны не только агенту, но и виджету. Нам так и не удалось настроить систему, в которой агент не видел бы инструмент, а виджет сохранял бы к нему доступ.

Молчание или общее сообщение «успешно», когда ничего полезного не произошло, хуже прямого сообщения об ошибке. Поэтому сбои инструментов и виджетов мы сделали полноценными результатами: если процесс нельзя продолжить, мы сообщали об этом простым языком и возвращали явную ошибку, а не оставляли пользователя перед виджетом, который отобразился, но не помог продвинуться дальше. Это повысило удобство работы и сделало поведение модели надежнее.

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

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

Можно сначала запустить свой сервер MCP внутри ChatGPT через Apps SDK, не создавая самостоятельно чат, аутентификацию и инфраструктуру агента, а затем перейти на собственный стек, когда это потребуется продукту.

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