12-Factor Agents: Güvenilir LLM Uygulama Kalıpları

 (github.com/humanlayer)
1 puan yazan GN⁺ 2025-04-17 | 1 yorum | WhatsApp'ta paylaş
  • 12-Factor Agents, üretim ortamındaki müşterilere sunulabilecek kadar güvenilir LLM tabanlı yazılımlar geliştirmek için 12 ilkeyi derleyen açık bir rehberdir
  • İyi bir agent’ın, “bir prompt ve araç seti verip hedefe ulaşana kadar yineleme” biçiminden çok, büyük ölçüde deterministik yazılımın gerekli noktalarına LLM adımlarının yerleştirildiği bir yapıya daha yakın olduğu savunulur
  • Tipik bir agent döngüsünde LLM, sonraki adımı yapılandırılmış JSON araç çağrısı olarak belirler; deterministik kod bunu çalıştırır, sonucu bağlam penceresine ekler ve tamamlanana kadar yineleme sürer
  • Birçok SaaS geliştiricisinin framework’lerle hızlı başlayıp %70–80 kaliteye ulaştığı, ancak bunun customer-facing özellikler için yetersiz kaldığı; bu yüzden framework’ü, prompt’ları ve akışı tersine mühendislikle çözmeye ya da baştan başlamaya yöneldikleri söylenir
  • Yüksek kaliteli AI yazılımını müşterilere en hızlı sunmanın yolu, tüm bir agent framework’ünü benimsemektense küçük ve modüler agent geliştirme kavramlarını mevcut ürüne entegre etmektir

Projenin çıkış noktası

  • 12-Factor Agents, 12 Factor Apps yaklaşımının ruhunu LLM uygulamaları geliştirme ilkelerine uygulamayı amaçlayan açık bir projedir
  • Temel soru şudur: “Üretim ortamındaki müşterilere emanet edilebilecek kadar gerçekten iyi LLM tabanlı yazılımlar geliştirmek için hangi ilkeler kullanılabilir?”
  • Çıkış noktası, çeşitli agent framework’lerini deneme ve YC içinden ve dışından teknik kurucularla yapılan görüşmelerdir
    • Birçok kurucu, production customer-facing agent’larda framework’leri yoğun biçimde kullanmaktan ziyade kendi stack’lerini kuruyor
    • “AI Agent” diye adlandırılan birçok ürünün tamamen agentic olmaktan çok, çoğunlukla deterministik koda uygun yerlerde LLM adımları eklenmiş bir biçimde olduğu düşünülüyor

Agent’lara temel bakış

  • İyi bir agent yalnızca “prompt, araç koleksiyonu, hedefe ulaşana kadar yineleme” kalıbından oluşmaz
  • Yazılım yönlü bir grafik (DG) olarak görülebilir; geçmişte programların akış şemalarıyla ifade edilmesinin nedeni de budur
  • Yaklaşık 20 yıl öncesinden bu yana DAG orchestrator’ları yaygın biçimde kullanılmaya başlandı
    • Örnek olarak Airflow, Prefect, dagster, inggest, windmill veriliyor
    • Bunlar gözlemlenebilirlik, modülerlik, yeniden deneme ve yönetim işlevleri eklenmiş grafik kalıplarını izler
  • Agent vaadi, mühendislerin tüm adımları ve istisnaları kodlaması yerine yalnızca hedefi ve geçişleri sağlaması, LLM’in de rotayı gerçek zamanlı belirlemesidir
    • Bu yaklaşım daha az kod yazma, hatalardan toparlanma ve LLM’in yeni çözümler bulabilmesi beklentisini taşır
    • Ancak pratikte bu yaklaşımın beklendiği kadar iyi çalışmadığı savunulur

