GraphQL, yapay zekâ ajanlarının beklediği dil

GraphQL 2015’te ön yüz işini hızlandırmak için tasarlandı. Akıllı sorular soran makineler için mükemmel bir arayüz olduğu ortaya çıktı.

Önceki yazıda sav şuydu: yapay zekâ ajanları yazılımın ana kullanıcıları haline geldiği için her uygulamanın programlama arayüzünü öne koyması gerekiyor. Ürün programlama arayüzü. Kullanıcı arayüzü onun kullanıcılarından biri.

Bu sav, neredeyse kimsenin henüz sormadığı ama herkesin sorması gereken bir sonraki soruyu bırakıyor: hangi tür programlama arayüzü kurulmalı?

Ajanların yazılımı gerçekte nasıl kullanmaya çalıştığına dikkatle bakıldığında cevap güçlü biçimde tek bir yönü gösteriyor. GraphQL. Moda olduğu için değil: on yıllık bir teknoloji. Daha çok, GraphQL’i REST’ten ayıran belirli özelliklerin, ajanların döngüde insan olmadan çalışmak için ihtiyaç duyduğu şeyle neredeyse kusursuz biçimde örtüşmesi yüzünden.

Sanki Facebook 2015’te kazara ajan döneminin sorgu dilini kurmuş ve sektör sonraki on yılı onu esasen React uygulamalarını biraz daha rahat kılmak için kullanarak geçirmiş gibi. Bu onu kesinlikle hafife almak.

Bulma sorunu

İşte bir programlama arayüzünün makineler için değil insanlar için kurulduğunun en açık işareti: belge sayfası. Ad olarak listelenmiş erişim noktaları. Ne aradığını zaten bilen biri için yazılmış örnekler. Son yeniden düzenlemeden beri kimsenin güncellemediği bir sürüm geçmişi. Bir mühendislik insanı geldiğinde belgeleri okuyor, kaynakların haritasını kafasında tutuyor ve ihtiyaç duyduğu veriyi almak için belirli, önceden planlanmış çağrı dizileri yürüten kod yazıyor. Belgeler tek seferlik bir giriş maliyeti.

Ajanlar böyle çalışmıyor. Bir ajan programlama arayüzünüze bir hedefle geliyor (mühendislik ekibine atanmış en yüksek öncelikli üç açık talebi bul ve en son etkinliklerini özetle) ve o hedefi işlemlere nasıl ayıracağını anında belirlemesi gerekiyor. Hazır bir entegrasyon yok. Belgeleri okuyan deneyimli bir kişi yok. Ajan arayüzünüz hakkında gerçek zamanlı olarak, ilk karşılaşmada akıl yürütüyor.

Buna bulma sorunu diyelim: bir ajan uygulamanıza içinde ne olduğunu bilmeden geliyor ve o bilmemenin bedeli yürütmeye çalıştığı her akışta ödeniyor. REST ile ajanın hangi erişim noktalarının var olduğunu tahmin etmesi, bir çağrı yapması, veri biçimini anlamak için yanıta bakması, başka bir yerden ilişkili veriye ihtiyaç duyduğunu fark etmesi, başka bir çağrı yapması, sonuçları ilişkilendirmesi, sayfalamayı işlemesi ve tekrar etmesi gerekiyor; bu süre boyunca ihtiyaç duymadığı veri için bağlam penceresini yakıyor.

GraphQL bulma sorununu çökertiyor. Ajan tek bir iç gözlem sorgusu yapıp yanıt olarak tüm şemayı alabiliyor: her tip, her alan, her ilişki, her argüman, her tanım. Şema, gerçeklikten sapabilecek ayrı bir yapıntı değil. O, gerçekliğin kendisi. Sorguları çözen aynı koddan doğuyor.

Bir ajan için bu, bir şehri haritasız gezmek ile navigasyonla başlamak arasındaki fark.

İç gözlem kendini belgelemektir

Her GraphQL arayüzü kendini belgeliyor. REST arayüzlerinin biri OpenAPI belirtimini güncellemeyi hatırladığında “kendini belgelediği” gevşek ve iyi dilekli anlamda değil. GraphQL arayüzleri harfi harfine kendini belgeliyor, tasarım gereği, protokolün temel bir özelliği olarak.

