a2’de bir işin yolculuğu

Çalışma masası — 10

Bir işin başlangıcı çoğu zaman kısa bir cümle: “Bu veriyi düzenle.”

Fakat bu cümlenin içinde henüz verilmemiş kararlar var. Hangi alanlar kalacak? Hangilerinin adı değişecek? Boşluklar temizlenecek mi? Aynı kayıttan iki tane varsa ikisi de korunacak mı?

a2’de bir işin yolculuğunu, bu kararların küçük ve izlenebilir parçalara ayrılması üzerinden düşünmek istiyorum.

Bunun için projenin örnek dosyalarındaki basit bir dönüşümü ele alacağım. Gerçek kullanıcı verisi içermeyen, iki kayıtlık bir iş.

İstekten açık kurala

Örnek girdide her kaydın bir kodu, adı ve kullanılmayacak bir alanı var:

{
  "code": "A1",
  "name": "  First item  ",
  "ignored": "discard"
}

İstenen dönüşüm küçük: code alanı id, name alanı label olacak. Adın başındaki ve sonundaki boşluklar temizlenecek. Diğer alanlar çıktıya alınmayacak.

Ama işin kuralı burada bitmiyor. Bütün kayıtların korunması ve bu örnekte sorun kaydı üretilmemesi de sözleşmenin parçası.

Bu ayrıntılar, “düzenle” kelimesinin açık bıraktığı alanı daraltıyor. Hangi değişikliklerin yapılabileceğini ve hangilerinin yapılmaması gerektiğini belirliyor.

İlk önemli parça, veriden önce bu sözleşme.

Girdinin içeri alınması

Bir görev modele ulaşmadan önce de reddedilebilir.

a2’nin veri yolunda yerel girdinin beklenen yapıda olması gerekiyor. JSON içinde yinelenen anahtarlar veya geçersiz sayısal değerler kabul edilmiyor. Girdi boyutu da sınırlı.

Bunlar, görevin anlamını çözmüyor. Daha temel bir soruyu cevaplıyor: Elimizde açık biçimde okuyabildiğimiz bir veri var mı?

Örneğin aynı nesnede iki kez yazılmış bir alan adını sessizce kabul etmek, daha dönüşüm başlamadan hangi değerin esas alındığını belirsizleştirebilir.

Bu nedenle girdiyi kabul etmek de işin bir adımı. Dosyanın bulunması, işlenmeye hazır olduğu anlamına gelmiyor.

İşi hangi yoldan yapacağız?

a2’de her görev aynı yoldan ilerlemiyor.

Bu dönüşüm için daha önce doğrulanmış ve sözleşmesi tam olarak eşleşen bir beceri varsa, data apply onu doğrudan çalıştırabiliyor. Bu yolda model çağrısı yapılmıyor.

Buradaki eşleşme, iki işin birbirine benzemesinden daha dar. Dönüşüm ailesi, kayıtlı sözleşme ve sözleşme sürümü birlikte değerlendiriliyor. Uygun beceri yoksa veya seçim belirsizse çalışma bir raporla duruyor. Kendiliğinden modele geçip başka bir çözüm denemiyor.

Modelle çözüm üretmek ve yeni bir beceri öğrenmek ayrı yollar.

Bu ayrım, işin nasıl yürütüldüğünü anlamayı kolaylaştırıyor. Hazır bir parçayı yeniden mi kullandık, yeni bir çözüm mü ürettik, yoksa yeniden kullanılabilir bir beceri adayı mı hazırladık?

Ortaya çıkan dosya benzer olsa bile bu yolların dayanakları ve maliyetleri farklı.

Çıktıyla karşılaşmak

Örnekteki ilk kaydın beklenen dönüşümü şöyle:

{
  "id": "A1",
  "label": "First item"
}

İkinci kayıt da aynı kurallarla dönüştürülüyor. Tam çıktı, dönüştürülmüş kayıtların bulunduğu rows ve sorunların bulunduğu issues alanlarını taşıyor.

Burada iki ayrı inceleme var.

İlki, çıktının beklenen yapıda olup olmadığı. İkincisi, bağımsız hazırlanmış beklenen sonuçla uyuşup uyuşmadığı.

