از عرضه با ChatGPT Apps SDK چه آموختیم

• اگر به‌زودی به یک گردش کار در ChatGPT نیاز دارید، یا می‌خواهید پیش از سرمایه‌گذاری روی پشتهٔ سفارشی عامل، ابزارهایتان را در آنجا بیازمایید، Apps SDK گزینه‌ای کاربردی است. اما اگر لازم است تمام مراحل رفتار عامل در اختیار خودتان باشد، معمولاً گزینهٔ مناسبی نیست.

• وقتی ChatGPT باید محیط اصلی باشد و بدون ساخت یک محصول کامل چت، ابزار و بخش‌های کوچکی از رابط کاربری می‌خواهید، Apps SDK را انتخاب کنید. وقتی به کنترل دقیق جریان، حافظه، اعلان‌ها و عملیات نوشتن نیاز دارید، پشتهٔ عامل خودتان را انتخاب کنید.

• Apps SDK برای محصولاتی مناسب است که چت را با چند مرحلهٔ کوتاه رابط کاربری ترکیب می‌کنند. سریع‌تر عرضه می‌کنید، اما بخشی از کنترل را واگذار می‌کنید.

• آنچه برای ما جواب داد، ابزارهای روشن، رفتار مشخص ویجت و گام‌های بعدی واضح بود. برای تعیین جریان به همین موارد تکیه کردیم، نه به مدل‌های زبانی بزرگ (LLM). مدل زمانی بیشترین فایده را داشت که نتایجی را توضیح می‌داد که سیستم از قبل انتخاب کرده بود.

• در ادامه: ابتدا نحوهٔ انتخاب، سپس آنچه جواب داد و آنچه نداد.

بیشتر تیم‌ها هنوز طرح‌های آزمایشی هوش مصنوعی اجرا می‌کنند یا آن را در کاربردهای جانبی با ریسک و بازده پایین به کار می‌گیرند. تعداد کمی محصولی حیاتی برای کسب‌وکار عرضه می‌کنند که کاربران هر هفته با آن سروکار داشته باشند. اگر هدفتان حضور در ChatGPT باشد، نه ساخت تمام دستیار از ابتدا، ChatGPT Apps SDK یکی از راه‌های پر کردن این شکاف است.

آموخته‌های ما حاصل پروژه‌ای برای یک مشتری است که نیازهایش ChatGPT را به‌عنوان محیط اصلی مشخص می‌کرد و مسیری سریع می‌خواست که مستلزم تأمین هزینهٔ یک محصول چت کاملاً سفارشی نباشد.

با توجه به این شرح نیاز، Apps SDK مناسب بود، زیرا مشتری به این موارد نیاز داشت:

• نیازی به ساخت و میزبانی محصول اختصاصی چت نبود—آن‌ها خواهان دسترسی درون ChatGPT بودند، نه پوسته‌ای دیگر برای یک دستیار مستقل.

• چت همراه با رابط کاربری کوچک و ویژهٔ هر کار—چند مرحلهٔ متمرکز در ویجت، نه محصول کامل دیگری درون گردش کار.

• ارائهٔ قابلیت‌های بک‌اند از طریق ابزارهای MCP—فراخوانی استاندارد ابزار، نه محیط اجرای سفارشی عامل با مالکیت سرتاسری.

• کشف‌شدن درون ChatGPT—کاربران باید در همان محیطی که از قبل کار می‌کنند با این گردش کار روبه‌رو شوند.

هم‌زمان با ساخت، این انتخاب‌ها را با مشتری اعتبارسنجی کردیم. این بده‌بستان همچنان برقرار است: وقتی ChatGPT میزبان نشست باشد، محیط اجرای بیرونی در اختیار شما نیست. آن را هدایت می‌کنید، اما کنترل کاملش را ندارید.

یک برنامهٔ Apps SDK سه چیز را به هم متصل می‌کند:

1. محیط اجرای عامل در ChatGPT

2. ابزارهای MCP شما

3. رابط کاربری ویجت شما

جریان کار در عمل:

1. کاربر چیزی از ChatGPT می‌خواهد.

