Vibe Coding & Multi-Agent Mimarisi: Next.js ve Python ile Otonom AI Agent Platformu İnşa Etmek

📌 Bölüm 1: Giriş ve Paradigma Değişimi (Paradigm Shift)

LLM Çağında Evrim: Prompt Engineering'den Agent Orchestration'a

Yapay zeka ekosisteminde son dönemin en büyük yanılgılarından biri, karmaşık problemleri tek bir "mükemmel prompt" yazarak çözebileceğimize inanmaktı. LLM API'lerine tekil çağrılar (single API calls) atarak elde ettiğimiz sonuçlar bir yere kadar etkileyiciydi; ancak gerçek dünya senaryolarına girdiğimizde bu yaklaşım çabuk tıkandı.

Bir sistemin otonom bir şekilde karmaşık görevleri yürütebilmesi için tek bir devasa prompt'a değil, görev dağılımına (Separation of Concerns) ve araç kullanma (Tool Calling) kabiliyetine ihtiyacı var. İşte burada AI Agent (Yapay Zeka Ajanı) kavramı devreye giriyor. Ajanlar; bellek (memory), planlama yeteneği, dış dünya araçları (web arama, kod çalıştırma, API entegrasyonları) ve belirli roller üstlenerek sadece metin üretmiyor, aksine aksiyon alıyor.

Peki, bu ajanları tek tek çalıştırmak yerine bir araya getirip bir orkestra gibi yönettiğimizde ne oluyor? Multi-Agent Orchestration (Çoklu Ajan Orkestrasyonu) doğuyor.

AI Engineering'de Yeni Dönem: "Vibe Coding" ve Cursor IDE

Yazılım mühendisliği tarafında da ciddi bir konsept kayması yaşıyoruz. Bir AI Mühendisi (AI Engineer) olarak günümüzdeki rolümüz, saatlerce boilerplate (şablon) kod yazmak ya da syntax hatalarıyla boğuşmak değil. Artık odağımız: Sistem mimarisini kurgulamak, veri akışını tasarlamak ve ajanların orkestrasyonunu doğru parametrelerle sağlamak.

PRD (Product Requirement Document) ve MVP Tanımı

Bu yazıda adım adım inşa edeceğimiz projenin ana amacı; kullanıcının kod yazmadan, tamamen sürükle-bırak (drag-and-drop) mantığıyla çalışan bir arayüzde kendi AI otomasyon süreçlerini kurgulamasına olanak tanımaktır.

Bir ürünün minimum çalışabilir versiyonunu (MVP) ortaya koyarken net bir PRD dokümanı ile başlamak hayati önem taşır. Sistemimizin temel gereksinimleri:

1. Görsel Akış Editörü (Node-Based Canvas): Kullanıcının tuval üzerine Web Search, YouTube Summarizer, Researcher gibi farklı uzmanlıktaki ajan düğümlerini (Nodes) ekleyebilmesi.
2. Dinamik Bağlantı Hatları (Edges & State): Düğümlerin birbirine bağlanabilmesi ve birinci ajanın çıktısının (Output) bir sonraki ajanın girdisi (Input) haline gelebilmesi.
3. Konfigürasyon Yönetimi: Her ajanın kendi API Key, System Prompt, Model Seçimi (Gemini, GPT-4, Llama) gibi parametrelerinin bağımsız ayarlanabilmesi.
4. Python Multi-Agent Backend: Arayüzden gelen bu iş akışı haritasını (Workflow Graph) alıp asenkron olarak çalıştıracak ve canlı durum bilgisini arayüze yansıtacak esnek bir servis altyapısı.

📌 Bölüm 2: Sistem Mimarisi ve Teknoloji Yığını (Tech Stack)

Genel Mimari Şema ve Veri Akışı

Bir AI Engineer için projenin en kritik anı, ilk kod satırını yazmadan önce veri akışını ve bileşenlerin sorumluluk sınırlarını çizdiği andır. Görsel bir akış editöründen (Flow Editor) otonom ajanların koşturduğu bir arka plana geçiş, doğru kurgulanmış bir mimari gerektirir.

Veri Akış Senaryosu:

1. Kullanıcı arayüzde (Canvas) düğümleri birbirine bağlar, parametrelerini yapılandırır.
2. Çalıştır butonuna basıldığı an, Canvas üzerindeki bağlantı grafiği (Graph Topology) ve konfigürasyonlar Redux Store üzerinden toplanarak yapılandırılmış JSON payload'una dönüştürülür.
3. Frontend, bu veriyi Next.js API Route / Proxy katmanı üzerinden Python Backend'e iletir.
4. Python tarafındaki Orchestrator, gelen bağımlılık sırasına göre ajanları asenkron olarak tetikler, çıktıyı bir sonraki düğüme aktarır ve canlı durumu arayüze geri bildirir.

Frontend Katmanı: Next.js 14/15, Redux Toolkit ve Shadcn UI

Görsel bir iş akışı oluşturucu yazarken karşılaşılan en büyük zorluk, tuval üzerindeki onlarca düğümün anlık durumunu performanslı bir şekilde yönetmektir.

• Next.js (App Directory): Server-side rendering (SSR) hızı ve temiz API yönlendirme (Proxy/Route Handlers) kabiliyetleri sebebiyle temel omurgamız.
• Shadcn UI & Tailwind CSS: Estetik, özelleştirilebilir ve erişilebilir arayüz bileşenleri için tercihimiz.
• Redux Toolkit (State Management): Sürükle-bırak uygulamalarında karmaşık durum yönetimini kütlesel React useState zincirleriyle çözmeye çalışmak kabusa dönüşebilir. Her düğümün konfigürasyonu (örn. model: 'gemini-1.5-flash') Redux store üzerinde merkezi olarak tutulur. Bir düğümün ayarları değiştiğinde tüm tuvali re-render etmeden ilgili dilim güncellenir.

Backend Katmanı: Python & Phidata/Data Framework

"Neden Backend tarafında Node.js değil de Python kullandık?" sorusu akla gelebilir. Yanıt basit: Yapay zeka ekosisteminin merkez üssü Python.

• Phidata / Data Framework Entegrasyonu: Ajanların bellek yönetimi, araç entegrasyonları ve sistem talimatlarını esnek bir şekilde yönetebilmek için Phidata ekosisteminden faydalanıyoruz. Ajan tanımlamak sadece birkaç satır deklaratif koddan ibaret hale geliyor.
• Modüler Ajan Yapısı: Ajanlarımız birbirinden bağımsız sınıflar/modüller olarak kurgulanır. Her ajan kendi aracına ve modeline sahiptir.
• Asenkron Çalışma Ortamı (Async/Await Pipeline): Ajanların dış servislerle iletişimi zaman alabilir. Bloklayıcı kod yazmak yerine, veri akışını asenkron bir boru hattı üzerinde koşturarak UI tarafında donmaları ve zaman aşımlarını önlüyoruz.

📌 Bölüm 3: Modüler Ajanlar ve Uygulama Alanları

Platformumuzun omurgasını kurduktan sonra sıra geldi en eğlenceli kısma: Ajanlara uzmanlık kazandırmak ve onları dış dünya ile haberleştirmek!

Bir AI Mühendisi olarak ajan tasarlarken altın kural şudur: Her ajana net bir rol, kısıtlı bir sorumluluk ve doğru araçlar (tools) ver.

3.1. Dış Dünya ile Etkileşim: Web Search & Extraction Agent

Ajanların en büyük kısıtlamalarından biri, eğitildikleri veri setlerinin güncelliğini yitirmesidir. Web Search Agent, ajanın internet araması yapmasını, dinamik içerikleri kazımasını (scraping) ve veriyi yapılandırarak sunmasını sağlar.

• Teknik Altyapı: Backend tarafında Phidata/Data framework arama araçlarını entegre ediyoruz. Ajan, gelen arama talebine göre dış servislere HTTP isteği atıyor, dönen HTML/JSON verisini süzüyor ve Markdown formatında temiz bir çıktı halinde UI'a döndürüyor.
• UI Görselleştirme: Çıktının sadece ham metin kalmaması için arayüzde Markdown Renderer kullanarak listeleri, tabloları ve kalın metinleri zengin bir şekilde görselleştiriyoruz.

3.2. Medya & İçerik İşleme: YouTube & Media Summary Agent

Uzun video ve ses dosyalarından anlamlı bilgi çıkarmak, yapay zekanın en güçlü olduğu alanlardan biridir.

• Teknik Altyapı: YouTube Agent, parametre olarak verilen video URL'ini alır, video altyazılarını (transcript) dış kütüphaneler aracılığıyla çeker ve belirlediğimiz sistem talimatı doğrultusunda analiz eder.
• Model Seçimi: Hız ve yüksek bağlam penceresi avantajı nedeniyle bu aşamada varsayılan model olarak Google Gemini 1.5 Flash tercih ediyoruz. Böylece saatlik videoların altyazıları bile saniyeler içinde işlenebiliyor.