Bu ajanlar için belirli bir biçimde önemli. Tek bir veri isteği yapmadan önce ajan arayüze sorabiliyor: neler yapabiliyorsun? Hangi verilerin var? Bunların hepsi nasıl bağlanıyor? Ve arayüz eksiksiz, doğru ve işlenmesi önemsiz biçimde cevap veriyor.

Son müşteri faturalandırma şikâyetlerini bulması gereken bir ajan düşünün. Şemayı inceliyor ve tickets alanı olan bir Customer tipi, taleplerin BILLING içeren bir category numaralandırması olduğunu, taleplerin createdAt zaman damgası ve status alanı taşıdığını, her talebe bağlı bir comments bağlantısı olduğunu keşfediyor. Saniyeler içinde veri modelinin tam haritasına sahip; güncel olabilecek ya da olmayabilecek belgelerden değil, yaşayan sistemin kendisinden.

Bu, Anthropic’in yapay zekâ yardımcılarının harici araçları bulup çağırmasına imkân veren standardı Model Context Protocol’ün esasen her tür programlama arayüzüne sonradan eklemeye çalıştığı özellik. GraphQL şeması zaten MCP biçiminde bir bildirim. İkisi de aynı dili konuştuğunda protokol ile veri modeli yolun ortasında buluşuyor.

Tam olarak gerekeni istemek

REST arayüzleri sabit veri yapıları döndürüyor. /api/users/123 çağırıyorsunuz ve sunucunun kullanıcı yanıtına dahil etmeye karar verdiği her şeyi alıyorsunuz: ad, posta adresi, ikamet adresi, tercihler, görsel adresi, hesap oluşturma tarihi, son giriş damgası ve kırk başka alan. O kullanıcının son siparişlerine de ihtiyacınız varsa bu ayrı bir çağrı. O siparişlerdeki kalemlere ihtiyacınız varsa bu her sipariş için başka bir çağrı.

Programlama arayüzünün her kullanıcısı, fazla veriyi işlemek için kendi kodunu yazabilen ve gidiş gelişleri düzenleyebilen bir ön yüz insanı olduğunda bu anlamlıydı. Kullanıcı gerçek kısıtlar altında çalışan bir ajan olduğunda derinlemesine verimsiz.

Ajanların bağlam pencereleri var. Bir yanıttaki gereksiz her veri karakteri, akıl yürütmek, planlamak ya da başka bir ilgili bağlamı tutmak için kullanılabilecek bir karakter. Bir REST arayüzü 4 KB kullanıcı verisi döndürdüğünde ve ajan yalnızca ada ve posta adresine ihtiyaç duyduğunda, bu yalnızca boşa harcanmış bant genişliği değil. Boşa harcanmış bilişsel kapasite. Bunu çok adımlı bir akıştaki her çağrıyla çarpın ve ajanın bağlamı gürültüyle doluyor.

GraphQL bu sorunu ortadan kaldırıyor. Ajan tam olarak ihtiyaç duyduğu alanları belirtiyor:

query {
  user(id: "123") {
    name
    email
    recentOrders(first: 3) {
      status
      total
      items {
        productName
        quantity
      }
    }
  }
}

Tek istek. Tam olarak gerekli veri. Fazlası yok. Eksiği yok. Boşa harcanmış karakter yok. Ajan, bilgi ihtiyacına doğrudan karşılık gelen kesin bir cevap alıyor. Bu bir eniyileme değil: kullanıcının biçimi tanımladığı ve sunucunun onu nasıl bir araya getireceğini belirlediği, temelden farklı bir veri alma modeli.

Akıllı ajanların bir veri kaynağıyla konuşabilmesi gereken model bu. GraphQL’in on yıldır sessizce yürüttüğü model bu.

On iki istek yerine tek istek

REST’te verinin çok az gelmesi sorunu, fazla gelmesi sorunundan bile daha can sıkıcı ve GraphQL’in avantajı tam orada en belirgin hale geliyor.

Haftalık bir ekip durumu raporu hazırlaması gereken bir ajan düşünün. Ekip üyelerine, her kişiye atanmış görevlere, o görevlerin durumuna ve önceliğine, bu hafta değişmiş tüm görevlerin yorumlarına ve o görevlerin ait olduğu projelere ihtiyacı var. Tipik bir REST arayüzünde bu bir çağlayan: ekip listesini al, sonra her kişi için görevlerini, sonra her görev için yorumlarını ve projesini. Onlarca istek, her biri öncekine bağlı. Ajanın her şeyi düzenlemesi, her erişim noktasında sayfalamayı işlemesi, hız sınırlarıyla baş etmesi ve farklı yanıt biçimlerinden gelen veriyi birleştirmesi gerekiyor. Kavramsal olarak tek bir soru olan bir şey için çok fazla art arda mantık.

