Workflow Tasarım Rehberi

İyi bir workflow, canvas üzerine bağlanmış node'lardan fazlasıdır. Açık bir giriş sözleşmesi, öngörülebilir dallanma, sınırlı dış etkiler, hata davranışı, insan karar noktaları ve işletilebilir bir yaşam döngüsüdür.

Bu rehber bir workflow'u fikirden üretime taşır:

Amaç → Tetikleyici → Girdi sözleşmesi → Adımlar ve dallar → Dış etkiler
     → Hata politikası → Onay → Test → Yayın → İzleme → Telafi

Workflow mu, agent mı?

İlk karar otomasyonun hangi yapıda olması gerektiğidir:

Agent bir workflow'u başlatabilir; bu, workflow'un yetki ve doğrulama kontrollerini kaldırmaz. Model “çalıştır” kararı verdiğinde gerçek girdiler, kullanıcı kapsamı ve riskli eylemler workflow sınırında yeniden değerlendirilir.

Örnek süreç: Masraf talebi ön kontrolü

Rehber boyunca şu örneği kullanacağız:

Tetikleyici: Yeni masraf talebi webhook'u
Girdi: talep_id, çalışan_id, tutar, para_birimi, belge_url
Adımlar:
  1. İmza ve payload doğrulama
  2. Talep ve çalışan kaydını kaynaktan okuma
  3. Belgeyi sınıflandırma ve alanları çıkarma
  4. Politika kurallarını değerlendirme
  5. Düşük riskliyse taslak değerlendirme oluşturma
  6. Eşik üzerindeyse insan onayında duraklama
  7. Onay sonrası finans sistemine kontrollü yazma
  8. Sonucu bildirme ve audit etme

Workflow ödeme yapmaz; yalnız doğrulanmış sonucu finans sistemine iletir. Gerçek ödeme ayrı yetki ve süreç sınırında kalır.

Adım 1 — Süreç sözleşmesini yazın

Canvas'ı açmadan önce şu alanları doldurun:

Başarı ile tamamlanmayı ayırın

Engine'in bütün node'ları hata vermeden çalıştırması, iş sonucunun doğru olduğu anlamına gelmez. Örneğin “API 200 döndü” yerine şu kabulü tanımlayın:

Teknik tamamlanma: Finans API'si isteği kabul etti.
İş tamamlanması: Talep kaydı beklenen durum ve tutarla oluştu.
Doğrulama: Oluşan kayıt kimliği yeniden okunup talep_id ile eşleşti.

Adım 2 — Tetikleyiciyi seçin

Webhook tasarımı

Webhook endpoint'i:

• Sağlayıcı imzasını ham body üzerinden doğrulamalı.
• Timestamp toleransı ve replay koruması uygulamalı.
• Payload boyutu ve content type sınırı koymalı.
• Olay kimliğini idempotency anahtarı olarak saklamalı.
• Hızlı kabul cevabı verip uzun işi asenkron yürütmeli.
• Bilinmeyen event type'ı sessizce başarı saymamalı.
• Secret rotasyonunda eski ve yeni anahtarın kontrollü geçişini desteklemeli.

Zamanlama tasarımı

Şunları açıkça belirleyin:

• Saat dilimi ve yaz saati uygulaması
• İş bir önceki çalıştırma bitmeden yeniden gelirse davranış
• Planlanan zamanda sistem kapalıysa catch-up yapılıp yapılmayacağı
• Hariç tutulan tarihler ve bitiş tarihi
• Aynı periyotta birden fazla context çalıştırılıyorsa izolasyon
• Uzun tatil veya bakım sonrası oluşabilecek toplu yük

“Her gün 09:00” ifadesi saat dilimi olmadan tamamlanmış bir gereksinim değildir.

Adım 3 — Girdi sözleşmesini tanımlayın

Her trigger için sürümlü ve makine tarafından doğrulanabilir bir şema oluşturun:

{
  "schema_version": "1.0",
  "event_id": "evt_8f2...",
  "occurred_at": "2026-07-31T08:00:00Z",
  "organization_id": "org_...",
  "request_id": "exp_...",
  "amount": 12500.00,
  "currency": "TRY",
  "document_url": "https://approved-source.example/..."
}

Girdide:

• Zorunlu ve opsiyonel alanları ayırın.
• Tarih, para, sayı ve enum formatlarını sabitleyin.
• Bilinmeyen alanların kabul edilip edilmeyeceğini belirleyin.
• Maksimum metin, liste ve dosya boyutunu sınırlandırın.
• Tenant/organizasyon kimliğini client iddiasından değil yetkili kaynaktan doğrulayın.
• URL ve dosya referanslarını allowlist ve erişim kontrolünden geçirin.
• Şema sürümünü taşıyın; kırıcı değişiklikte yeni sürüm yayınlayın.

