ChatGPT Apps SDK ile ürün sunarken öğrendiklerimiz

• ChatGPT’de kısa sürede bir iş akışı kullanıma sunmanız veya özel bir ajan yığınına yatırım yapmadan önce araçlarınızı orada denemeniz gerekiyorsa Apps SDK pratik bir seçenektir. Ajanın davranışındaki her adımın kontrolü sizde olmalıysa genellikle uygun değildir.

• Ana arayüz ChatGPT olacaksa ve eksiksiz bir sohbet ürünü geliştirmeden araçlarla birlikte küçük kullanıcı arayüzü öğeleri sunmak istiyorsanız Apps SDK’yı seçin. Akış, bellek, promptlar ve yazma işlemleri üzerinde sıkı denetim gerekiyorsa kendi ajan yığınınızı seçin.

• Apps SDK, sohbeti birkaç kısa kullanıcı arayüzü adımıyla birleştiren ürünlere uygundur. Daha hızlı kullanıma sunarsınız ancak kontrolün bir kısmından vazgeçersiniz.

• Bizim için işe yarayan; araçları, widget davranışını ve sonraki adımları netleştirmekti. Akışı belirlemek için LLM’ye değil, bunlara güvendik. Model en çok, sistemin önceden seçtiği sonuçları açıklarken yararlı oldu.

• Aşağıda önce nasıl seçim yapacağınızı, ardından nelerin işe yarayıp nelerin yaramadığını ele alıyoruz.

Çoğu ekip hâlâ yapay zekâ pilotları yürütüyor veya yapay zekâyı risk-getiri oranı düşük, ikincil kullanım alanlarında devreye alıyor. Her hafta kullanıcıların etkileşim kurduğu iş açısından kritik bir ürünü kullanıma sunanların sayısı az. Amacınız asistanın tamamını kendiniz geliştirmek yerine ChatGPT içinde yer almaksa ChatGPT Apps SDK bu açığı kapatmanın yollarından biridir.

Çıkarımlarımız, temel arayüz olarak ChatGPT’yi işaret eden ve müşterinin tamamen özel bir sohbet ürününü finanse etmesini gerektirmeyen hızlı bir çözüm talep edilen müşteri projesine dayanıyor.

Apps SDK bu beklentilere uygundu çünkü müşterinin şunlara ihtiyacı vardı:

• Geliştirilip barındırılacak ayrı bir sohbet ürünü olmaması—başka bir bağımsız asistan kabuğu değil, ChatGPT içinde erişim istiyorlardı.

• Sohbet ve göreve özel küçük kullanıcı arayüzleri—iş akışının içinde ikinci bir eksiksiz ürün değil, belirli amaçlara odaklanan birkaç widget adımı.

• MCP araçları üzerinden sunulan arka uç davranışı—uçtan uca sahip olunan özel bir ajan çalışma zamanı değil, standart araç çağırma işlevi.

• ChatGPT içinde keşfedilme—kullanıcılar iş akışıyla zaten çalıştıkları yerde karşılaşmalıydı.

Geliştirme sürecinde bu tercihleri müşteriyle birlikte doğruladık. Ödünleşim yine de geçerli: Oturumu ChatGPT barındırdığında dış çalışma zamanı size ait değildir. Yön verirsiniz ama tamamen kontrol edemezsiniz.

Bir Apps SDK uygulaması üç bileşeni birbirine bağlar:

1. ChatGPT’nin ajan çalışma zamanı

2. MCP araçlarınız

3. Widget kullanıcı arayüzünüz

Uygulamadaki akış:

1. Kullanıcı ChatGPT’den bir şey ister.

2. ChatGPT, MCP araçlarınızdan birini çağırabilir.

3. Sunucunuz yapılandırılmış bir araç sonucu döndürür.

4. ChatGPT bu sonucu okur ve sonraki adıma karar verir: yeni araç çağrıları, kullanıcıya yanıt veya her ikisi. Bu araca bir widget bağladıysanız widget bu turda gösterilebilir.

5. Kullanıcı sohbette veya widget’ta devam eder (takip metni, bir seçim ya da widget’ın tetiklediği araç çağrısı). Bu işlem ileti dizisini günceller; ChatGPT yeni bir tur çalıştırır ve görev tamamlanana kadar 2–4. adımlar tekrarlanır.

Asıl amaç sohbet, arka uç işlemleri ve kısa kullanıcı arayüzü adımlarını bu şekilde birleştirmektir. Bu aynı zamanda hassas noktaların sohbet, araçlar ve kullanıcı arayüzü arasındaki geçişler olduğu anlamına gelir.

Sohbet arayüzünü, araç bağlantılarını, kimlik doğrulama kalıplarını veya widget kabuğunu sıfırdan geliştirmeniz gerekmez. Bu, birçok üründe geliştirme süresini önemli ölçüde kısaltarak alan mantığına ve güvenlik önlemlerine odaklanmanızı sağlar.