GraphQL’de bu tek bir sorgu. Tek gidiş geliş. Tüm veri, düzgün biçimde iç içe, tam olarak ajanın istediği biçimde. Ajanın düzenleme örüntüsünü anlaması gerekmiyor, geçici durum tutması gerekmiyor, erişim noktalarının nasıl bağlandığının haritasını kafasında tutması gerekmiyor. Kurtarılan her gidiş geliş, ortadan kalkan bir arıza biçimi, kurtarılan bir gecikme ve ajanın hiç yazmak zorunda kalmadığı bir düzenleme kodu parçası.

Özünde gereksiz karmaşıklığı azaltmaya çalışan bir akıl yürütme makinesi olan bir ajan için bu büyük bir avantaj.

Gömülü denetimli değiştirmeler

GraphQL’in avantajı veri okumada bitmiyor. Ajanların bir şey yapması gerektiğinde (kayıt oluşturmak, durum değiştirmek, akış başlatmak) GraphQL değiştirmeleri kendini denetleyen, düzenli ve öngörülebilir bir arayüz veriyor.

Bir ajan REST arayüzü üzerinden destek talebi oluşturduğunda JSON gövdeli bir POST isteği kurması gerekiyor ama o gövdenin kesin biçimi (hangi alanlar zorunlu, hangileri seçimlik, hangi tipler bekleniyor, hangi değerler geçerli) yalnızca harici belgelerde tanımlı. Yanlış yaparsa ajan bunu çalışma anında, yardımcı olabilecek ya da olmayacak bir hata yanıtıyla öğreniyor.

GraphQL değiştirmelerinin tipli girdi nesneleri var. Şema her argümanı, tipini, zorunlu olup olmadığını ve tanımını açıkça bildiriyor. Ajan çağırmadan önce değiştirmeyi inceleyebiliyor, geçerli yükü güvenle kurabiliyor ve dönüşte tam olarak ihtiyaç duyduğu doğrulama verisini isteyebiliyor. Tahmin yok. Deneme yanılma yok. Umutla birleştirilmiş sallantılı entegrasyonlar yok.

Bir makinenin bir uygulamayla konuşabilmesi gereken biçim bu.

Şema sözleşmedir

GraphQL şeması pratikte makine tarafından okunabilir bir yetenek bildirimi. Şunu duyuruyor: bu uygulamanın yapabildiği her şey burada, buna katılan veri tipleri burada, nasıl bağlandıkları burada, kullanılabilir işlemler burada. Bu, uygulamanız ile onu kullanmak isteyen her akıllı sistem arasındaki sözleşme.

Bir ajan bir GraphQL arayüzüne rastladığında özel bir entegrasyona ihtiyaç duymuyor. Bir bağlayıcıyı elle yazacak birine ihtiyaç duymuyor. Şemayı okuyup çalışmaya başlıyor. Şema, entegrasyon katmanının kendisi.

Archie Core’un çevresinde tasarlandığı özellik bu. Archie Core üzerinde kurulan her uygulama (ön yüz, arka uç ya da ikisi) bedavaya bir GraphQL şeması alıyor. Sonradan akla gelen bir şey olarak değil, bir eklenti olarak değil, ana arayüz olarak. Sonuç ince değil: Archie üzerinde yayına alınan her uygulama birinci günden ajanlara hazır, çünkü ajan o dili zaten konuşuyor.

Bir kullanıcı adına hangi araçların çağrılacağını giderek ajanların seçtiği bir ekonomide, birlikte çalışma kolaylığı teknik bir ayrıntı değil. Pazara giriş stratejisi.

Dürüst ödünleşmeler

GraphQL’in gerçek bir bedeli var ve olmadığını iddia etmek rahat olurdu. Bir GraphQL sunucusu kurmak REST erişim noktaları dikmekten daha fazla iş. Naif gerçekleştirmeler aşırı sayıda veritabanı sorgusu üretebilir (N+1 sorunu) ve bunu hafifletmek için DataLoader gibi örüntüler ve sorgu planlaması gerekir. Önbellekleme, adrese dayalı REST kaynaklarından daha zor; içerik dağıtım ağı katmanındaki önbelleklemeye güvenmek yerine kalıcı sorgular gibi uygulama düzeyinde stratejilere ihtiyacınız var. Ve uygulamanız asgari ilişkileri olan düz bir kaynak modeline sahipse REST tümüyle yeterli olabilir, ajanlar için de.

