Apa yang kami pelajari saat merilis dengan ChatGPT Apps SDK

• Apps SDK adalah pilihan praktis jika Anda perlu segera menghadirkan alur kerja di ChatGPT atau ingin menguji alat Anda di sana sebelum berinvestasi dalam stack agen khusus. Namun, biasanya ini bukan pilihan tepat jika Anda perlu mengendalikan setiap tahap perilaku agen.

• Pilih Apps SDK jika ChatGPT akan menjadi antarmuka utama dan Anda menginginkan alat serta sedikit UI tanpa perlu membangun produk chat lengkap. Pilih stack agen Anda sendiri jika Anda memerlukan kendali ketat atas alur, memori, prompt, dan operasi tulis.

• Apps SDK cocok untuk produk yang memadukan chat dengan beberapa langkah UI singkat. Anda dapat merilis lebih cepat, tetapi harus melepaskan sebagian kendali.

• Yang berhasil bagi kami adalah alat yang jelas, perilaku widget yang jelas, dan langkah berikutnya yang jelas. Kami mengandalkan hal-hal tersebut untuk menentukan alur, bukan LLM. Model paling berguna ketika menjelaskan hasil yang telah dipilih oleh sistem.

• Berikut ini: cara memilih, lalu apa yang berhasil dan tidak berhasil.

Sebagian besar tim masih menjalankan proyek percontohan AI atau menerapkan AI untuk penggunaan pendukung dengan risiko dan manfaat yang rendah. Hanya sedikit yang merilis produk penting bagi bisnis yang digunakan setiap minggu. ChatGPT Apps SDK adalah salah satu cara untuk menjembatani kesenjangan tersebut jika tujuan Anda adalah hadir di dalam ChatGPT, bukan membangun seluruh asisten sendiri.

Pelajaran kami berasal dari proyek klien yang kebutuhannya mengarah pada ChatGPT sebagai antarmuka utama dan jalur cepat yang tidak mengharuskan mereka mendanai produk chat khusus secara menyeluruh.

Untuk memenuhi kebutuhan tersebut, Apps SDK cocok karena klien memerlukan:

• Tidak perlu membangun dan meng-host produk chat khusus—mereka ingin menjangkau pengguna di dalam ChatGPT, bukan membuat kerangka asisten mandiri lainnya.

• Chat ditambah UI kecil yang spesifik untuk tugas tertentu—beberapa langkah widget terfokus, bukan produk lengkap kedua di dalam alur kerja.

• Perilaku backend yang tersedia melalui alat MCP—pemanggilan alat standar, bukan runtime agen khusus yang dikelola sepenuhnya.

• Penemuan di dalam ChatGPT—pengguna dapat menemukan alur kerja di tempat mereka sudah bekerja.

Kami memvalidasi pilihan tersebut bersama klien selama proses pengembangan. Konsekuensinya tetap sama: ketika ChatGPT meng-host sesi, Anda tidak mengendalikan runtime luarnya. Anda dapat mengarahkannya, tetapi tidak mengendalikannya sepenuhnya.

Aplikasi Apps SDK menghubungkan tiga hal:

1. Runtime agen ChatGPT

2. Alat MCP Anda

3. UI widget Anda

Alur dalam praktik:

1. Pengguna meminta sesuatu kepada ChatGPT.

2. ChatGPT dapat memanggil salah satu alat MCP Anda.

3. Server Anda mengembalikan hasil alat yang terstruktur.

4. ChatGPT membaca hasil tersebut dan menentukan langkah berikutnya: pemanggilan alat tambahan, balasan kepada pengguna, atau keduanya. Jika Anda menautkan widget ke alat tersebut, widget dapat muncul pada giliran ini.

5. Pengguna melanjutkan melalui chat atau widget (teks lanjutan, pilihan, atau pemanggilan alat yang dipicu widget). Tindakan tersebut memperbarui utas; ChatGPT menjalankan giliran lain dan langkah 2–4 berulang hingga tugas selesai.

Intinya adalah perpaduan antara chat, tindakan backend, dan langkah UI singkat tersebut. Ini juga berarti bagian yang rentan adalah transisi antara chat, alat, dan UI.

Anda tidak perlu membangun ulang UI chat, integrasi alat, pola autentikasi, atau kerangka widget dari awal. Bagi banyak produk, hal ini memangkas banyak waktu pengembangan sehingga Anda dapat berfokus pada logika domain dan mekanisme pengaman.

Membangun di dalam ChatGPT tidak sama dengan menjalankan agen Anda sendiri. Bagian tersulit dalam proyek ini bukanlah trik prompt. Tantangannya adalah membuat alat, widget, dan langkah berikutnya cukup eksplisit agar model dan UI tetap selaras.

