İçeriğe geç
Muhammet Şafak
en

Kitap III / III The Unreliable Systems Trilogy

Güvenilir AI Agent Mühendisliği

Production'daki agent'lar için tool'lar, yetki, state, sınırlar ve kayıtlar

Production'da güvenilebilecek AI agent'lar kurmak için pratik bir rehber: araçlar, yetki, durum, sınırlar ve kayıtlar; tasarımdan olay incelemesine.

  • 495 sayfa
  • 1. baskı
  • Ücretsiz

Kitabın tezi

Değil

modelin doğru olmasına güvenmek

Aksine

hatalarını atlatılabilir kılmak

  • 01

    Güvenilmez karar verici

    Modelin bazen yanılacağını varsayın ve tasarımı ilk satırdan buna göre kurun.

  • 02

    Kontrol sistemi

    Agent'ın yapabileceklerini izinler, kontroller ve sert limitlerle sınırlayın.

  • 03

    Kanıt izi

    Her karar ve eylemi, incelenebilsin, ölçülebilsin ve ters gittiğinde soruşturulabilsin diye kaydedin.

Kitap hakkında

Bir run aynı sorguyu art arda 40 kez çağırdı; çalışmasını tesadüfen izleyen biri fark edene kadar kimse görmedi. Sahne, orta ölçekli kurgusal bir fulfillment şirketinde, Parcelport’ta, ilk agent’ın yayına girdiği hafta geçer.

Çarşambaya gelindiğinde ekip üç şey öğrenmişti. Lookup döngüsünün yanında bir ticket, hiçbir tool’un döndürmediği bir teslimat tarihi vaat eden bir cevap üretmiş; bir müşteri e-postasındaki “asistana” hitap eden paragraf da Parcelport’tan gelen bir talimat gibi işlenmişti. Hiçbiri felaket değildi, hepsi öngörülebilirdi ve hiçbiri sonradan tam olarak yeniden kurulamadı, çünkü agent’ın ne yaptığına dair tek kayıt nihai yanıtıydı.

Kitabın tezi tek cümle: AI agent’lar, güvenilir kontrol sistemlerinin içinde çalışan güvenilmez karar vericiler olarak tasarlanmalıdır. Model öneri üretir, kararı sistem verir; bu yüzden kitap daha iyi bir prompt’la değil şu soruyla başlar: model bazen yanılacaksa, yanılmak atlatılabilir olsun diye çevresindeki sistem neyi garanti etmelidir?

Kitap prompt engineering, model eğitimi, framework ya da vendor üzerine değildir ve bir saldırı kitabı da değildir. Her kontrol maliyetiyle birlikte gelir; kitap bir kontrolün ne zaman gösterişten ibaret olduğunu da söyler. İçindeki sayılar örnektir; öneri ya da ölçüm değildir.