Bunlar bilinen çözümleri olan mühendislik zorlukları, temel sınırlar değil. Soru, bedelin ajan dönemi faydasına değip değmediği ve cevap bu geleceği ciddiye alan her uygulama için giderek evet.

Makinelerin düşünebileceği arayüzü kurun

Önce programlama arayüzü savı, ajanlar ana kullanıcılar haline geldiği için uygulamaların programlı arayüzler üzerinden tam olarak erişilebilir olması gerektiğini söylüyor. GraphQL savı bunun doğal uzantısı: arayüz, akıllı makinelerin onu asgari sürtünmeyle bulabileceği, anlayabileceği ve kullanabileceği biçimde tasarlanmalı.

GraphQL size kendini tanımlayan ve yaşayan bir yetenek bildirimi işlevi gören bir şema veriyor. Ajanın bağlam sınırlarına saygı duyan kesin veri alma. Tahmini ortadan kaldıran tipli değiştirmeler. Öngörücü davranışı mümkün kılan gerçek zamanlı abonelikler. Hepsi tek bir erişim noktası üzerinden, tek bir tekdüze sorgu diliyle.

REST, insanların entegrasyonları elle, erişim noktası erişim noktası yazdığı bir dünya için kuruldu. O dünya hâlâ var ve REST ona hâlâ iyi hizmet ediyor. Ama beliren dünya, ajanların uygulama yeteneklerini anında bulup birleştirdiği dünya, daha anlatımlı, daha iyi düzenlenmiş, incelemesi daha kolay bir şey gerektiriyor.

GraphQL artık yalnızca mühendislik için bir kolaylık değil. Akıllı ajanların düşünebileceği arayüz dili. Ve onu konuşan uygulamalar, önce uzanılacak olanlar olacak.

İlgili okumalar

Altındaki mimari gerekçe arayüz bir yalan yazısında, ticari sürümü ise önce programlama arayüzü için iş gerekçesi yazısında.

Sıkça sorulan sorular

GraphQL yapay zekâ ajanları için REST’ten neden daha iyi? GraphQL iç gözlem yoluyla kendini belgeliyor, ajanların tek bir gidiş gelişte tam olarak ihtiyaç duydukları alanları istemesine imkân veriyor ve değiştirmelerde tipli girdiyi zorunlu kılıyor. REST, ajanları erişim noktası biçimini tahmin etmeye, ilişkili veri için çok sayıda çağrıyı düzenlemeye ve zorunlu alanları deneme yanılmayla keşfetmeye zorluyor.

Bulma sorunu nedir? Bulma sorunu, bir yapay zekâ ajanının hangi veri ve işlemlerin kullanılabilir olduğunu bilmeden bir uygulamaya gelmesinin bedeli. REST arayüzleri ajanı tahmin etmeye zorluyor; GraphQL arayüzleri tüm şemayı döndüren tek bir iç gözlem sorgusuyla cevap veriyor.

GraphQL, Model Context Protocol (MCP) ile nasıl ilişkili? MCP, Anthropic’in yapay zekâ yardımcılarının harici araçları bulup çağırmasına imkân veren standardı. Bir GraphQL şeması zaten MCP biçiminde: MCP’nin sunmayı amaçladığı, makine tarafından okunabilir yetenek bildirimini veriyor. GraphQL uygulamaları ajan ekosistemiyle yolun ortasında buluşuyor.

GraphQL’in gerçek bedelleri ve karmaşıklığı yok mu? Var. GraphQL sunucuları REST erişim noktalarından kurması daha karmaşık. Önbellekleme daha zor. Naif gerçekleştirmelerde N+1 sorgu sorunları var. Bunlar bilinen çözümleri olan mühendislik zorlukları (DataLoader, kalıcı sorgular, şema planlaması), temel sınırlar değil.

Archie Core ana arayüz olarak neden GraphQL’i seçti? Archie Core, üzerinde kurulan her uygulamanın bedavaya bir GraphQL şeması almasını sağlayacak biçimde tasarlandı; bu da onu birinci günden yapay zekâ ajanları için bulunabilir ve kullanılabilir kılıyor. Ajanlara hazırlık, sonradan eklenmiş bir özellik değil mimarinin bir niteliği.