Kendi VPS Sunucunuzda n8n AI Agent Kurulumu

n8n AI agent nedir ve bir zincirden (chain) farkı nedir

n8n AI agent, kendisine bağlı alt düğümleri (bir sohbet modeli, bir veya daha fazla araç ve isteğe bağlı bir bellek) bulunan tek bir AI Agent düğümüdür. Yalın bir dille bir hedef belirlersiniz; model, yanıt verene kadar hangi araçları hangi sırayla çağıracağına kendisi karar verir. Aşağıdaki her şey, bu tek fikir etrafındaki yapılandırmadır.

Zincir (chain) ise tam tersi şekilde çalışır. Bir Basic LLM Chain yapısında adımlara siz karar verirsiniz ve model yalnızca metni doldurur. Bir agent yapısında ise adımlara model karar verir; bu nedenle aynı soru bugün bir model çağrısına mal olurken, yarın dokuz çağrıya mal olabilir. Bu tek fark, bu kılavuzdaki her ayarı belirler.

Bu kılavuz, n8n'in kontrolünüz altındaki bir makinede HTTPS arkasında çalıştığını varsayar. Eğer çalışmıyorsa, Docker üzerinde gerçek bir sertifika ile n8n self-hosting rehberiyle başlayın; çünkü depolayacağınız API anahtarı, o rehberde ısrarla belirtilen şifreleme anahtarı yedeğine ihtiyaç duyar. Agent olmayan yapılar, webhook özetleyiciler ve zamanlanmış sınıflandırıcılar için Claude ve n8n iş akışı modelleri bölümüne bakın.

Buradaki herhangi bir alan adına güvenmeden önce sürümünüzü kontrol edin, çünkü n8n AI düğümlerini sık sık değiştirmektedir.

docker compose exec n8n n8n --version

Bu kılavuzdaki isimler, Temmuz 2026 itibarıyla n8n güncel kararlı sürümüyle uyumludur. 1.82.0 sürümünden itibaren her AI Agent düğümü Tools Agent olarak çalışır, bu nedenle eski agent tipi açılır menüsü artık mevcut değildir.

Adım 1: tetikleyiciyi seçin

Sohbet tabanlı bir aracı için Chat Trigger düğümü ekleyin. Oluşturma aşamasında Make Chat Publicly Available seçeneğini kapalı tutun; böylece araca yalnızca düzenleyicinin sohbet paneli üzerinden erişilebilir. Aracı tamamladığınızda ve kimlik doğrulama yöntemine karar verdiğinizde bu seçeneği açın.

Chat Trigger, araca chatInput adında bir alan iletir. Bu isim 3. adımda önem kazanır ve bu ismin yanlış girilmesi, karşılaşılan en yaygın ilk hata türüdür.

Katılımsız bir araç için bunun yerine Schedule Trigger veya Webhook düğümü kullanın. Bu düğümlerin hiçbiri chatInput üretmez; bu nedenle istemi kendiniz yazmanız gerekecektir.

Adım 2: Model kimlik bilgisi

Tuval üzerine bir AI Agent düğümü bırakın. n8n, hemen altında boş bir Chat Model bağlayıcısı gösterir. Oraya bir Anthropic Chat Model alt düğümü ekleyin.

Kimlik bilgisini platform.claude.com adresindeki Anthropic Console üzerinden, Settings ve ardından API Keys kısmından oluşturun. Anahtar yalnızca bir kez gösterilir. API kullanımı token başına ücretlendirilir ve herhangi bir Claude.ai aboneliğinden ayrıdır; bu nedenle ilk çalıştırmadan önce hesapta faturalandırmanın ayarlanmış olması gerekir.