a2’nin örnek dosyalarında beklenen cevap ayrı tutuluyor. Görevi çözen modele referans cevap verilmiyor. Kontrol, üretilen sonuç üzerinde dışarıdan yapılıyor.

Bu örnekte bütün kayıtların korunması gerektiği için karşılaştırma, yinelenen kayıtların sayısını da koruyarak yapılıyor. Düzenli görünen bir çıktı, eksik bir kaydı gizleyememeli.

Beklenen sonuç sağlanmadığında ise rapor yalnız şema kontrolü yapıldığını belirtiyor. Böyle bir raporu okurken “başarılı” durumunun hangi doğrulama kapsamıyla verildiğine bakmak gerekiyor.

Bir işi başka bir işe bağlamak

Dönüştürülen kayıtların daha sonra başka bir dosyayla eşlenmesini isteyebiliriz.

Bu artık tek becerilik örnekten daha geniş bir iş. İlk adımın çıktısının ikinci adımın hangi girdisine bağlanacağı açıkça tanımlanmalı.

a2’nin data pipeline yolu, çağıranın hazırladığı sıralı planları çalıştırıyor. Önceki adımdan rows veya issues alanları belirli girişlere aktarılabiliyor. Bu bağlantı sırasında örtük bir alan dönüştürme yapılmıyor.

Bir adım başarısız olursa sonraki adımlar yürütülmüyor. Ara sonuçta sorunlar varsa bunların sonraki adıma nasıl taşınacağı da açık olmalı. Sorunları aktarmak, anlamlarının korunduğunu tek başına kanıtlamıyor; sonucun ayrıca kontrol edilmesi gerekiyor.

Modelden plan önerisi istemek de mümkün. Ancak öneri üretmek ve planı çalıştırmak ayrı işlemler. Önerilen plan, hedefin doğru çözüleceğine dair bir onay sayılmıyor.

Böylece işin yolculuğunda bir karar noktası daha oluşuyor: Bu parçalar gerçekten istenen işi yapacak biçimde mi birleşti?

İşin sonunda kalan kayıt

Sonunda yalnız dönüştürülmüş veri bulunmasını yeterli görmüyorum.

Hangi beceri kullanıldı? Hangi kontrol yapıldı? Çalışma tamamlandı mı, geçersiz bir sonuç mu üretti, yoksa bir sınırda mı durdu?

a2’nin raporları, yürütülen yola göre bu soruların izlerini taşıyor. Doğrudan kullanımda seçilen beceri ve doğrulama kapsamı; çok adımlı yürütmede tamamlanan adımlar ve kullanılan becerilerin kod özetleri kaydediliyor.

Yeni bir beceri öğrenilecekse bunun da ayrı bir doğrulama yolu var. Tek görevde doğru cevap üretmek, aynı işlemin başka girdilerde çalışacağını göstermiyor.

Bu iki kayıtlık örnekten çıkarabileceğimiz sonuç da sınırlı. Örneğin açık bir sözleşmesini ve kontrol edilebilir bir beklenen cevabını gösterebiliriz. Buradan gerçek işlerde genel verimlilik veya geniş doğruluk sonucu çıkaramayız.

a2’de izlemek istediğim yolculuk şu: İsteğin kurala dönüşmesi, uygun yürütme yolunun seçilmesi, çıktının sınanması ve geride okunabilir bir kayıt kalması.

Bir sonraki iş geldiğinde, önceki dosyanın yanına dönüp şu soruyu sorabilmek için:

Burada tam olarak neyi başarmıştık ve hangi koşullarda ona yeniden güvenebiliriz?

---

Kaynak notu — 15 Ekim 2026: Yazı, a2’nin paketlenmiş örnek girdileri ve beklenen sonuçları ile mevcut veri, yeniden kullanım, planlama ve sıralı yürütme koduna dayanır. İki kayıtlık dönüşüm, projedeki öğretici örnektir; gerçek kullanıcı çalışması değildir. Ardından eşleme yapılması, akışı açıklayan bir genişletme örneğidir. Bu yazı için yeni model çağrısı veya değerlendirme koşusu yapılmamıştır.

a2 proje sayfası · Önceki yazı: Bir ajan ne zaman durmalı?