ChatGPT içinde geliştirme yapmak, kendi ajanınızı çalıştırmakla aynı şey değildir. Projede zor olan kısım prompt hileleri değildi. Asıl zorluk; model ile kullanıcı arayüzünün uyumlu kalması için araçları, widget’ları ve sonraki adımları yeterince açık hâle getirmekti.

Apps SDK, alışılmış ön uçlardan farklı bir ürün yapısı sunar; ancak hangi senaryolar için ideal olduğunu bilmek önemlidir.

Şunları istiyorsanız Apps SDK’yı kullanın:

• Bir ChatGPT iş akışını hızla kullanıma sunmak.

• Sohbeti ChatGPT’nin barındırmasını sağlamak.

• Doğal dili belirli amaçlara odaklanan birkaç kullanıcı arayüzü adımıyla birleştirmek.

• Kendi sohbet arayüzünüzü, ajan kapsayıcınızı ve keşif mekanizmanızı geliştirmekten kaçınmak.

Kullanıcılarınız zaten ChatGPT’de çalışıyorsa bu son nokta önemlidir.

Şunlara ihtiyacınız varsa kendi ajanınızı geliştirin:

• Kodla zorunlu kılabileceğiniz sabit ve adım adım ilerleyen bir akış.

• Uçtan uca size ait özel bir kullanıcı arayüzü ve onay süreci.

• Kendi bellek ve durum modeliniz.

• Her çalıştırmada öngörülebilir olması gereken davranışlar.

• Ajan için izler, günlükler ve metrikler.

Planlayıcı, sistem promptları ve iş akışının tamamı ürününüzün temelini oluşturuyorsa özel bir yığın genellikle daha uygundur.

Projemizde sürekli öne çıkan kavram kontroldü: Bir tarafta hız ve tanıdık bir barındırma ortamı, diğer tarafta çalışma zamanının yalnızca kısmen size ait olması. Müşteri, yığının tamamına sahip olmak yerine kullanıcılarla ChatGPT’de buluşmaya öncelik verirken bu ödünleşimi kabul etti.

Sorunsuz senaryo kolay görünür: Kullanıcı ister, araç çalışır, veriler gelir ve seçim gerektiğinde widget görünür.

Uygulamada asıl sorun geçişlerdi. Widget bir süs değildir. Ekranda göründüğü anda modelin ne gördüğünü ve sonraki adımda ne yaptığını değiştirir. Widget eylemlerini serbest sohbet olarak değil, adlandırılmış olaylar olarak ele alın.

Projede kullandığımız yığın oldukça basitti: FastMCP, Pydantic, React ve TypeScript. Bunları entegre etmek sorun olmadı. Asıl iş, modelin, araçların ve kullanıcı arayüzünün bir sonraki adım konusunda uzlaşmasını sağlamaktı.

Her geçişi belirgin hâle getirin

Araç sonuçlarını ham arka uç yükleri olarak ele almayı bıraktık. Her dönüş bir geçiş hâline geldi.

Sağlam bir araç sonucu:

• Widget’a görüntüleme için gerekenleri sağlar.

• ChatGPT’ye yanıtını dayandırabileceği yapılandırılmış olgular sunar.

• Akış gerektiriyorsa modelin tahmin yürütmesine gerek kalmaması için bir sonraki adımda ne olacağını belirtir.

Widget eylemleri ileti dizisine belirsiz ifadeler göndermemelidir. Kullanıcının ne yaptığını ve ardından ne olması gerektiğini belirtmelidir.

Geçişler netleşince güvenilirlik arttı.

Model, araç çıktısında ve widget eylemlerinde yer alan kısa ve açık talimatları izler.

Aşağıda kullandığımız küçük bir Pydantic şeması yer alıyor. output alanı, gösterildiğinde widget’ın ihtiyaç duyduğu yapılandırılmış verileri ve ChatGPT’nin oturumda kullanması gereken olguları içerir. agent_directions alanı, asistanın bir sonraki adımda ne yapması gerektiğini belirten kısa bir satır içerir. Reason isteğe bağlıdır.

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

Widget’ları küçük tutun

İşe yarayan widget’lar tek bir karar aldırıp kontrolü geri verdi. Kısa listeler, onaylar veya odaklı bir inceleme ekranı, widget’ı mini uygulamaya dönüştürmekten daha iyi sonuç verdi. Akışın daha belirli olmasını istediğimizde basit doğrulama veya sabit bir sonraki adım gibi az miktarda widget mantığı yine fayda sağladı.

Widget mesajlarında üçüncü şahıs kullanın

Widget takip mesajlarını kullanıcının ağzından sohbet metni gibi yazmayı bıraktık ("Şunu seçtim," "Şunu onayladım"). Bunları kullanıcının ne yaptığını bildiren kısa raporlar olarak yazdık ("Kullanıcı şunu seçti," "Kullanıcı şunu onayladı"). Bu yaklaşımı denedik çünkü ChatGPT, widget mesajlarını kullanıcı mesajı yerine araç mesajı olarak ekliyordu.