Modeli şirket bazında değil, aracı bazında seçin. Bir şeyleri arayıp raporlayan tek araçlı bir aracı, Temmuz 2026 itibarıyla milyon girdi token'ı başına 1 dolar ve milyon çıktı token'ı başına 5 dolar olarak listelenen Haiku üzerinde sorunsuz çalışır. Aracı birden fazla araca sahip olduğunda ve bunlar arasında planlama yapması gerektiğinde Sonnet modeline geçin. Kaçınmanız gereken hata, yanlış aracı dört kez çağıran ucuz bir modelin, doğru aracı bir kez çağıran pahalı bir modelden daha maliyetli olmasıdır.

Alt düğümün seçenekleri içerisinden Maximum Number of Tokens değerini ayarlayın. Bu, modelin ürettiği her yanıtın uzunluğunu sınırlar. Varsayılan olarak büyük bir değerde bırakılırsa, hatalı bir çalıştırma çok uzun bir yanıt üretebilir ve bunun için ücretlendirilirsiniz.

n8n dokümantasyonunda herkesin gözünden kaçan bir uyarı: alt düğüm içindeki ifadeler her zaman ilk girdi öğesine göre çözümlenir, öğe başına değil. Öğe bazlı ifadeleri kök düğümün istem alanlarına yerleştirin.

Adım 3: Ajanın aldığı istem

AI Agent düğümünü açın. Prompt parametresinin iki ayarı vardır.

• Take from previous node automatically, chatInput adında gelen bir alan bekler. Bu, bir Chat Trigger arkasında kullanmak için doğru seçimdir.
• Define below, statik metin veya ifade yazabileceğiniz bir Prompt (User Message) alanını gösterir. Bu, bir Schedule Trigger veya Webhook düğümü arkasında kullanmak için doğru seçimdir.

Önünde bir Webhook düğümü olduğunda, POST gövdesi $json.body altında yer alır; bu nedenle istem alanı şu şekilde görünür.

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

Adım 4: araca bir yetenek atayın

Aracı (agent) bulunmayan bir AI Agent düğümü çalışmayı reddeder. Tek bir araçla başlayın; düzgün çalışan tek bir araç, yarım yamalak yapılandırılmış dört araçtan daha fazla bilgi öğretir.

Agent düğümünün Tool bağlantı noktasına bir HTTP Request düğümü ekleyin. Bu düğümü normal bir HTTP Request düğümünü yapılandırdığınız gibi yapılandırın ve ardından ilgili uç noktayı önce bir kabuk (shell) üzerinden test edin.

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

Eğer curl komutu bir hata döndürürse veya bir HTML giriş sayfası verirse, agent da başarısız olacaktır. Bu başarısızlık, aslında bir URL veya kimlik doğrulama sorunu olmasına rağmen bir model sorunu gibi görünebilir. Sorunu düğüm içinde değil, kabuk üzerinde çözün.

Aracın Description alanı iş arkadaşlarınız için yazılmış bir dokümantasyon değildir. Modelin, bu aracın ilgili olup olmadığına karar verirken okuduğu tek şeydir. Burayı, dönen veriyi net bir şekilde ifade eden bir cümleyle doldurun: "İzlenen bir servis için mevcut çalışma veya durma durumunu ve kesinti süresini JSON formatında döndürür."

Modelin isteğin bir kısmını doldurmasını sağlamak için $fromAI() ifadesini kullanın. Bu ifade yalnızca AI Agent düğümüne bağlı araçlarda çalışır; Code aracında çalışmaz.

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

Argümanlar key, ardından isteğe bağlı olarak description, type ve defaultValue şeklindedir. Anahtar (key) 1 ila 64 karakter arasında olmalı; harf, rakam, alt çizgi ve tire içermelidir. Tür (type) ise string, number, boolean veya json değerlerinden biri olmalı ve varsayılan olarak string kabul edilmelidir. Daha kapsamlı bir çağrı şu şekilde görünür.

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

Anahtar bir ipucudur, mevcut veriye yapılan bir referans değildir. $fromAI('service') ifadesi, herhangi bir yerden service adlı bir alanı okumaz. Modele "bir değer üret ve buna service adını ver" talimatını verir; model de bu değeri bulmak için konuşma geçmişini, girdi verilerini ve diğer araç sonuçlarını tarar. Bir sohbet iş akışında model, kullanıcıya doğrudan soru sorabilir.