Apps SDK menawarkan bentuk produk yang berbeda dari frontend biasa, sehingga penting untuk mengetahui skenario yang paling cocok untuknya.

Gunakan Apps SDK jika Anda ingin

• Merilis alur kerja ChatGPT dengan cepat.

• Menyerahkan pengelolaan percakapan kepada ChatGPT.

• Menggabungkan bahasa alami dengan beberapa langkah UI yang terfokus.

• Menghindari pembangunan antarmuka chat, kontainer agen, dan mekanisme penemuan sendiri.

Poin terakhir itu penting jika pengguna Anda sudah terbiasa bekerja di ChatGPT.

Bangun agen Anda sendiri jika Anda memerlukan

• Alur langkah demi langkah yang tetap dan dapat diterapkan melalui kode.

• UI khusus dan jalur konfirmasi yang Anda kendalikan sepenuhnya.

• Model memori dan status Anda sendiri.

• Perilaku yang harus dapat diprediksi pada setiap eksekusi.

• Rekaman jejak, log, dan metrik untuk agen.

Jika perencana, prompt sistem, dan seluruh alur kerja merupakan produk Anda, stack khusus biasanya lebih sesuai.

Dalam proyek kami, satu kata yang terus muncul adalah kendali: di satu sisi ada kecepatan dan platform yang sudah familier; di sisi lain ada kepemilikan runtime yang hanya sebagian. Itulah konsekuensi yang diterima klien ketika memprioritaskan menjangkau pengguna di ChatGPT daripada mengendalikan seluruh stack.

Alur idealnya terdengar mudah: pengguna meminta sesuatu, alat berjalan, data kembali, lalu widget muncul ketika pengguna perlu menentukan pilihan.

Dalam praktiknya, masalah utama terletak pada transisi. Widget bukan sekadar hiasan. Begitu muncul di layar, widget mengubah apa yang dilihat dan dilakukan model selanjutnya. Perlakukan tindakan widget seperti peristiwa bernama, bukan chat bebas.

Stack dalam proyek tersebut cukup sederhana: FastMCP, Pydantic, React, dan TypeScript. Mengintegrasikannya tidak menjadi masalah. Tantangan sebenarnya adalah menyelaraskan model, alat, dan UI mengenai tindakan berikutnya.

Perjelas setiap transisi

Kami berhenti memperlakukan hasil alat sebagai payload backend mentah. Setiap hasil yang dikembalikan menjadi sebuah transisi.

Hasil alat yang baik:

• Memberikan data yang diperlukan widget untuk dirender.

• Memberikan fakta terstruktur kepada ChatGPT sebagai dasar balasan.

• Jika diperlukan oleh alur, menjelaskan tindakan berikutnya agar model tidak perlu menebak.

Tindakan widget tidak boleh mengirimkan teks yang samar kembali ke utas. Pesan tersebut harus menjelaskan tindakan pengguna dan langkah berikutnya.

Keandalan meningkat setelah transisi dibuat jelas.

Model mengikuti instruksi yang singkat dan jelas ketika instruksi tersebut tersedia dalam output alat dan tindakan widget.

Berikut adalah struktur Pydantic kecil yang kami gunakan. Kolom output memuat data terstruktur yang diperlukan widget saat ditampilkan, serta fakta yang harus digunakan ChatGPT dalam sesi. Kolom agent_directions memuat satu baris singkat yang menjelaskan tindakan asisten selanjutnya. Reason bersifat opsional.

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

Jaga agar widget tetap sederhana

Widget yang berhasil menangani satu keputusan, lalu mengembalikan kendali. Daftar singkat, konfirmasi, atau layar peninjauan yang ringkas bekerja lebih baik daripada mengubah widget menjadi aplikasi mini. Sedikit logika di dalam widget, seperti validasi sederhana atau langkah berikutnya yang tetap, tetap membantu ketika kami menginginkan alur yang lebih deterministik.

Sudut pandang orang ketiga dalam pesan widget

Kami berhenti menulis tindak lanjut widget seolah-olah berasal dari chat pengguna ("Saya memilih...", "Saya mengonfirmasi..."). Kami menulisnya sebagai laporan singkat tentang tindakan pengguna ("Pengguna memilih...", "Pengguna mengonfirmasi..."). Kami mencoba pendekatan ini karena ChatGPT menambahkan pesan widget sebagai pesan alat, bukan pesan pengguna.

Tindakan langsung ketika langkah berikutnya sudah jelas