Sonraki adım belliyse doğrudan eyleme geçin

Bir düğme sonraki araç çağrısını açıkça belirtiyorsa widget’ın bunu doğrudan tetiklemesi, yeni bir sohbet turunu zorunlu kılmaktan daha iyi sonuç verdi. Bu yalnızca sonraki araç çağrısı ChatGPT’den girdi gerektirmiyorsa geçerlidir.

Bu yöntem, belirli akışları uygulamayı kolaylaştırdı ve yeni bir sohbet turunu önleyerek gecikmeyi azalttı.

Hata yönetimi

Bir araç çağrısı başarısız olduğunda araçtan doğru MCP hata kodlarını ve kısa, anlaşılır mesajları döndürdük. Böylece ChatGPT, başarısız çağrılarda okuyabileceği somut bilgiler elde etti; sorunu kullanıcıya açıklayabildi ve/veya uygun bir sonraki adımı seçebildi.

Araç bağlamı yönetimi

Oturum durumunu kendi sunucumuzda tuttuk. ChatGPT, araç çağrılarıyla birlikte oturuma özgü bağlam gönderir; FastMCP’de her araca bir Context parametresi vererek işleyicinin bu durumu okuyup güncellemesini sağladık.

• ChatGPT’den bunları her çağrıda araç bağımsız değişkeni olarak yeniden iletmesini istemek yerine kararlı kimlikleri ve önceki sonuçları oturumda tuttuk.

• Araç çağrısı döngüleri oluştuğunda yinelenen çağrıları yakalayıp araç sonucu üzerinden açık bir hata döndürebildik.

• Hata ayıklama ve destek için oturum günlüklerini kendi tarafımızda tuttuk.

Başlangıçta bir widget gösterip modelin “anladığını” varsaydık ve doğru takip araç çağrısını bekledik. Bazen gerçekleşti. Çoğu zamansa gerçekleşmedi.

Net bir geçiş olmadığında ChatGPT, eylem beklediğimiz yerde özet çıkarabiliyor, kullanıcıdan seçimini tekrarlamasını isteyebiliyor veya durması gerekirken planlama yapmayı sürdürebiliyordu.

Çözüm, modelin tahmin etmesini ummak yerine sonraki adımı yapılandırılmış çıktılarda ve widget yüklerinde açıkça belirtmekti.

Apps SDK belgelerinde belirtildiği gibi yanıtları araç çıktısı, gizli meta veriler ve sohbet metni arasında ustaca bölmeyi denedik. Ancak widget’lardan gizli meta verileri okuyamadık. Bu nedenle bu yöntemi kullanamadık.

Apps SDK belgeleri, widget’tan çağrılmaya devam ederken ajanın seçmemesi için araç listesinden çıkarabileceğiniz araçları açıklıyor. Görünürlüğü yalnızca uygulama olarak ayarladığımızda bu araçlara yalnızca ajan değil, widget da erişemedi. Ajanın göremediği ancak widget’ın erişebildiği bir araç yapılandırması oluşturamadık.

Yararlı hiçbir şey gerçekleşmediğinde sessizlik veya genel bir “başarılı” mesajı, doğrudan hata vermekten daha kötüydü. Bu yüzden araç ve widget hatalarını başlı başına çıktılar olarak ele aldık: Bir adım devam edemiyorsa bunu açıkça belirttik ve kullanıcıları görüntülenmesine rağmen ilerleme sağlamayan bir widget’la baş başa bırakmak yerine net bir hata döndürdük. Bu yaklaşım kullanılabilirliği artırdı ve model davranışını daha güvenilir hâle getirdi.

Amacınız daha az özel platform çalışmasıyla ChatGPT içinde bir iş akışı oluşturmaksa Apps SDK bunu başarmanın pratik bir yoludur. Hız kazanmak ve kullanıcılarla zaten çalıştıkları yerde buluşmak için kontrolün bir kısmından vazgeçersiniz.

Akışın her dalına, kullanıcı arayüzüne ve her adımda kimin karar verdiğine sahip olmanız gerekiyorsa en başından kendi ajan yığınınızı planlayın. Muhtemelen yalnızca ChatGPT içinde geliştirme yaklaşımının sınırlarını aşacaksınız.

Sohbet, kimlik doğrulama ve ajan altyapısını kendiniz geliştirmeden önce MCP sunucunuzu ChatGPT içinde çalıştırmak için Apps SDK’yı kullanabilir, ürün gerektirdiğinde kendi yığınınıza geçebilirsiniz.

Aynı durumdaki ekipler için sonraki adım: Sonucu net bir iş akışı seçin, sohbet, araçlar ve widget’lar arasındaki geçişleri yazılı hâle getirin; prompt ayarına fazla zaman ayırmadan önce yeniden denemeleri ve hataları yoğun biçimde test edin.