Kendi VPS'inizde n8n AI agent kurma rehberi

n8n AI agent nedir ve chain'den farkı nedir

Bir n8n AI agent, kendisine alt düğümlerin bağlandığı tek bir AI Agent düğümüdür: bir chat model, bir veya daha fazla tool ve isteğe bağlı bir memory. Düz dille bir hedef belirtilir. Model, yanıt verebilene kadar hangi araçların hangi sırayla çağrılacağına karar verir. Aşağıdaki tüm yapılandırma bu tek fikir etrafındadır.

Bir chain bunun tersine çalışır. Bir Basic LLM Chain içinde adımlara karar verilir ve model yalnızca metni oluşturur. Bir agent içinde adımlara model karar verir. Bu nedenle aynı soru bugün bir model çağrısına, yarın ise dokuz çağrıya mal olabilir. Bu tek fark, bu kılavuzdaki tüm ayarları belirler.

Bu açıklamada n8n'nin, kontrol edilen bir makinede HTTPS arkasında zaten çalıştığı varsayılır. Böyle değilse gerçek bir sertifikayla Docker üzerinde n8n self-hosting kılavuzuyla başlanmalıdır. Çünkü saklanacak API key için bu kılavuzda zorunlu tutulan encryption-key yedeği gerekir. Agent kullanılmayan kalıplar, webhook özetleyicileri ve zamanlanmış sınıflandırıcılar için Claude ve n8n workflow kalıpları bölümüne bakılmalıdır.

Buradaki alan adlarına güvenmeden önce sürüm kontrol edilmelidir. n8n, AI düğümlerini sık sık değiştirir.

docker compose exec n8n n8n --version

Bu kılavuzdaki adlar, Temmuz 2026 itibarıyla n8n current stable sürümüyle eşleşir. 1.82.0 sürümünden itibaren her AI Agent düğümü Tools Agent olarak çalışır. Bu nedenle eski agent-type açılır listesi artık yoktur.

Adım 1: tetikleyiciyi seçin

Konuşma aracısı için bir Chat Trigger düğümü ekleyin. Oluşturma sırasında Make Chat Publicly Available seçeneğini kapalı bırakın. Böylece yalnızca düzenleyicinin sohbet paneli bu aracıya erişebilir. Aracı tamamladıktan ve kimlik doğrulama yöntemine karar verdikten sonra seçeneği açın.

Chat Trigger, aracıya chatInput adlı bir alan sağlar. Bu ad, 3. adımda önemlidir. Adın yanlış yazılması, ilk aşamadaki en yaygın hatadır.

İnsan müdahalesi olmadan çalışan bir aracı için bunun yerine Schedule Trigger veya Webhook düğümünü kullanın. Bu düğümlerin hiçbiri chatInput üretmez. Bu nedenle istemi kendiniz yazmanız gerekir.

Adım 2: model kimlik bilgisi

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

Kimlik bilgisini platform.claude.com adresindeki Anthropic Console üzerinden, önce Settings, ardından API Keys bölümünden oluşturun. Anahtar yalnızca bir kez gösterilir. API kullanımı belirteç başına ücretlendirilir ve herhangi bir Claude.ai aboneliğinden ayrıdır. Bu nedenle ilk çalıştırmadan önce hesap için faturalandırma ayarlanmalıdır.

Modeli şirket başına değil, aracı başına seçin. Bir aracı kullanarak bir bilgiyi arayan ve bildiren tek araçlı bir aracı Haiku ile çalıştırmak genellikle yeterlidir. Haiku, July 2026 itibarıyla 1 milyon giriş belirteci için $1 ve 1 milyon çıkış belirteci için $5 olarak listelenir. Aracın birden fazla aracı olduğunda ve bunlar arasında planlama yapması gerektiğinde Sonnet'e geçin. Kaçınılması gereken durum, yanlış aracı dört kez çağıran ucuz bir modelin, doğru aracı bir kez çağıran pahalı modelden daha yüksek maliyet oluşturmasıdır.

Alt düğümün seçeneklerinde Maximum Number of Tokens değerini ayarlayın. Bu değer, modelin ürettiği her yanıtın uzunluğunu sınırlar. Büyük bir varsayılan değer bırakılırsa, tek bir hatalı çalıştırma çok uzun bir yanıt üretebilir ve bunun ücretini ödemeniz gerekebilir.

n8n belgelerinde belirtilen ve sıkça gözden kaçan bir nokta vardır: Alt düğüm içindeki ifadeler her zaman ilk giriş öğesine göre çözümlenir; öğe başına çözümlenmez. Öğe başına kullanılan ifadeleri kök düğümün istem alanlarına yerleştirin.

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

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