Web araması genellikle eklenen ikinci araçtır. Bu da başka bir HTTP uç noktası olduğundan, aynı düğümü ücretli bir arama API'si yerine kendi SearXNG örneğinize yönlendirebilirsiniz. Ancak, dönen her sayfayı artık isteminizin (prompt) bir parçası olan güvenilmez bir metin olarak değerlendirmeniz gerektiğini unutmayın.

Adım 5: Bellek ve ajanın neden unuttuğu

Bellek alt düğümü (sub-node) olmadan her mesaj sıfırdan başlar. Yakın geçmişteki konuşmayı tutmak için bir Simple Memory alt düğümü ekleyin.

Bu düğümün iki parametresi vardır. Session Key, hangi konuşmanın yürütüldüğünü belirler; böylece farklı anahtarlara sahip iki kullanıcı ayrı geçmişlere sahip olur. Context Window Length, önceki etkileşimlerden kaç tanesinin isteme (prompt) tekrar dahil edileceğini belirler.

Context Window Length, kalite ayarı olduğu kadar bir maliyet ayarıdır da; çünkü hatırlanan her etkileşim, sonraki her çağrıda girdi belirteci (input token) olarak yeniden gönderilir. Çok konuşan bir ajanda 20 birimlik bir pencere boyutu, aynı ilk mesajlar için yirmi kez ödeme yapmanız anlamına gelir.

Simple Memory, n8n kuyruk (queue) modunda çalışırken aktif bir üretim iş akışında işlevsel değildir; çünkü geçmiş, paylaşımlı bir depoda değil, iş akışının kendi verisinde tutulur. Kuyruk modundaki bir örnekte, bunun yerine Postgres Chat Memory alt düğümünü kullanın ve ana süreç ile çalışanların (workers) erişebileceği bir veritabanını işaret edin.

Adım 6: Sistem Mesajı

Ajanın Options kısmını açın ve bir System Message ekleyin. İş tanımının yer aldığı bu alan, iş akışındaki en yüksek etkiye sahip metindir.

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

"Yanıt vermeden önce her zaman durum aracını (status tool) çağır" talimatı burada kritik bir işlev görür. Bu talimat olmadan, cevabı bildiğini varsayan bir model aracı atlayacak ve hafızasından yanıt verecektir; bu da altyapınız değiştiği anda modelin kendinden emin ancak hatalı bir yanıt üretmesine neden olur.

Ajan neden döngüye girer ve bu durum nasıl durdurulur

Options (Seçenekler) altında yer alan Max Iterations (Maksimum Yineleme) değeri varsayılan olarak 10'dur. Bir yineleme, bir model çağrısı ve ardından bağlama geri beslenen bir araç sonucundan oluşur. Dolayısıyla tek bir ajan çalıştırma işlemi tek bir API çağrısı değildir; 10 çağrıya kadar çıkabilir ve her biri, büyüyen konuşmanın tamamını girdi olarak taşır.

Bu değeri düşürün. Tek araçlı ajanların çoğu iki yinelemede tamamlanır; 3 veya 4 gibi bir sınır, kontrolsüz bir döngüyü yürütme listesinde görebileceğiniz temiz bir hata durumuna dönüştürür.

Hata ayıklama yaparken Return Intermediate Steps (Ara Adımları Döndür) seçeneğini açın. Bu durumda nihai çıktı, ajanın süreç boyunca yaptığı araç çağrılarını içerir. "Modelin aracı hiç çağırmadığı" durumu ile "aracın yararlı bir sonuç döndürmediği" durumunu bu şekilde ayırt edebilirsiniz. Canlı ortama geçmeden önce bu seçeneği tekrar kapatın, çünkü bu adımlar son kullanıcı için gereksiz veri oluşturur.

Bir çalıştırma işlemini shell üzerinden izleyin.