Jika sebuah tombol jelas mengarah pada pemanggilan alat berikutnya, membiarkan widget memicunya secara langsung bekerja lebih baik daripada memaksakan giliran chat tambahan. Ini hanya berlaku jika pemanggilan alat berikutnya tidak memerlukan input dari ChatGPT.

Pendekatan ini membantu menerapkan alur deterministik sekaligus mengurangi latensi karena tidak memerlukan giliran chat tambahan.

Penanganan kesalahan

Ketika pemanggilan alat gagal, kami mengembalikan kode kesalahan MCP yang tepat dan pesan singkat yang lugas dari alat. Dengan demikian, ChatGPT memiliki informasi nyata untuk dibaca ketika pemanggilan gagal, sehingga dapat menjelaskan masalah kepada pengguna dan/atau memilih langkah berikutnya yang masuk akal.

Pengelolaan konteks alat

Kami menyimpan status sesi di server kami. ChatGPT mengirimkan konteks dalam cakupan sesi bersama pemanggilan alat; di FastMCP, kami memberikan parameter Context kepada setiap alat agar handler dapat membaca dan memperbarui status tersebut.

• ID stabil dan hasil sebelumnya disimpan dalam sesi, sehingga ChatGPT tidak perlu mengirimkannya lagi sebagai argumen alat pada setiap pemanggilan.

• Ketika terjadi perulangan pemanggilan alat, kami dapat mendeteksi pemanggilan duplikat dan mengembalikan kesalahan yang jelas melalui hasil alat.

• Log sesi tetap berada di sisi kami untuk keperluan debug dan dukungan.

Pada tahap awal, kami menampilkan widget, berasumsi bahwa model “memahaminya”, lalu menunggu pemanggilan alat lanjutan yang tepat. Terkadang hal itu terjadi. Namun, sering kali tidak.

Tanpa transisi yang jelas, ChatGPT mungkin membuat ringkasan ketika kami menginginkan tindakan, meminta pengguna mengulangi pilihan, atau terus menyusun rencana ketika seharusnya berhenti.

Solusinya adalah menjabarkan langkah berikutnya dalam output terstruktur dan payload widget, bukan berharap model akan menyimpulkannya.

Kami mencoba mengikuti dokumentasi Apps SDK dengan membagi respons secara cerdik antara output alat, metadata tersembunyi, dan teks chat. Namun, kami tidak dapat membaca metadata tersembunyi di dalam widget. Karena itu, kami tidak dapat menggunakan pendekatan ini.

Dokumentasi Apps SDK menjelaskan alat yang dapat disembunyikan dari daftar alat agen agar tidak dipilih olehnya, tetapi tetap dapat dipanggil dari widget. Ketika visibilitas diatur ke khusus aplikasi, alat tersebut juga tidak lagi tersedia dari widget, bukan hanya dari agen. Kami tidak pernah berhasil membuat konfigurasi yang menyembunyikan alat dari agen tetapi tetap membuatnya tersedia bagi widget.

Tidak ada respons atau pesan umum “berhasil” ketika tidak ada hasil yang berguna lebih buruk daripada kesalahan langsung. Karena itu, kami menjadikan kegagalan alat dan widget sebagai output utama: jika suatu langkah tidak dapat dilanjutkan, kami menyampaikannya dengan bahasa lugas dan mengembalikan kesalahan eksplisit, bukan membiarkan pengguna menatap widget yang berhasil dirender tetapi tidak membantu mereka melanjutkan. Hal ini meningkatkan kemudahan penggunaan dan membuat perilaku model lebih andal.

Jika tujuan Anda adalah menghadirkan alur kerja di ChatGPT dengan lebih sedikit pekerjaan platform khusus, Apps SDK merupakan cara praktis untuk mencapainya. Sebagai gantinya, Anda melepaskan sebagian kendali demi kecepatan dan menjangkau pengguna di tempat mereka sudah bekerja.

Jika Anda perlu mengendalikan setiap percabangan alur, UI, dan pihak yang menentukan setiap langkah, rencanakan stack agen Anda sendiri sejak awal. Kemungkinan besar, membangun hanya di dalam ChatGPT pada akhirnya tidak lagi memadai.

Anda juga dapat menggunakan Apps SDK untuk menjalankan server MCP di dalam ChatGPT sebelum membangun sendiri chat, autentikasi, dan integrasi agen, lalu beralih ke stack sendiri ketika produk membutuhkannya.

Langkah berikutnya bagi tim dengan situasi serupa: pilih satu alur kerja dengan hasil yang jelas, catat transisi antara chat, alat, dan widget, lalu uji percobaan ulang dan kesalahan secara intensif sebelum menghabiskan banyak waktu untuk menyempurnakan prompt.