• Take from previous node automatically, chatInput adlı gelen alanı bekler. Chat Trigger arkasında kullanılacak doğru seçim budur.
• Define below, statik metin veya ifade yazabileceğiniz Prompt (User Message) alanını gösterir. Schedule Trigger veya Webhook düğümü arkasında kullanılacak doğru seçim budur.

Önünde bir Webhook düğümü bulunduğunda POST gövdesi $json.body altında yer alır. Bu durumda istem alanı aşağıdaki gibi 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.

4. Adım: aracı tek bir araçla sınırlama

Araç alt düğümü olmayan bir AI Agent düğümü çalışmayı reddeder. Önce tek bir araç eklenmelidir. Çalışan tek bir araç, yarı yapılandırılmış dört araçtan daha fazla bilgi sağlar.

Agent düğümünün Tool bağlantı noktasına bir HTTP Request düğümü bağlayın. Bu düğümü normal bir HTTP Request düğümünü yapılandırdığınız şekilde yapılandırın. Ardından, bu uç noktayı önce bir shell üzerinden test edin.

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

Bu curl komutu hata veya HTML giriş sayfası döndürürse agent da başarısız olur. Bu durumda hata bir model sorunu gibi görünebilir. Asıl sorun URL veya kimlik doğrulama olabilir. Sorunu düğümde değil, shell üzerinde düzeltin.

Aracın Description alanı çalışma arkadaşlarınız için bir belge değildir. Modelin bu aracın ilgili olup olmadığına karar verirken okuduğu tek içerik budur. Bu alanı, döndürülen sonucu açıkça belirten basit bir ifade olarak yazın: "İzlenen tek bir hizmetin mevcut up veya down durumunu ve kesinti süresini JSON olarak döndürür."

Modelin isteğin bir bölümü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. 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 değerleridir. Anahtar 1 ile 64 karakter arasında olmalıdır. Harf, rakam, alt çizgi ve kısa çizgi kullanılmalıdır. Tür string, number, boolean veya json değerlerinden biridir ve varsayılan değer string olur. Daha kapsamlı bir çağrı aşağıdaki gibidir.

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

Anahtar bir ipucudur; mevcut verilere başvuru değildir. $fromAI('service') herhangi bir yerden service adlı bir alanı okumaz. Modele "bir değer üret ve bunu service olarak adlandır" talimatını verir. Model, bu değeri bulmak için konuşmayı, giriş verilerini ve diğer araç sonuçlarını inceler. Bir sohbet iş akışında kullanıcıya doğrudan soru sorabilir.

Adım 5: bellek ve aracının neden unuttuğu

Bir bellek alt düğümü olmadan her ileti sıfırdan başlar. Yakın zamandaki konuşmayı tutmak için bir Simple Memory alt düğümü bağlayın.

Bu alt düğümde iki parametre bulunur. Session Key, bunun hangi konuşma olduğunu belirler. Bu nedenle farklı anahtarlara sahip iki kullanıcı ayrı geçmişlere sahip olur. Context Window Length, önceki etkileşimlerden kaç tanesinin isteme yeniden ekleneceğini belirler.

Context Window Length, kalite ayarı olduğu kadar maliyet ayarıdır. Bunun nedeni, hatırlanan her turun sonraki her çağrıda giriş belirteçleri olarak yeniden gönderilmesidir. Çok konuşkan bir aracıda 20 uzunluğundaki bir pencere, aynı ilk iletiler için 20 kez ödeme yapılması anlamına gelir.

n8n queue mode ile çalışırken Simple Memory etkin bir üretim iş akışında çalışmaz. Bunun nedeni, geçmişin paylaşılan bir veri deposunda değil, iş akışının kendi verilerinde tutulmasıdır. queue mode kullanan bir örnekte bunun yerine Postgres Chat Memory alt düğümünü kullanın ve bu düğümü hem ana işlemin hem de worker'ların erişebileceği bir veritabanına yönlendirin.

Adım 6: Sistem Mesajı

Aracının Options bölümünü açın ve bir System Message ekleyin. İş tanımı buraya yazılır ve bu metin, iş akışındaki en yüksek etkili unsurdur.

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.

"Always call the status tool before answering" ifadesi burada gerçekten işlev görür. Bu ifade olmadan, yanıtı zaten bildiğini düşünen bir model aracı atlayıp belleğinden yanıt verir. Altyapınız değiştiği anda bu yanıt, kendinden emin ancak yanlış olur.

Aracı neden döngüye girer ve bunu ne durdurur