İçindekiler

  1. 01 Önsöz Kitabın tezini koyar: AI agent'lar güvenilmez karar vericilerdir ve güvenilir kontrol sistemlerinin içinde çalışmalıdır. Kitabın kime hitap ettiğini, framework'süz yaklaşımı ve pseudocode gösterimini de anlatır.
  2. 02 Agent Sistemin Kendisi Değildir Agent'ı bir orchestrator döngüsü, bir model, bir gate ve tool'lar olarak; modeli ise çıktısı gate izin verene kadar güvenilmeyen bir öneri üreticisi olarak tanımlar. Altı parçalı kontrol zarfını, karar haklarını ve en az agency kuralını tanıtır.
  3. 03 Model Belirsizliği Modelin önerisinin neden güvenilmeyen girdi olduğunu açıklar ve dört belirsizliği adlandırır: biçim, içerik, niyet ve eksiklik. Beyan edilen güven bir kontrol sinyali değildir; üzerine kurulacak sinyaller modelin dışında hesaplanır.
  4. 04 Agent'lar İçin Bir Hata Taksonomisi Bir çalıştırmanın tamamında neyin ters gittiği için bir sözlük verir: dokuz hata sınıfı, bir kök neden ekseni ve severity. Modelin hatası tetikleyicidir; kök neden, yanlış bir önerinin önem kazanmasına izin veren kontrol, bağlam ya da tool'dur.
  5. 05 Determinizm Sınırları Determinizm sınırının, geri alınabilirlik, doğrulanabilirlik, sıklık, tolerans ve açıklanabilirlik tartılarak karar başına nasıl çizileceğini gösterir. Model önerir, kod karar verir; para, tarih ve eşikler kodla hesaplanır.
  6. 06 Tool Çağırma Bir önerinin, propose'dan return'e kadar bir etkiye dönüştüğü yolu ve ilk durak dışındaki her durağın neden deterministik kod olduğunu izler. Sıkı parsing, düzeltme turları, tek etkili az sayıda tool ve gözlemlerin güvenilmeyen veri sayılması kapsanır.
  7. 07 Tool Sözleşmeleri Argümanların iyi biçimlendiğini söyleyen şema ile çağrının dünyanın şimdiki hâlinde yapılabileceğini söyleyen sözleşmeyi ayırır. Etki sınıfları, runtime'ın atadığı idempotency key'ler ve gate'in uyguladığı önkoşullar kapsanır.
  8. 08 İzinler ve Devredilmiş Yetki Yetkiyi prompt'ta değil, credential'da ve onu kullanan kodda konumlandırır. Etkin yetki, agent'ın kimliği, delegasyon ve görev kapsamının kesişimidir ve modelin dışındaki bir politika motoru tarafından uygulanır.
  9. 09 MCP: Güven Sınırını Aşan Tool'lar Bir MCP sunucusu bağlamayı bir güven sınırı açmak olarak ele alır. Her tool'un sözleşmesi host'a aittir; sunucu allowlist'i ve sabitlenmiş tanımlar değişiklikleri görünür kılar, her MCP çağrısı diğer her çağrı gibi aynı gate'ten geçer.
  10. 10 Bağlam Yönetimi Bağlamı, öğeleri seçen, etiketleyen, sınırlayan ve kaydeden deterministik montaj kodunun çıktısı olarak ele alır. Kaynak ve güven seviyeleri, sabitlenmiş çekirdekli yazılı bir bütçe, türetilmiş öğe olarak özetler ve alaka tabanlı retrieval kapsanır.
  11. 11 State Çalıştırma durumunu orchestrator'a ait kalıcı bir depoya koyar; modelin bağlamı bu depodan üretilen bir görünümdür. State machine'ler, durumdan devam etme, her beklemede deadline ve birkaç düzeyde eşzamanlılık kontrolleri kapsanır.
  12. 12 Bellek Çalıştırmalar arasında tutulan hafızayı çalıştırma durumundan ayırır ve önce hafızanın gerekip gerekmediğini sorar. Her hafıza yazımı kodun doğruladığı, kapsamlandırdığı ve süresini bitirdiği bir önerisidir; hafıza asla yetki taşımaz.
  13. 13 Planlama ve Döngüler Döngüyü orchestrator yürütür, model yalnızca bir sonraki öneriyi sağlar. Öneri olarak planlar, kodda bir predicate olarak başarı ve adım sınırları ile ilerleme tespiti içeren katmanlı durdurma koşulları kapsanır.
  14. 14 Bütçeler ve Circuit Breaker'lar Bütçeyi bir birimi, ölçüldüğü bir yeri ve tükendiğinde tanımlı bir davranışı olan bir sınır olarak tanımlar. Katmanlı bütçeler, etki bütçesi, bütçe bittiğinde ne olacağının planlanması ve yalnızca bağımlılık hatalarını sayan circuit breaker'lar kapsanır.
  15. 15 Retry'lar ve Fallback'ler Hiçbir şeyi tekrar etmeden önce hatayı sınıflandırır: zaman aşımına uğrayan bir yazımın sonucu bilinmez, retry'ı tam olarak bir katman yapar ve modele yeniden sormak bir onarım değil, yeni bir örnektir. Bir fallback merdiveni her basamağın izin verdiği kadar birincil davranışı korur.
  16. 16 İnsan Onayı Onayı, modelin beyan ettiği güvenden değil, kodun aldığı bir politika kararı yapar. Onay, tam olarak bir çağrının hash'ine bağlanır ve etkiyi gerçekleştiren servis geçerli bir onayı kendisi de kontrol etmelidir.
  17. 17 Prompt Injection Prompt injection'ı modelin dışında, bağlamın yapısında ve gate'te ele alır. Zarar, aynı çalıştırmada güvenilmeyen içeriği, erişimi ve dışarı bir kanalı gerektirir; tasarım her tool için bu üçünden en az birini keser.
  18. 18 PII Kişisel veriyi bir agent içinde sekiz yerden izler ve her birinde bir kontrol koyar. Korunması en ucuz PII, modelin hiç görmediği PII'dır; token'lar, yazım anında redaction ve çıkış kontrolü gerisini yapar.
  19. 19 Secret'lar Secret'ları modelin bağlamının dışında tutar: credential'ı tool runtime enjekte eder ve tool şemaları credential alanlarına kapalıdır. Kısa ömürlü, dar, çalıştırmaya bağlı credential'ları tercih eder, sınırda temizler ve pull request'leri secret taramasıyla gate'ler.
  20. 20 Sandboxing Model üretimi kodu çalıştırmayı ayrı bir güven sınırı olarak ele alır. Geçici bir dizin ya da temizlenmiş bir ortam sandbox değildir; izolasyon kodu kimin yazdığına göre seçilir ve profili ile sınırları model değil orchestrator belirler.
  21. 21 Observability ve Tracing Çalıştırmayı bir trace, her adımı, model çağrısını, gate kontrolünü, tool çağrısını ve onay beklemesini bir span olarak ele alır. Kaydı orchestrator deterministik event'lerden yazar; içerik katmanlanır ve yazım anında redact edilir.
  22. 22 Değerlendirme Olasılıksal parçaları ölçen eval'leri, deterministik parçaları kontrol eden testlerden ayırır. Dört eval düzeyi, gerçek trafikten ve olaylardan kurulan bir golden set, önce deterministik grader'lar ve sonuçların oran olarak raporlanması kapsanır.
  23. 23 Maliyet Kontrolü Her limitin altında kalıp yine de yanlış olan harcamayı kapsar. Her span'da ham kullanımı kaydedin, insan dakikaları dahil çözülen vaka başına maliyeti yönetin ve maliyet kontrollerini yalnızca kalitenin korunduğuna dair kanıtla uygulayın.
  24. 24 Olay Müdahalesi Agent olayını ve neden servis olayından daha zor olduğunu tanımlar: çalıştırmalar yeniden üretilemez ve davranış listelenmemiş bir değişiklikle kaymış olabilir. Önceden yazılmış bir sınırlama merdiveni, etki analizi ve nedenleri sıralayan review kapsanır.
  25. 25 Bir Güvenilirlik Kontrol Listesi ve Kapanış Düşünceleri Kitabı kontrol zarfına göre gruplanmış bir güvenilirlik kontrol listesinde toplar; her madde açabileceğiniz bir artifact ile yanıtlanır ve neyin onu eskittiğine bağlanır. Prototipten production'a geçiş, yetenek başına kanıtla yapılır.
  26. 26 Ek: Sözlük, Gate Kararı Reason'ları, Tool Gateway Hata Kodları, Örüntü Hızlı Başvurusu, Tool Sözleşmesi Şablonu, Hata Taksonomisi Tablosu, Lansman Öncesi Kontrol Listesi, Agent Olay Review Şablonu Referans malzemesidir: sözlük, gate karar nedenleri, tool gateway hata kodları, örüntü hızlı başvurusu, tool sözleşmesi şablonu, hata taksonomisi tablosu, lansman öncesi kontrol listesi ve olay review şablonu.