Adım 4 — Mutlu yolu önce çizin

Workflow'u tek bir başarılı senaryo olarak soldan sağa çizin:

Trigger
  → Validate
  → Read source record
  → Transform
  → Evaluate policy
  → Write result
  → Verify write
  → Notify

Her node bir iş yapmalı ve adı sonucu anlatmalıdır:

• Zayıf: API 1, Function, Condition 2
• İyi: Masraf kaydını oku, Para birimini normalize et, Onay eşiğini değerlendir

Node açıklamasına girdiyi, çıktıyı ve dış etkiyi yazın. Canvas'a bakan başka bir ekip üyesi kod veya credential görmeden akışı anlayabilmelidir.

Adım 5 — Veri sözleşmelerini node'lar arasında koruyun

Bir node'un çıktısını sonraki node'a ham ve sınırsız aktarmayın. Gereken alanları seçin:

Kaynak API cevabı
  ├── gerekli: request_id, employee_id, amount, status
  ├── gerekli değil: tüm profil, geçmiş hareketler, debug metadata
  └── hassas: banka hesabı → sonraki AI adımına aktarılmaz

Her dönüşüm için:

• Alan adı ve tipini sabitleyin.
• Null/boş değer davranışını belirleyin.
• Para ve tarih dönüşümünü locale'e bırakmayın.
• Model çıktısını JSON şemasıyla doğrulayın.
• Hassas alanları ihtiyaç bittiğinde düşürün.
• Büyük payload yerine obje referansı kullanmayı değerlendirin.

Bir AI node'u yapılandırılmış çıktı veremiyorsa, sonucu iş etkisinde kullanmadan önce deterministik bir doğrulama ve insan kontrolü ekleyin.

Adım 6 — Dallanmayı açık tasarlayın

Her condition için tüm olası sonuçları çizin:

Politika değerlendirmesi
├── uygun → sonuç taslağı
├── onay gerekli → human-in-the-loop
├── eksik belge → kullanıcıya iade
└── değerlendirilemedi → manuel inceleme

Yalnız true dalı bulunan koşul, false veride sessizce duran bir workflow üretebilir. Default/unknown dalını tanımlayın. Model skorunu kesin doğruluk gibi kullanmayın; eşik çevresinde manuel inceleme bölgesi bırakın.

Paralel çalışma

Birbirinden bağımsız salt-okunur adımlar paralel çalışabilir:

                 ┌→ Çalışan kaydını oku ─┐
Trigger → Validate                       ├→ Birleştir → Karar
                 └→ Politika verisini oku┘

Aynı kaydı güncelleyen veya sıralı bağımlılığı olan adımları paralelleştirmeyin. Bir paralel dal hata verdiğinde diğer dalın dış etkisinin nasıl telafi edileceğini belirleyin.

Adım 7 — Credential'ları bağlayın

Credential değeri node içine yazılmaz. Workflow tanımı yalnız güvenli credential referansı taşır; gerçek değer çalıştırma anında yetkili kapsamda çözülür.

• Her entegrasyon ve ortam için ayrı credential kullanın.
• Staging credential'ı üretim kaydına erişmemeli.
• Salt-okunur adımlarda yazma yetkisi vermeyin.
• Credential'ı Space/workspace ve işlem kapsamıyla sınırlandırın.
• Kişisel OAuth bağlantısının sahibi ayrıldığında ne olacağını planlayın.
• Rotasyon sırasında çalışan ve duraklamış execution davranışını test edin.
• Secret veya token'ı node çıktısı ve loglara taşımayın.

Knowentra Space üyeliği ile workflow motorundaki workspace üyeliği eşleşmelidir. Kullanıcı Space'ten çıkarıldığında editör, credential ve çalıştırma erişiminin de kaldırıldığını doğrulayın.

Adım 8 — Dış etkileri idempotent yapın

Retry, webhook tekrarı veya kullanıcı yeniden çalıştırması aynı iş etkisini çoğaltmamalıdır.

İyi idempotency anahtarı

organization_id + workflow_version + business_request_id + operation

Rastgele execution ID tek başına yeterli olmayabilir; aynı iş olayı yeni execution ile tekrar başlatılabilir. Dış sistem destekliyorsa idempotency header/alanını kullanın. Desteklemiyorsa:

