Kendi VPS Sunucunuzda n8n AI Agent Kurulumu

n8n AI agent nedir ve bir zincirden farkı nedir

n8n AI agent, kendisine bağlı alt düğümleri olan tek bir AI Agent düğümüdür: bir sohbet modeli, bir veya daha fazla araç ve isteğe bağlı bir bellek. Bir hedefi yalın bir dille belirtirsiniz; 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.

Bir zincir ise tam tersi şekilde çalışır. Bir Basic LLM Chain içinde 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. Eğer bu döngü fikri sizin için bir n8n özelliğinden ziyade yeni bir kavramsa, onu düğümlerle birleştirmeden önce bir kez elle yazmak faydalı olacaktır; çünkü düğüm, bu kılavuzun geri kalanında üzerinde düşüneceğiniz kısmın tam olarak kendisini gizler.

Bu kılavuz, n8n'in kontrolünüz altındaki bir makinede HTTPS arkasında çalıştığını varsayar. Eğer çalışmıyorsa, işe Docker üzerinde gerçek bir sertifika ile n8n self-host etmek ile başlayın; çünkü depolayacağınız API anahtarı, o kılavuzda ı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

Sürüm 1.82.0 ile birlikte agent-type ayarı, Tools Agent lehine kullanımdan kaldırılmıştır. Eski v1 düğümleri hala bu ayara sahiptir; n8n belgeleri, bu düğüm sürümünün kaldırılmasını n8n 3.0 sürümüne atamaktadır.

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ğlantı noktası gösterir. Oraya bir Anthropic Chat Model alt düğümü ekleyin.

Kimlik bilgisini platform.claude.com adresindeki Claude Console üzerinden, Settings ve ardından API keys menüsünden oluşturun. Anahtar yalnızca bir kez gösterilir. Console, anahtar oluştururken bir son kullanma tarihi seçmenizi de ister; katılımsız bir ajan, anahtarının süresi dolduğu gün çalışmayı durdurur, bu nedenle bu tarihi görebileceğiniz bir yere not edin. Katılımsız bir ajan için, isteklerin ayrı bir çalışma alanı başlığına ihtiyaç duymaması adına bir çalışma alanıyla sınırlandırılmış bir servis hesabı anahtarı kullanın.

API kullanımı token başına ücretlendirilir ve ödeme yöntemi 31 Ekim 2026 itibarıyla Claude planınıza bağlıdır. Max, Ultra ve Team planları aylık API kredileri içerir: Max planında 100$, Ultra planında 200$ ve Team planında havuzda 500$'a kadar. Bu kredileri, Max veya Ultra için Settings > Billing, Team için ise Organization settings > Billing menüsünden bir Console organizasyonunu plana bağlayarak talep edersiniz; Console üzerinde ayrıca bir ödeme yöntemi eklemenize gerek yoktur. Yeni aboneler planı başlattıktan 7 gün sonra talepte bulunabilirler; kullanılmayan krediler her fatura döneminin sonunda veya yıllık planlarda aylık olarak sona erer. Dahil edilen krediler tükendiğinde istekler satın alınan krediler üzerinden devam eder, otomatik yükleme özelliği daha fazla kredi alabilir ve faturalı organizasyonlar aşan kullanım için ücretlendirilir. Ön ödemeli bir organizasyonun kredisi kalmadığında istekler durur; API kullanımı hiçbir zaman Claude abonelik planınız üzerinden ücretlendirilmez. Free, Pro ve Enterprise planları aylık API kredisi içermez, bu nedenle bu planlarda API, abonelikten ayrı olarak faturalandırılır.

Modeli şirket bazında değil, ajan bazında seçin. Bir şeyi araştırıp raporlayan tek araçlı bir ajan, Haiku üzerinde sorunsuz çalışır. 12 Ekim 2026 itibarıyla güncel sürüm olan Haiku 5.5, milyon giriş token'ı başına 0.10$ ve milyon çıkış token'ı başına 0.50$ olarak listelenir; uzun bir bellek penceresi ve büyük araç sonuçlarının zorlayabileceği 100.000 token sınırını aşan isteklerde bu rakamlar sırasıyla 0.50$ ve 2.50$'a yükselir. Ajan 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çinden Maximum Number of Tokens değerini ayarlayın. Bu, modelin ürettiği her yanıtın uzunluğunu sınırlar. Varsayılan olarak yüksek bırakılırsa, hatalı bir çalışma ç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 giriş öğesine göre çözümlenir, öğe başına değil. Öğe bazlı ifadeleri kök düğümün istem (prompt) alanlarına yerleştirin.

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