3.3. Derin Analiz: Researcher Agent

Tek bir arama sonucu veya video özetlemek bazen yeterli olmaz. Researcher Agent, bir konuda derinlemesine araştırma yapmak üzere tasarlanmış otonom bir simülasyon ajanıdır.

• Teknik Altyapı: Kullanıcının verdiği bir konu başlığını alır. İnternetteki ilk 5-10 kaynağı tarar, bağlantıları tek tek ziyaret eder, okur, çelişen bilgileri ayıklar ve kaynak göstererek yapılandırılmış bir araştırma raporu oluşturur.
• Otonom Araştırma Mantığı: Ajan sadece bilgi getirmekle kalmaz; kaynakların güvenilirliğini sorgulayarak "Özet", "Yöntem", "Bulgular" ve "Kaynaklar" bölümlerinden oluşan akademik/profesyonel bir çıktı üretir.

📌 Bölüm 4: Multi-Agent Orkestrasyonu ve UX Mühendisliği

Çoklu Ajan (Multi-Agent) Tasarım Deseni: Separation of Concerns

AI sistemlerinde karşılaşılan en büyük hatalardan biri, devasa bir ajana "İnternette ara, bulduğun videoyu özetle, kod yaz ve rapor oluştur" şeklinde her işi yaptırmaya çalışmaktır. Bu durum, modelin odağını kaybetmesine (hallucination) ve yüksek token maliyetlerine yol açar. Doğru yaklaşım, yazılım mühendisliğindeki Separation of Concerns (Sorumlulukların Ayrılması) prensibidir.

• Web Search Agent: Sadece doğru kaynakları ve URL'leri bulur.
• YouTube Agent: Sadece altyazıyı işler ve içeriği çıkarır.
• Researcher Agent: Tüm bu verileri alır, sentezini yapar ve nihai raporu hazırlar.

Ajanlar Arası Veri Transferi (Agent-to-Agent Pipeline)

Tuval üzerindeki iki düğüm (Node) arasında çizdiğimiz her bağlantı kablosu (Edge), aslında bir Data Pass-through (Veri Aktarımı) mekanizmasıdır. Frontend tarafında Redux Store, tuvaldeki grafik topolojisini tutar. Çalıştır butonuna basıldığında, sıralı çalıştırma mantığı devreye girer:

1. Topolojik Sıralama (Topological Sort): Bağlantı grafiği analiz edilerek hangi düğümün önce çalışması gerektiği belirlenir.
2. Output to Input Mapper: Düğüm A başarıyla tamamlandığında, dönen yanıt otomatik olarak Düğüm B'nin girdi alanına enjekte edilir.

Arayüzde Gerçek Zamanlı Durum Göstergeleri ile Gelişmiş UX

Karmaşık bir Multi-Agent akışı çalışırken kullanıcının en çok nefret ettiği şey, ekranda hiçbir şey görmeden saatlerce beklemesidir. Kullanıcıya arayüzde dinamik geri bildirim sunmak hayati önem taşır. Tuvalimizdeki düğümler ve bağlantı hatları anlık durumlarına göre renk değiştirir:

• Gri (Idle / Beklemede): İş akışı henüz başlamadı veya ilgili düğüme sıra gelmedi.
• Turuncu (Processing / İşleniyor): Ajan şu anda aktif olarak dış servislere istek atıyor veya LLM yanıtı bekliyor. Arayüzde loading animasyonu görünür.
• Yeşil (Success / Başarılı): Ajan görevini tamamladı, çıktı üretildi ve veri bir sonraki düğüme aktarıldı.

📌 Bölüm 5: AI Engineer'ın Sözlüğü: "Vibe Coding" & Problem Çözme

Yapay zeka çağında yazılım geliştirirken sıklıkla övülen "Vibe Coding", hiçbir şey bilmeden sadece butonlara basmak değildir. Aksine, kod yazma işini yapay zekaya devrederken, mimari doğruluğu ve süreç kontrolünü yüksek farkındalıkla yönetme sanatıdır. Bir AI Mühendisi olarak Cursor veya benzeri LLM destekli IDE'lerle çalışırken, sistemin sizin "kod ortağınız" olduğunu unutmamalısınız. Ancak bu ortak bazen halüsinasyon görebilir, eksik paket yükleyebilir veya mimari bağlamı unutabilir.