docker compose logs -f n8n

Katılımsız bir ajanın sessizce bütçe tüketmesini engelleme

Chat Trigger arkasındaki bir agent, akışın içinde bir insan denetimi barındırır. Yanıt hatalı göründüğünde bu kişi agent'ı durdurur. Schedule Trigger arkasındaki agent'ı ise izleyen kimse yoktur. Burada izlenen değer lisans maliyeti değil, model kullanım maliyetidir. Bunun nedeni, agent, tool ve memory node'larının ücretsiz self-hosted sürümde çalışmasıdır. Ücretli bir anahtar gerektiren özellikler çoğunlukla ekip ve yönetişim özellikleridir. Ayrıntılı açıklama Her zaman açık bir VPS üzerinde AI agent maliyet kontrolü bölümünde yer alır. Burada işin çoğunu dört ayar yapar.

• Model alt düğümünde Maximum Number of Tokens değerini sınırlayın; böylece hiçbir yanıt tek başına uzun sürmez.
• Max Iterations değerini, görevi tamamlamaya yetecek en küçük sayıya ayarlayın.
• Araç yanıtlarını kısa tutun. 4.000 satırlık bir JSON bloğu döndüren bir araç, bu verinin tamamını bir sonraki model çağrısına ve aynı çalışma içindeki sonraki tüm çağrılara dahil eder.
• Ajanın gerçekten bir zamanlamaya ihtiyacı olup olmadığını sorgulayın. Beş dakikada bir çalışan bir iş, günde 288 kez tetiklenir. Tek bir çalıştırmanın maliyeti neyse, çarpacağınız rakam odur.

İyileştirme yaparken iş akışını devre dışı bırakın. Schedule Trigger içeren aktif bir iş akışı, n8n tarafından kaydedilmiş sürüm üzerinden çalışmaya devam eder; bu sürüm her zaman ekranda gördüğünüz sürüm olmayabilir.

FAQ

AI Agent dugumum neden calismiyor?

AI Agent dugumu, bir sohbet modeli alt dugumu ve en az bir arac alt dugumu gerektirir. Modeli olan ancak araci olmayan bir dugum, herhangi bir API cagrisi yapmadan once hata verir. Basit bir arac dahi olsa bir tane ekleyin ve tekrar calistirin.

Ajan yanit veriyor ancak aracimi hic cagirmiyor. Sorun nedir?

Sorun neredeyse her zaman aracin Description alanindadir. Model, araclari bu aciklamalari okuyarak secer; bu nedenle "HTTP Request" gibi bir aciklama, aracin ne zaman kullanilacagi hakkinda hicbir bilgi vermez. Aciklamayi, hangi verinin dondugunu ve hangi durumda yararli oldugunu belirtecek sekilde yeniden yazin, ardindan System Message kismina ajana yanit vermeden once bu araci cagirmasini soyleyen bir satir ekleyin.

Ayni soru neden her calistirmada farkli bir maliyete sahip?

Cunku model, adim sayisini kendisi belirler. Her yineleme, onceki arac ciktilari da dahil olmak üzere sohbetin tamamini yeniden gonderir; bu nedenle dort yineleme suren bir calistirma, tek bir cagridan dort kat daha pahali olmaktan cok daha fazlasina mal olur. Max Iterations bu konuda bir ust sinir belirler, Return Intermediate Steps ise belirli bir calistirmanin gercekte kac adim kullandigini gosterir.

Bellek (memory) editor icinde calisiyor ama uretim ortaminda calismiyor. Ne degisti?

Ornegin kuyruk modunda (queue mode) calisip calismadigini kontrol edin. Simple Memory, gecmisi is akisinin kendi calistirma verisinde saklar; bu veri, ayri bir isci (worker) surecine aktarildiginda kaybolur, dolayisiyla aktif bir uretim is akisi bunu kaybeder. Gecmisi tum iscilerin paylastigi veritabaninda tutan Postgres Chat Memory alt dugumunu kullanin.