Agent döngüsünün yürütme modeli

  • Temel agent döngüsü LLM kararı → araç yürütme → sonucun bağlama eklenmesi → yineleme adımlarından oluşur
  • Akış şöyledir
    • Başlangıç bağlamı; kullanıcı mesajı, cron çalıştırması veya webhook gibi bir başlangıç olayıdır
    • LLM sonraki adımı ya da tamamlanıp tamamlanmadığını belirler
    • Sonraki adım, yapılandırılmış JSON biçiminde bir araç çağrısı olarak çıktılanır
    • Deterministik kod araç çağrısını yürütür
    • Yürütme sonucu bağlam penceresine eklenir
    • Sonraki adım done ise nihai yanıt döndürülür
  • README’deki örnek, llm.determine_next_step(context) ile sonraki adımı belirleyen, execute_step(next_step) ile bunu çalıştıran ve sonucu bağlama ekleyen bir döngü gösterir

Neden 12 ilkeye ihtiyaç var?

  • HumanLayer geliştirilirken en az 100 SaaS geliştiricisiyle konuşuldu; bunların çoğu mevcut ürünlerini daha agentic hale getirmeye çalışan teknik kuruculardı
  • Tipik yolculuk şöyle ilerler
    • Bir agent geliştirmeye karar verilir
    • Ürün tasarımı, UX haritalaması ve çözülecek problem belirlenir
    • Hızlı ilerlemek için belirli bir framework seçilir
    • %70–80 kalite seviyesine ulaşılır
    • %80 kalitenin çoğu customer-facing özellik için yeterli olmadığı fark edilir
    • %80’in üstüne çıkmak için framework, prompt’lar, akış vb. tersine mühendislikle çözülmelidir
    • Sonunda baştan başlanır
  • Bu eleştirinin framework’lere veya framework geliştiricilerine saldırı amacı taşımadığı; framework’lerin AI ekosistemini hızlandırdığı belirtilir
  • MCP ele alınmaz; örneklerde ağırlıklı olarak TypeScript kullanılsa da bunların Python veya diğer dillerde de uygulanabilir olduğu söylenir

12 faktör

Uygulama biçimi ve ilgili kaynaklar

  • Tüm framework’ü benimseyip fiilen greenfield bir yeniden yazıma gitmenin ters etki yaratabileceği düşünülür
  • Agent’ları iyi yapan temel ilkelerin çoğu bir framework benimsenerek de elde edilebilir; ancak müşterilere hızlıca yüksek kaliteli AI yazılımı sunmanın yolu, daha küçük ve modüler kavramları mevcut ürüne entegre etmektir
  • Bu modüler kavramların, AI geçmişi olmayan deneyimli yazılım mühendisleri tarafından da tanımlanıp uygulanabileceği söylenir
  • İlgili kaynaklar arasında Anthropic’in Building Effective Agents, Prompts are Functions, Library patterns: Why frameworks are evil, The Wrong Abstraction bulunur
  • İçerik ve görseller CC BY-SA 4.0, kod ise Apache 2.0 lisansıyla sunulur

İlgili okumalar