Options altında varsayılan değeri 10 olan Max Iterations da bulunur. Bir yineleme, bir model çağrısı ile bağlama geri beslenen bir araç sonucundan oluşur. Bu nedenle tek bir aracı çalıştırması tek bir API çağrısından ibaret değildir. En fazla on çağrı yapılır ve her çağrıda, giderek büyüyen konuşmanın tamamı girdi olarak taşınır.

Bu değeri düşürün. Tek araç kullanan aracıların çoğu iki yinelemede tamamlanır. 3 veya 4 turluk bir sınır, kontrol dışı bir döngüyü yürütme listesinde görebileceğiniz temiz bir hataya dönüştürür.

Hata ayıklarken Return Intermediate Steps seçeneğini etkinleştirin. Böylece nihai çıktı, aracının süreç boyunca yaptığı araç çağrılarını da içerir. Bu sayede "model aracı hiç çağırmadı" durumunu "araç yararlı bir sonuç döndürmedi" durumundan ayırt edebilirsiniz. Canlıya almadan önce bu seçeneği yeniden kapatın. Bu adımlar son kullanıcı için gereksiz ayrıntıdır.

Bir çalıştırmanın gerçekleşmesini kabuktan izleyin.

docker compose logs -f n8n

Denetimsiz bir aracının sessizce harcama yapmasını önleme

Chat Trigger arkasındaki bir aracının içinde bir insan bulunur ve yanıt hatalı göründüğünde bu kişi aracı durdurur. Schedule Trigger arkasındaki aracı ise izleyen kimse yoktur. Ayrıntılı açıklama sürekli açık bir VPS üzerinde yapay zeka aracısı maliyet denetimi 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ırlandırın. Böylece tek bir yanıtın gereğinden uzun sürmesi önlenir.
• Görevi tamamlamaya yeten en düşük değere Max Iterations ayarını getirin.
• Araç yanıtlarını küçük tutun. 4,000 satırlık JSON blob'u döndüren bir araç, içeriğin tamamını sonraki model çağrısına ve aynı çalıştırmadaki bundan sonraki her çağrıya aktarır.
• Aracının gerçekten bir zamanlamaya ihtiyaç duyup duymadığını değerlendirin. Her beş dakikada bir çalışan bir iş, günde 288 kez tetiklenir. Tek çalıştırmanın maliyeti ne olursa olsun, çarpılması gereken değer budur.

Yineleme yaparken workflow'u devre dışı bırakın. Schedule Trigger içeren etkin bir workflow, n8n'in kaydettiği sürüm üzerinden çalışmaya devam eder. Bu sürüm, ekranda görülen sürümle her zaman aynı olmayabilir.

FAQ

AI Agent düğümüm neden çalıştırmayı reddediyor?

AI Agent düğümü bir chat model alt düğümü ve en az bir tool alt düğümü gerektirir. Model içeren ancak tool içermeyen bir düğüm, herhangi bir API çağrısı yapmadan önce başarısız olur. Önemsiz bir tool olsa bile bir tool ekleyin ve düğümü yeniden çalıştırın.

Agent yanıt veriyor, ancak tool'umu hiç çağırmıyor. Sorun nedir?

Sorun neredeyse her zaman tool'un Description alanıdır. Model, tool'ları bu açıklamaları okuyarak seçer. Bu nedenle "HTTP Request" gibi bir açıklama, tool'un hangi durumda kullanılacağı hakkında bilgi vermez. Açıklamayı, hangi verilerin döndüğünü ve tool'un hangi durumda yararlı olduğunu belirtecek şekilde yeniden yazın. Ardından System Message alanına, yanıt vermeden önce agent'ın bu tool'u çağırmasını belirten bir satır ekleyin.

Aynı soru neden her çalıştırmada farklı bir tutara mal oluyor?

Bunun nedeni, modelin adım sayısını seçmesidir. Her yinelemede, önceki tool çıktısı dahil olmak üzere o ana kadarki konuşmanın tamamı yeniden gönderilir. Bu nedenle dört yineleme süren bir çalıştırmanın maliyeti, tek bir çağrının maliyetinin dört katından çok daha fazla olabilir. Max Iterations bu sayı için üst sınırı belirler. Return Intermediate Steps ise belirli bir çalıştırmada gerçekte kaç adım kullanıldığını gösterir.

Belleğim editörde çalışıyor, ancak production ortamında çalışmıyor. Ne değişti?

Instance'ın queue mode'da çalışıp çalışmadığını kontrol edin. Simple Memory, geçmişi workflow'un kendi execution data'sında depolar. Bu veriler ayrı bir worker process'e devredildiğinde korunmadığından, etkin bir production workflow'u geçmişi kaybeder. Geçmişi her worker'ın paylaştığı database'de tutan Postgres Chat Memory alt düğümünü kullanın.