Prompt Engineering for Developers: IDE Ajanlarını Doğru Yönlendirmek

1. Görsel Bağlam (Visual Context) Kullanımı: Hata aldığınızda veya UI istediğiniz gibi çıkmadığında sadece metin atmayın. Arayüzün ekran görüntüsünü (screenshot) alıp IDE'ye doğrudan iletin. Yapay zeka, görsel okuma kapasitesi sayesinde arayüzdeki CSS kırılmalarını veya eksik bileşenleri metinlerden çok daha hızlı tespit eder.
2. Kısıtları Açıkça Belirtmek (Negative Constraints): Neyin yapılmaması gerektiğini söylemek, ne yapılması gerektiğini söylemek kadar kritiktir. ("Kesinlikle var olan data bağımlılıklarını silme, mevcut requirements.txt yapısını bozma" gibi).
3. Parçalı ve Adım Adım (Iterative) İlerleme: Devasa bir sistemi tek prompt ile yazdırmaya çalışmayın. Önce boş bir API endpoint'i yazdırın, ardından Redux store entegrasyonunu yaptırın, en son UI bileşenine bağlayın.

Karşılaşılan Teknik Engeller ve Çözüm Stratejileri

• 500 & 404 API Hataları ve Bağlam Kaybı (Context Drift): Frontend katmanından backend'e istek atıldığında 404 veya 500 dönmesi. LLM'e "Hata var düzelt" demek yerine, terminaldeki curl isteği çıktısını veya sunucu konsol loglarını tam olarak kopyalayıp iletmek. Projeyi tekrar indeksletip (re-index) doğru rotayı düzeltmesini sağlamak.
• Python Ortamındaki Eksik Paketler (ModuleNotFound Errors): Sanal ortamı (virtualenv) aktif tutarak paket indirme komutlarını IDE ajanına doğrudan terminal üzerinden koşturmak ve requirements.txt dosyasını anlık güncellemesini istemek.
• API Key & Environment Yönetimi: Tüm anahtarları .env ortam değişkenlerine taşımak ve backend tarafında os.getenv kontrolünü sağlayarak varsayılan bir uyarı mekanizması kurgulamak.

📌 Bölüm 6: Sonuç, Production Notları ve Gelecek Vizyonu

Geliştirdiğimiz bu platform, sadece sürükle-bırak düğümlerden oluşan görsel bir oyuncak değil; arka planda asenkron çalışan, modüler ve ölçeklenebilir bir AI Agent Orchestration Platformu MVP'sidir. Tekil bir prompt penceresine sıkışıp kalmak yerine, otonom ajanları birer mikroservis gibi konumlandırıp aralarındaki veri akışını yönetmek, modern yapay zeka mühendisliğinin ana omurgasını oluşturuyor.

Production Ortamına Taşırken Dikkat Edilmesi Gerekenler

1. Token Maliyeti ve Gecikme (Latency) Optimizasyonu: Multi-Agent zincirlerinde her bir ajan ardışık çalıştığında yanıt süresi artabilir. Çözüm: Birbiriyle doğrudan bağımlılığı olmayan ajanları paralel koşturmak, hafif görevlerde Gemini Flash veya GPT-4o-mini gibi hızlı/ucuz modelleri tercih edip, derin analiz aşamasında daha büyük modellere geçmek.
2. Güvenlik ve Komut Çalıştırma (Shell Execution) Riskleri: İş akışlarına kod yorumlayıcı veya terminal komutları çalıştıran ajanlar eklendiğinde, sistem doğrudan sunucu kaynaklarına erişim kazanır. Çözüm: Bu tür ajanları doğrudan ana sunucuda değil, izolasyon sağlanmış Docker konteynerları (Sandboxing) veya geçici sunucusuz ortamlarda koşturarak sistem güvenliği garanti altına alınmalıdır.
3. Durum Kalıcılığı (State Persistence) ve Zamanlanmış Görevler (Cron Jobs): Kullanıcının tarayıcıyı kapattığında akışın kaybolmaması gerekir. Çözüm: İş akışlarını PostgreSQL/MongoDB üzerinde saklamak ve uzun süren akışları Celery / Redis gibi kuyruk mekanizmalarıyla yöneterek cron job'lar ile düzenli otomasyonlara dönüştürmek.