Örnek bölüm: İzinler ve Devredilmiş Yetki

Kitabın bir bölümünden alıntı; tamamı indirilebilir baskıda.

Gate ve yetki

Şimdi bunu gate’e koyalım. Bölüm 4’ün tool çağrısı dalı, modelin önerisini bir seçim kümesine karşı denetler ve not_in_choice_set ile reddeder; Bölüm 5 ve 6’nın sözleşmeleri de “sipariş bu run’ın müşterisine aittir”i bir ön koşul olarak listeler. Seçim kümesi daha önceki, ayrı bir katmandır: modele sunulanı daraltır, modelin önerdiğine karşı denetlenir ve reddi kendi kodunu korur. Yine de sahiplik cümlesini iki kez daha uygulamazdım. Sahiplik kararının tek bir sahibi var, aşağıdaki checkAuthority, ve tek bir kodu, not_permitted; sözleşmenin ön koşulu onu çağırarak karşılanır. Bir öneri seçim kümesinde takılabilir ve bu fonksiyona hiç ulaşmayabilir, ve bu sorun değil. Önemli olan, delegasyonun dışındaki bir sipariş gate’e ulaştığında, sahiplik hakkındaki kararın buradan çıkması, tek bir gözlem metni ve kayıtta tek bir sayımla. Ayrıca daha fazla veri okuyan ön koşullardan önce çalışır, çünkü principal’ın göremeyeceği bir siparişi okumak için bir neden yok.