AI Agent düğümünü açın. Source for Prompt (User Message) parametresinin iki ayarı bulunur.

• Connected Chat Trigger Node, 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 tarafta bir Webhook düğümü olduğunda, POST gövdesi $json.body altına düşer, 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: aracı bir araca bağlayın

n8n belgeleri, bir AI Agent düğümüne en az bir araç alt düğümü bağlamanız gerektiğini belirtir; ancak mevcut düğüm kodu (sürüm 3.1) yalnızca bir sohbet modeli olmadan çalışmayı reddeder. Her iki durumda da işe tek bir araçla başlayın; çünkü çalışan tek bir araç, yarım yapılandırılmış dört araçtan daha fazla şey öğretir ve araçsız bir aracı, daha maliyetli bir zincirden ibarettir.

Bir HTTP Request düğümünü aracın Tool bağlantı noktasına takın. Düğümü normal bir HTTP Request düğümünü yapılandırdığınız gibi yapılandırın, ardından 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 bu curl komutu bir hata veya HTML giriş sayfası döndürürse, aracı da başarısız olacaktır. Hata, aslında bir URL veya kimlik doğrulama sorunu olmasına rağmen model kaynaklı bir sorun gibi görünecektir. Sorunu düğüm içinde değil, kabuk üzerinde çözün.

Aracın Description alanı iş arkadaşlarınız için bir dokümantasyon değildir. Model, bu aracı kullanıp kullanmayacağına karar verirken aracın adını ve parametre şemasını okuduğu gibi bu alanı da okur. Buraya, ne döndüğünü belirten net bir ifade yazın: "İzlenen bir servis için mevcut yukarı/aşağı durumunu ve kesinti süresini JSON olarak 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 bir AI Agent düğümüne bağlı araçlarda çalışır ve Code aracında çalışmaz.

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

Bağımsız değişkenler key, ardından isteğe bağlı description, type ve defaultValue şeklindedir. Anahtar; harfler, rakamlar, alt çizgiler ve tireler kullanılarak 1 ila 64 karakter uzunluğunda olmalıdır. Tür; string, number, boolean veya json değerlerinden biridir ve varsayılan olarak string değerini alır. Daha kapsamlı bir çağrı şu şekilde görünür.

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

Anahtar bir ipucudur, mevcut verilere bir referans değildir. $fromAI('service'), service adlı bir alanı hiçbir yerden okumaz. Modele "bir değer üret ve buna service adını ver" der; model de bu değeri bulmak için konuşmayı, girdi verilerini ve diğer araç sonuçlarını tarar. Sohbet iş akışında model, kullanıcıya doğrudan soru sorabilir.

Web araması genellikle ikinci araçtır ve bu da başka bir HTTP uç noktası olduğundan, bu düğümü ücretli bir arama API'si yerine kendi SearXNG örneğinize yönlendirebilirsiniz; ancak döndürülen her sayfayı, artık isteminizin (prompt) içinde yer alan güvenilmez bir metin olarak değerlendirmeniz şartıyla.

Adım 5: bellek ve ajanın unutma nedeni

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 tutulacağını belirler; böylece farklı anahtarlara sahip iki kullanıcı ayrı geçmişlere sahip olur. Context Window Length, isteme (prompt) kaç önceki etkileşimin tekrar dahil edileceğini belirler.

Context Window Length, kaliteyi etkilediği kadar maliyeti de etkiler; çünkü hatırlanan her etkileşim, sonraki her çağrıda girdi token'ı olarak tekrar gönderilir. Çok konuşan bir ajanda 20 birimlik bir pencere, aynı ilk mesajlar için yirmi kez ödeme yapmanız anlamına gelir.

n8n kuyruk (queue) modunda çalışırken Simple Memory aktif bir üretim iş akışında çalışmaz. Çünkü bu düğüm, geçmişi iş akışı ve oturum kimlikleri ile anahtarlanmış, süreç yerelinde bir singleton Map yapısında saklar ve worker'lar bu belleği paylaşmaz. Kuyruk modundaki bir örnekte, bunun yerine Postgres Chat Memory alt düğümünü kullanın ve bunu hem ana sürecin hem de worker'ların erişebileceği bir veritabanına yönlendirin.

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 bunu ne durdurur