1. İşlem öncesi aynı business key ile kayıt arayın.
2. Kilit veya unique constraint ile yarış koşulunu önleyin.
3. İlk sonucu ve dış kayıt kimliğini kalıcılaştırın.
4. Retry'da yazmak yerine önceki sonucu döndürün.

Read–write–verify

Kritik yazmalarda:

Mevcut durumu oku
  → beklenen önkoşulu doğrula
  → idempotent yaz
  → kaydı yeniden oku
  → hedef durumu doğrula

HTTP 200 veya 202, iş sonucunun kesinleştiği anlamına gelmeyebilir.

Adım 9 — Timeout, retry ve rate limit

Her entegrasyon node'u için ayrı politika belirleyin:

Retry ayarları:

• Maksimum deneme sayısı
• İlk gecikme, backoff çarpanı ve üst sınır
• Jitter
• Toplam adım timeout'u
• Workflow genel deadline'ı
• Retry edilebilir hata kodları
• Dead-letter veya manuel inceleme hedefi

Sınırsız retry hem downstream servisi yorabilir hem maliyeti artırabilir. AI node'larında her retry yeni token kullanımı ve farklı çıktı anlamına gelebilir.

Adım 10 — İnsan onayı

İnsan onayı, yalnız canvas'a bir bekleme bloğu eklemek değildir. Onaylayan kişiye anlamlı ve değiştirilemez bir karar paketi gösterilmelidir:

Onay sırasında:

• Onaylayan Space/rol yetkisi yeniden kontrol edilir.
• Gösterilen veri ile çalıştırılacak payload aynı hash/revision'a bağlı olur.
• Kendi talebini onaylama kuralı açıkça belirlenir.
• Birden fazla onaylayanın yarışında ilk geçerli karar atomik uygulanır.
• Timeout sonrası otomatik onay verilmez.
• Onaylandıktan sonra hedef veri değişmişse önkoşul tekrar doğrulanır.

Onay yerine ne zaman manuel görev?

Onaylayan kişinin veri düzeltmesi, belge istemesi veya dış sistemde araştırma yapması gerekiyorsa basit approve/reject yeterli değildir. Workflow'u “manuel inceleme görevi oluştur → sonucu ayrı olayla al” biçiminde tasarlayın.

Adım 11 — Hata yolları ve telafi

Her dış etki için şu tabloyu doldurun:

Dağıtık sistemlerde tek transaction çoğu zaman mümkün değildir. Saga/telafi yaklaşımında başarılı her etkinin geri alma veya düzeltme adımı bulunur. Geri alınamayan etkileri onaydan sonra en sona yerleştirin.

Hata sınıfları

• Kullanıcı hatası: Eksik/geçersiz girdi; düzeltme iste.
• İş kuralı: Politika izin vermiyor; alternatif dala yönlendir.
• Geçici teknik hata: Sınırlı retry uygula.
• Kalıcı teknik hata: Dead-letter/manual inceleme oluştur.
• Güvenlik hatası: Fail closed, alarm ve audit üret.
• Bilinmeyen durum: Başarı sayma; dış etkiyi kontrol et.

Adım 12 — Bildirimleri tasarlayın

Bildirim birincil kayıt değildir. AI Feed, e-posta, Slack veya webhook ile sonuç gönderirken:

• Alıcıyı organizasyon/Space bağlamından çözün.
• Hassas payload yerine özet ve güvenli bağlantı gönderin.
• Başarılı, başarısız, onay bekleyen ve iptal durumlarını ayırın.
• Bildirim retry'ı ana iş etkisini yeniden çalıştırmasın.
• Aynı execution için bildirim tekrarını önleyin.
• Kullanıcıya execution/run kimliği ve destek yolu verin.

Knowentra AI Feed tamamlanan workflow sonucunu görünür kılabilir. Feed kartı, workflow'un kalıcı çalıştırma kaydının yerine geçmez.

Adım 13 — Gözlemlenebilirlik

Her execution için ortak bir run/correlation kimliği kullanın:

trigger_event_id
  → knowentra_workflow_id + version
  → sim_execution_id
  → node span'leri
  → approval_id
  → external_record_id
  → notification_id

Minimum sinyaller

• Çalıştırma sayısı, başarı, hata, iptal ve duraklama
• Queue bekleme, toplam süre ve node bazlı P50/P95
• Retry sayısı ve downstream rate limit
• AI node token, maliyet ve model gecikmesi
• Onay bekleme süresi ve timeout
• Dead-letter ve manuel inceleme yaşı
• Dış etki ve idempotency çakışması
• Bildirim teslimi