function checkAuthority(run, call):
    delegation = run.delegation                       // assigned at run creation
    if delegation.expired or delegation.revoked:
        return { kind: "refuse", reason: "not_permitted" }    // an expired delegation is no authority
    authority = intersect(grantsFor(run.agent, call.tool),
                          delegation.grantsFor(call.tool),
                          run.taskScope)
    if authority is empty:
        return { kind: "refuse", reason: "not_permitted" }
    for each ref in resourceRefs(call):               // order id, shipment id
        owner = ownerOf(ref)                          // read from the owning service
        if owner is unknown:
            return { kind: "refuse", reason: "upstream_unavailable" }   // cannot verify: refuse, retryable
        if owner != delegation.on_behalf_of:
            return { kind: "refuse", reason: "not_permitted" }
    return evaluatePolicies(run, call, authority)     // ceiling, window, environment

Blok, ilgilendiği hata altında doğrudur. Reason’lar, bu bölümün kendi sözlüğünden değil, Bölüm 5’teki gate’in sözlüğünden gelir (Ek bunu listeler) ve checkAuthority, Bölüm 5’teki gate’in kısmi bir görünümüdür: o, permitted adımıdır ve döndürdüğü bir onay sonucu, ön koşullardan sonra en son uygulanır (Bölüm 6). Sahip araması başarısız olduğunda çağrı retryable olan upstream_unavailable ile reddedilir: ulaşılamayan bir orders-service izne dönüşmemeli ve kalıcı bir reddedilmeye de dönüşmemelidir; bu yüzden retry, modelin isteğiyle değil, retry politikası altında (Bölüm 14) çalışır. Run askıdayken ticket kapandığı için delegasyonun süresi dolduğunda çağrı not_permitted ile reddedilir. Model müşteriye ait olmayan bir sipariş önerdiğinde çağrı, modele emin olup olmadığı hiç sorulmadan, aynı şekilde reddedilir.

Ret metni önemlidir. Modele döndürülen gözlem, siparişin bu ticket için kullanılabilir olmadığını söylemeli ve başka bir şey söylememelidir. Siparişin var olduğunu doğrulamamalı ve onun hiçbir alanını içermemelidir. Diğer müşterinin verisini yankılayan bir ret, başka bir yoldan gerçekleşmiş bir okumadır.

Yetki beklemeden sonra yeniden denetlenir

Askıya alınmış bir run, Sam onaylamadan önce dakikalarca ya da saatlerce bir queue’da durabilir. Bu arada ticket yeniden atanmış, delegasyon iptal edilmiş ya da sipariş başka biri tarafından iade edilmiş olabilir. Orchestrator run’ı resume eder ve çağrıyı önceki kararın gücüyle uygularsa, bayat bağlama göre davranır (F5, kontrolden çıkan döngü ya da bayat bağlam). Run resume ettiğinde checkAuthority’yi ve ön koşulları yeniden çalıştırırdım ve onayı o ikinci denetime bir girdi sayardım, asla onun yerine geçen bir şey değil. Onay, bir insanın tam o çağrıyı kabul ettiğini söyler. Dünyanın hâlâ eskisi gibi olduğunu söylemez.

Sözlükçe

Kitapta geçen temel terimler ve kısa tanımları.