2. ChatGPT ممکن است یکی از ابزارهای MCP شما را فراخوانی کند.

3. سرور شما نتیجه‌ای ساختاریافته از ابزار برمی‌گرداند.

4. ChatGPT نتیجه را می‌خواند و گام بعدی را تعیین می‌کند: فراخوانی ابزارهای بیشتر، پاسخ به کاربر یا هر دو. اگر ویجتی را به آن ابزار متصل کرده باشید، می‌تواند در همین نوبت نمایش داده شود.

5. کاربر در چت یا ویجت ادامه می‌دهد (متن تکمیلی، یک انتخاب یا فراخوانی ابزار از سوی ویجت). این کار رشتهٔ گفتگو را به‌روزرسانی می‌کند؛ ChatGPT نوبت دیگری را اجرا می‌کند و مراحل ۲ تا ۴ تا پایان کار تکرار می‌شوند.

هدف همین ترکیب چت، عملیات بک‌اند و مراحل کوتاه رابط کاربری است. این همچنین یعنی بخش‌های شکننده، نقاط تحویل میان چت، ابزارها و رابط کاربری هستند.

لازم نیست رابط چت، اتصال ابزارها، الگوهای احراز هویت یا پوستهٔ ویجت را از ابتدا بسازید. برای بسیاری از محصولات، این رویکرد زمان ساخت را بسیار کاهش می‌دهد تا بتوانید بر منطق حوزه و سازوکارهای محافظتی تمرکز کنید.

ساختن درون 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 ابزارهایی را شرح می‌دهند که می‌توانید از فهرست ابزارهای عامل کنار بگذارید تا آن‌ها را انتخاب نکند، اما همچنان از ویجت فراخوانی شوند. وقتی قابلیت مشاهده را روی app-only تنظیم کردیم، آن ابزارها علاوه بر عامل، از دسترس ویجت نیز خارج شدند. هرگز به تنظیماتی نرسیدیم که ابزار از دید عامل پنهان باشد، اما ویجت همچنان به آن دسترسی داشته باشد.

وقتی اتفاق مفیدی نیفتاده بود، سکوت یا پیام عمومی «success» از یک خطای صریح بدتر بود؛ بنابراین خطاهای ابزار و ویجت را خروجی‌هایی درجه‌یک در نظر گرفتیم: اگر مرحله‌ای نمی‌توانست ادامه یابد، به زبان ساده اعلام می‌کردیم و خطایی صریح برمی‌گرداندیم، نه اینکه کاربران را مقابل ویجتی بگذاریم که نمایش داده شده، اما آن‌ها را پیش نمی‌برد. این کار کاربردپذیری را بهبود داد و رفتار مدل را قابل‌اعتمادتر کرد.

اگر هدفتان ایجاد گردش کاری در ChatGPT با کار سفارشی کمتر روی پلتفرم است، Apps SDK راهی کاربردی برای رسیدن به آن است. در ازای سرعت و دسترسی به کاربران در محیط کاری همیشگی‌شان، بخشی از کنترل را واگذار می‌کنید.

اگر باید تمام شاخه‌های جریان، رابط کاربری و تصمیم‌گیرندهٔ هر مرحله در اختیار شما باشد، از ابتدا برای پشتهٔ عامل خودتان برنامه‌ریزی کنید. احتمالاً ساخت صرفاً درون ChatGPT دیگر پاسخ‌گوی رشدتان نخواهد بود.

همچنین می‌توانید پیش از آنکه چت، احراز هویت و زیرساخت عامل را خودتان بسازید، با Apps SDK سرور MCP خود را درون ChatGPT اجرا کنید و هر زمان محصول اقتضا کرد به پشتهٔ خودتان منتقل شوید.

گام بعدی برای تیم‌های مشابه: یک گردش کار با نتیجه‌ای روشن انتخاب کنید، نقاط تحویل میان چت، ابزارها و ویجت‌ها را بنویسید، سپس پیش از صرف زمان زیاد برای تنظیم اعلان، تلاش‌های مجدد و خطاها را تحت آزمون فشار قرار دهید.