1 yorum

 
GN⁺ 2025-04-17
Hacker News görüşleri

  • Bu yazıdaki noktalar harika. Birkaç yıl boyunca bizzat deneyip derlediğim çıkarımların bir listesi de var: https://mg.dev/lessons-learned-building-ai-agents/
    Bugün olsa en büyük ekleyeceğim madde, en düşük seviyedeki planlama döngüsüne bizzat sahip çıkmak olurdu. Dinamik planlama iyi, ama gözlemle-yönel-karar ver-harekete geç (OODA) döngüsünü kendiniz yönetmeli; çözüme yakınsayıp yakınsamadığını anlayacak sezgiseller (örn. puanlama) ya da çıkış koşulları (örn. maksimum yineleme sayısı) koymalısınız.
    Ayrıca bir iş akışı motoru eklemeyi de düşünmeye değer. Modelin örtük bir iş akışını birden çok tur boyunca sürdürüp ilerletmesini sağlamaktansa, modelin o motorda çalıştırılacak iş akışı tanımını üretmesini sağlamak ve her adımda gerekirse modeli tekrar çağırmak daha iyi.

    • Bu rehber iyi; özellikle “sohbet arayüzleri aptalcadır” bakışına katılıyorum. Yapay zeka tabanlı UI için daha gidilecek çok yol var.

  • DSPY gibi kütüphanelerin factor-2’ye nasıl uyduğunu merak ediyorum: https://dspy.ai/, https://github.com/humanlayer/12-factor-agents/blob/main/con...
    Okurken BAML ile prompt üretildiğinden bahseden bir kısım gördüm. Kişisel olarak, yapılandırılmamış veriden yapılandırılmış bilgi çıkarmak için promptları elle yazmayı kolay bulmadım; DSPY ile şimdiye kadar oldukça iyi deneyimler yaşadım.
    BAML’in ham promptlarını kullanıyorsanız, DSPY’nin ham promptlarını kullanma yaklaşımını nasıl görüyorsunuz merak ediyorum: https://dspy.ai/tutorials/observability/#using-inspect_histo...

    • İlginç, ama bu konuda Boundary (YC W23) tarafının görüşüne daha çok katılıyorum. En ileri seviye performans istiyorsanız kutuyu açıp içini doğrudan düzeltebilmeniz gerekir.
      https://www.chrismdp.com/beyond-prompting/ yazısına tamamen katılmıyorum, ama delikli kart → assembly → C → yüksek seviyeli diller karşılaştırması burada epey yararlı.
      Uygun soyutlamanın ne zaman ortaya çıkacağını hâlâ bilmiyorum; LangChain ya da DSPY’nin yapay zekanın “C programlama dili” olduğunu henüz düşünmüyorum. Bir gün olabilir.
      Şimdilik tokenları inceleyebildiğim, system/user/JSON gibi özel token sıralarını değiştirebildiğim, kütüphane desteğini bekleyip bağlanmadan yeni modellerin tuhaflıklarına hızla uyum sağlayabildiğim düşük seviyeli bir çalışma tezgâhı kullanmayı tercih ederim.

  • Framework kalıplarıyla ilgili eski ve pek bilinmeyen bir yazı kariyerim boyunca bana anlamlı geldi; bunun burada da geçerli olduğunu düşünüyorum: https://tomasp.net/blog/2015/library-frameworks/
    LLM’leri, yazıda anlatılan nedenler ve daha fazlası yüzünden, özellikle de her şeyin bu kadar hızlı değiştiği bugünlerde framework yerine kütüphane gibi kullanmak daha iyi. Ancak framework’ler daha çekici, satması daha kolay ve lock-in ile ek hizmetlere yol açtığı için daha çok pazarlanıyor.

    • Bu benzetme gerçekten iyi. Paket tur satın almak framework satın almak gibidir; ulaşım, otel, yemek ve aktiviteler framework’ün sağladığı kalıba uyar. Buna karşılık bağımsız seyahat, çeşitli kütüphaneleri birleştirmeye benzer; uçak biletini, konaklamayı ve programı kendiniz ayarlamanız gerekir, daha zahmetlidir ama istediğiniz şekilde kontrol edebilirsiniz.
    • Güzel. Bağlantılar bölümüne ekleyeceğim.

  • Kendi “yapay zeka ajan framework”üm olan SecAI’yi aktör modeli, durum makinesi ve görünüş yönelimli programlama temelinde geliştirdim ve yeni yayımladım: https://github.com/pancsta/secai
    Özellikle 5. madde “yürütme durumu ile iş durumunu birleştir” ve 8. madde “kontrol akışına kendin sahip ol” hoşuma gidiyor. SecAI’nin çekirdeği bir grafik kontrol akışı kütüphanesi; DAG değil multigraph kullanıyor ve LLM çağrıları grafik düğümlerinin içine gömülü.
    Akış; müzakere, iptal ve durumlu ilişkilerle güçlendirilerek daha organik çalışıyor. Diğer framework’lerde sıkça eksik kalan özel geliştirme araçları (dbg, repl, svg), hatayı varsayan programlama, tüm adımları ayrıntılı inceleme olanağı, otomatik veri dışa aktarımı (metrikler, trace’ler, log’lar, SQL) ve basit entegrasyon (bash) da dahil.
    İlk teknik demoyu da yayımladım; AtomicAgents’tan port edilmiş deepresearch referans implementasyonu ile geliştirme araçlarını gösteriyor: https://youtu.be/0VJzO1S-gV0
    Send/Stop düğmesi fiilen “Factor 6. Basit API ile başlat/duraklat/sürdür” anlamına geliyor; ayrıca ağ şeffaflığı da olduğundan ölçeklenebilir.

    • Diğer framework’lerde özel geliştirme araçlarının sık sık eksik kaldığına katılıyorum. Kendi deneyimime göre PydanticAI, Logfire ile ajan hata ayıklamayı gerçekten iyi çözmüş; test ettiğim diğer framework ve kütüphanelerden çok daha kolay ve etkiliydi: https://ai.pydantic.dev/logfire/#pydantic-logfire
    • Terminal UI’ı ve OTel entegrasyonu hoşuma gitti. Şu anda bunu hangi işlerde kullandığını merak ediyorum.

  • Bir şey daha eklemek gerekirse, ölçek büyüdüğünde maliyeti planlamak gerekiyor.
    Bu tür sistemler ölçek büyüdüğünde ucuz değil; bu yüzden bir iş deterministik bileşenlerle ele alınabiliyorsa önce onu denemek iyi olur. Bu yalnızca halüsinasyonları ve gecikmeyi azaltmakla kalmaz, nihai kârlılıkta da büyük fark yaratabilir.

    • Kesinlikle öyle olduğunu düşünüyorum. İnsanların en çok kullandığı kalıp şu gibi görünüyor: “Başta yavaş ve pahalı ama geliştirme eforu düşük bir yöntemle başla; sonra hız, kalite ve maliyet darboğazları içinde yatırım yapmaya değer yerleri buldukça kademeli olarak iyileştir.”

  • Her ilkeyi takip etmeyi kolaylaştırmak için, farklı factor’ları birbirine bağlayan tutarlı bir anlatı olsa iyi olur. Gerçeğe yakın bir sistem örneğini baştan sona kullanmak, anlamayı daha kolay hale getirebilir.

    • Güzel geri bildirim. Ne tür bir kullanım senaryosunun uygun olacağını merak ediyorum.
      Bunu toplulukla birlikte açık biçimde geliştirmeye devam etmek istiyorum.

  • Harika. %80’ini zaten zor yoldan öğrendim; kalan %20’si de okumaya değer gibi
    Kişisel olarak LangGraph + pydantic şeması kombinasyonuyla başarılı oldum. Başkalarının faydalı bulduğu araçları da merak ediyorum

  • Tam da şu anda ihtiyacım olan zamanda çıkan bir yazı
    Görsel-işitsel bir sandbox fikrini deniyorum. vvvv gibi bir şey ama çok daha basit ve yalnızca asgari özelliklere sahip bir biçimde: https://kfs.mkj.lt/#audiovisllm, https://vvvv.org/
    Fikir, belirli bir görevi üstlenen ve çıktısı çok sınırlı olan bir LM ya da basit bir yerel sinir ağı “düğümü” eklemek. Bu yüzden “question -> answer: float” gibi örnekler çok çekici geliyor. Benim durumumda sorulardan bazıları oldukça soyut olabilir ama çok aşamalı pipeline da ilginç

    • LLM’lerin tipli çıktısı oyunun kurallarını değiştiren bir unsur

  • Ayrıntılı okumadım ama mümkün olduğunca çok deterministik kod kullanıp LLM’den olabildiğince az yararlanmak istiyorum
    Bunun öngörülebilir sonuçlar, düşük işletim maliyeti ve başkalarının aynı uygulamayı hızla kopyalamasının zor olduğuna dair bir işaret anlamına geldiğini düşünüyorum. LLM’i başka sistemlere bağlamak için moda sözcüklerden oluşan yapıştırıcıyı aynen kullanmak yerine araçları kendim yapma eğilimindeyim
    Bu koşullar sağlanmıyorsa ya da gerekli değilse, birinin aynı çözümü göz açıp kapayıncaya kadar vibe coding ile üretebileceğini düşünüyorum. Kontrolü elde tutmak gerekiyor. Kontrol tepesinde ölmeye razıyım. Bu, LLM’lere hayran olmadığım anlamına gelmiyor; tam tersine

    • Kontrol de iyi, determinizm de iyi. Temel hedef “çok fazla kontrolden vazgeçmeyin” diye ikna etmek; ikincil hedef ise “kontrolün bir kısmını bırakabileceğiniz noktalar tam da buralar” diye göstermek