agent
Bir bileşen: bir model çağıran, önerilerini denetlemesi için bir gate'e soran ve onaylanan etkileri tool'lar aracılığıyla uygulayan bir orchestrator döngüsü. Bir insan değil.
kontrol zarfı
Bu kitabın altı parçalı modeli: Bağlam, Öneri, Gate, Etki, Sınır, Kayıt.
determinizm sınırı
Her karar için çizilen, modelin neyi önerebileceği ile kodun neye karar vermesi gerektiği arasındaki çizgi.
gate
Bir öneri ile bir etki arasındaki deterministik kontrol; üç sonucu var: allow, refuse, needs approval. Pseudocode'da: `"allow"`, `"refuse"`, `"needs_approval"`.
öneri
Modelin döndürdüğü her şey: bir tool çağrısı, bir plan, bir nihai cevap. Güvenilmeyen girdi olarak ele alınır.
etki
Gate bir tool çağrısına izin verdikten sonra dünyada olan şey.
tool sözleşmesi
Bir tool'un yazılı, makine tarafından denetlenebilir tanımı: ad, açıklama, input schema, etki sınıfı, ön koşullar, idempotency, izinler, timeout'lar, hata şekli.
devredilmiş yetki
Bir principal'ın bir başkası adına tuttuğu yetki; her zaman devredenin kendi yetkisinden dardır ve bir göreve bağlıdır.
confused deputy
Daha az yetkili bir tarafın istediğini yapmak için kendi yetkisini kullanan bileşen.
prompt injection
Veri olan içeriğin talimat olarak ele alınması. Doğrudan: kullanıcının kendi girdisi talimatları geçersiz kılmaya çalışır. Dolaylı: içerik bir tool sonucu, bir doküman ya da bir e-posta yoluyla gelir.
kill switch
Agent düzeyindeki breaker'ın manuel ucu: yeni run yok, uçuştaki run'lar bir sonraki step sınırında bekler. Agent'ın dışında tutulur.
etki bütçesi
Etkilerin birikimli büyüklüğü üzerindeki bir bütçe, örneğin toplam iade edilen tutar. Çağrı başına bir tavan ile toplam arasındaki boşluğu kapatır.
degraded mode
Bir sınır ya da breaker devreye girdiğinde sistemin içine girdiği, belirtilmiş, azaltılmış davranış (tool'suz cevap verir ya da yalnızca hand-off yapar).

Sık sorulanlar

8 soru

  • Kitap kimin için?

    Backend ve platform mühendisleri, SRE'ler, tech lead'ler ve bir agent'ı production'a taşıyan ekipler için; başkasının tasarladığı bir tasarımı gözden geçirmesi istenenler de dahil.

  • Belirli bir modele, framework'e ya da vendor'a bağlı mı?

    Hayır. Kitap modeli çağırdığınız bir bileşen olarak ele alır ve o bileşeni değiştirdiğinizde de kitabın anlattıkları geçerliliğini korur. Gerçek ürünler ve açık protokoller yalnızca örnek olarak geçer; asıl olan örüntüdür.

  • Bir prompt engineering kitabı mı?

    Hayır. Prompt'lar kötü önerilerin oranını düşürdüğü için geçer, ama prompt bir ricadır ve kitaptaki hiçbir özellik yalnızca bir ricaya dayanmaz. Bir bölüm bir talimata yaslandığında, talimat tutmasa bile tutan deterministik kontrolü adıyla söyler.

  • Okumadan önce neleri bilmem gerekir?

    Yetkin bir yazılım mühendisi olduğunuz varsayılır. Kitap bir dil modelinin ne olduğunu açıklamaz ve makine öğrenmesi terimlerini yalnızca bir kontrol kararını değiştirdikleri yerde kullanır. Belirli bir framework kullanmış olmanız gerekmez; kitap hiçbirini öneri olarak anmaz.

  • Kitap ücretsiz mi?

    Evet. Lisans satırı "© 2026 Muhammet Şafak — ücretsiz indirilir ve okunur" der. PDF ve EPUB dosyaları bu sayfadaki indirme panelinde sunulur. Bu baskı 495 sayfadır.

  • Hangi dillerde ve hangi formatlarda var?

    Yedi dilde: İngilizce, Türkçe, İspanyolca, Basitleştirilmiş Çince, Portekizce, Almanca ve Fransızca. Her biri PDF ve EPUB olarak sunulur.

  • Kitapta kod örnekleri var mı?

    Pseudocode var. Bütün kod dilden bağımsızdır, düz text bloklarında yazılır; diyagramlar Mermaid ile çizilir. Kitap hiçbir sağlayıcı API'sini ya da SDK'yı göstermez; model çağrısı her zaman bir öneri döndüren tek bir soyut fonksiyondur: model.propose(context).

  • Tek başına bir kitap mı, bir serinin parçası mı; seriyi hangi sırayla okumalıyım?

    The Unreliable Systems Trilogy'nin üç kitabından üçüncüsüdür: I Erişim (Production Veritabanı Erişim Rehberi), II Event'ler (Güvenilir Event-Driven Sistemler Tasarlamak) ve III Agent'lar (bu kitap). Önsöz başka bir kitabı değil, genel mühendislik becerisini önkoşul sayar; önünüzdeki sorun bir agent ise buradan başlayabilirsiniz.

Bu kitabın konusuna değinen blog yazıları.

Sitede Ara

Yazı, proje ve sayfalarda arama yapmak için yazmaya başlayın.

Esc ile kapat Pagefind ile güçlendirildi