Options (Seçenekler) altında, varsayılan değeri 10 olan Max Iterations (Maksimum Yineleme) ayarı bulunur. Bir yineleme, modelin araç talep ettiği veya nihai yanıtı döndürdüğü tek bir model çağrısıdır; araç sonuçları bir sonraki çağrıya girdi olarak beslenir. Dolayısıyla tek bir ajan çalışması tek bir API çağrısı değildir; on çağrıya kadar çıkabilir ve her biri, giderek büyüyen tüm konuşmayı girdi olarak taşır.

Bu değeri düşürün. Tek araçlı ajanların çoğu iki yinelemede tamamlanır; 3 veya 4 turluk bir sınır, kontrolsüz bir döngüyü yürütme listesinde görebileceğiniz temiz bir başarısızlığa 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; "model aracı hiç çağırmadı" durumu ile "araç yararlı bir sonuç döndürmedi" 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 (gürültü) oluşturur.

Bir çalışmanın gerçekleşmesini shell üzerinden izleyin.

docker compose logs -f n8n

Gözetimsiz bir ajanın sessizce harcama yapmasını engelleme

Chat Trigger arkasındaki bir ajanın içinde bir insan bulunur ve cevap hatalı göründüğünde bu insan süreci durdurur. Schedule Trigger arkasındaki bir ajanı ise izleyen kimse yoktur. Burada izlediğiniz şey lisans maliyetinden ziyade model harcamasıdır; çünkü ajan, araç ve bellek düğümlerinin tamamı ücretsiz self-hosted sürümde çalışır ve ücretli bir anahtar gerektiren özellikler çoğunlukla ekip ve yönetişim ile ilgilidir. Konunun tamamı her zaman açık bir VPS üzerinde AI ajan maliyet kontrolü başlığında ele alınmıştır. Bu noktada dört ayar işin büyük kısmını halleder.

• Model alt düğümündeki 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. Bir çalıştırmanın maliyeti neyse, çarpanınız bu rakamdır.

Üzerinde çalıştığınız iş akışını yayından kaldırın veya en azından hangi sürümün canlı olduğunu unutmayın. Schedule Trigger içeren yayınlanmış bir iş akışı, ekranınızdaki taslağı değil, en son yayınladığınız sürümü çalıştırmaya devam eder; çünkü n8n, siz tekrar yayınlayana kadar düzenlemelerinizi taslak olarak tutar.

FAQ

AI Agent düğümüm neden çalışmıyor?

Öncelikle bağlayıcıları kontrol edin. AI Agent düğümü bir sohbet modeli alt düğümüne ihtiyaç duyar; bu olmadan herhangi bir API çağrısı yapmadan "Please connect a model to the Chat Model input" hatasıyla durur. n8n belgeleri ayrıca en az bir araç alt düğümünün gerekli olduğunu belirtir. Eğer model bağlı olduğu halde düğüm hala çalışmıyorsa, basit bir araç dahi olsa bir araç ekleyin ve tekrar çalıştırın.

Ajan yanıt veriyor ancak aracımı hiç çağırmıyor. Sorun nedir?

Sorun neredeyse her zaman aracın Description alanındadır. Model, araçları bu açıklamaları okuyarak seçer; bu nedenle "HTTP Request" gibi bir açıklama, aracın ne zaman kullanılacağı hakkında hiçbir bilgi vermez. Açıklamayı, hangi verinin döndüğünü ve hangi durumda yararlı olduğunu belirtecek şekilde yeniden yazın. Ardından System Message kısmına, ajana yanıt vermeden önce o aracı çağırmasını söyleyen bir satır ekleyin.

Aynı soru neden her çalıştırıldığında farklı maliyete sahip oluyor?

Çünkü model, adım sayısını kendisi belirler. Her yineleme, önceki araç çıktıları da dahil olmak üzere o ana kadarki tüm konuşmayı yeniden gönderir. Bu nedenle dört yineleme süren bir çalışma, dört çağrının tamamındaki girdi ve çıktı token'ları üzerinden faturalandırılır. Max Iterations bu durum için bir üst sınırdır ve Return Intermediate Steps, belirli bir çalışmanın aslında kaç adım kullandığını gösterir.

Bellek düzenleyicide çalışıyor ancak üretim ortamında çalışmıyor. Ne değişti?

Örneğin kuyruk modunda (queue mode) çalışıp çalışmadığını kontrol edin. Simple Memory, geçmişi iş akışı ve oturum kimlikleriyle anahtarlanmış, süreç yerelinde bir singleton Map içinde saklar; ayrı çalışan işçi süreçleri (worker processes) bunu paylaşmaz. Geçmişi tüm işçilerin paylaştığı veritabanında tutan Postgres Chat Memory alt düğümüne geçiş yapın.