Loglarda credential, authorization header, cookie, tam kişisel veri veya gereksiz dosya içeriği bulunmamalıdır. Girdi/çıktı örneklemesi veri sınıflandırmasına ve saklama politikasına uymalıdır.

Adım 14 — Test stratejisi

Node testi

Her node'u örnek ve sınır girdileriyle tek başına doğrulayın:

• Normal değer
• Null/boş değer
• Maksimum uzunluk
• Hatalı enum veya tarih
• Yetkisiz kayıt
• Downstream timeout ve 429/5xx

Workflow testi

Replay testi

Gerçek hassas veriyi taşımayan kaydedilmiş trigger örnekleriyle yeni workflow sürümünü dry-run ortamında çalıştırın. Dış yazma node'larını mock/sandbox hedefe yönlendirin. Eski ve yeni sürümün karar ve payload farkını karşılaştırın.

Adım 15 — Yayınlama ve sürümleme

Yayınlanan workflow sürümü şu bağımlılıkları sabitlemelidir:

workflow_version
├── node ve edge grafı
├── trigger + input schema revision
├── block/integration sürümleri
├── model ve prompt revision
├── credential referansları (değer değil)
├── politika/onay eşikleri
├── timeout/retry ayarları
├── output sözleşmesi
└── test raporu + onaylar

Aktif execution başladığı sürümde tamamlanmalıdır. Taslakta yapılan değişiklik çalışan execution'ın grafını sessizce değiştirmemelidir.

Değişiklik sınıfları

Adım 16 — Pilot ve kontrollü geçiş

• İlk trigger kapsamını belirli kullanıcı, klasör veya event type ile sınırlandırın.
• Mümkünse shadow modda karar üretip dış yazma yapmadan karşılaştırın.
• Günlük maksimum execution ve dış etki limiti koyun.
• Canary sürümü küçük trafik yüzdesine verin.
• Eski sürümü hızlı rollback için hazır tutun.
• Başarı kadar manuel düzeltme ve telafi ihtiyacını ölçün.

Kritik süreçte big-bang geçiş yerine iki sistemi kısa süre paralel çalıştırmak gerekebilir; aynı olayı ikisinin de yazmaması için sahiplik/idempotency sınırı tanımlayın.

Adım 17 — Operasyon ve kapatma

Üretim runbook'u şunları içermelidir:

• Workflow'u ve trigger'ı durdurma
• Queue'daki işleri güvenli biçimde bekletme veya iptal
• Paused execution'ları listeleme ve sahip atama
• Credential rotasyonu
• Dead-letter yeniden çalıştırma
• Dış etkiyi doğrulama ve telafi
• Önceki sürüme dönme
• Audit dışa aktarma ve olay inceleme

Workflow kaldırılırken yalnız canvas'ı silmeyin:

1. Yeni trigger'ları durdurun.
2. Aktif, retry ve paused execution'ları çözün.
3. Bekleyen onayları kapatın.
4. Connector credential ve webhook subscription'larını iptal edin.
5. Dış sistem callback ve schedule'larını kaldırın.
6. Tanım, çalıştırma ve audit kayıtlarını saklama politikasına göre arşivleyin.

Tasarım anti-pattern'leri

Yayın öncesi kontrol listesi

• İş sonucu, kaynak-of-truth ve sahipler belli.
• Trigger kimliği, replay ve rate-limit kontrolleri var.
• Girdi/çıktı şemaları sürümlü ve doğrulanıyor.
• Mutlu yol ile tüm hata/default dalları çizildi.
• Node'lar arasında yalnız gerekli veri taşınıyor.
• Credential'lar referansla ve en az yetkiyle kullanılıyor.
• Her dış yazma idempotent ve read-back ile doğrulanıyor.
• Timeout, retry, backoff ve dead-letter politikaları tanımlı.
• Onay verisi, yetkisi, timeout ve ret davranışı test edildi.
• Kısmi başarılar için telafi adımları var.
• Correlation kimliği dış kayda kadar taşınıyor.
• Normal, negatif, replay ve kesinti testleri geçti.
• Yayınlanan grafik ve bağımlılıklar sürümlendi.
• Pilot limiti, kill switch ve rollback hazır.
• Runbook ve süreç sahibine eskalasyon yolu mevcut.

Sonraki adımlar

• Agent'tan workflow başlatmak için Agent Oluşturma ve Yayınlama
• Araç sınırları için Araç Bağlama ve MCP
• Servis kimliği için Kimlik, SSO ve Yetkilendirme
• Entegrasyonlar için Desteklenen Entegrasyonlar
• Operasyon için Audit Logları ve Gözlemlenebilirlik