VPS üzerinde Claude tabanlı yapay zeka ajanı geliştirme

Claude ile bir ajan oluşturmanın anlamı

Claude ile bir ajan oluşturmak, Claude'u muhakeme çekirdeği olarak kullanırken döngünün, araçların ve verilerin kendi sunucunuzda barındırılması anlamına gelir. Claude ne yapılacağına karar verir; VPS'niz ise bu kararı uygular. Claude'a görevi ve mevcut durumu gönderirsiniz; Claude bir yanıtla veya araçlarınızdan birini kullanma talebiyle karşılık verir, kodunuz aracı çalıştırır ve sonucu geri gönderir; döngü, iş tamamlanana kadar bu şekilde devam eder. Zeka, internet üzerinden çağırdığınız bir servistir. Bunun dışındaki her şey size aittir.

Bu ayrım, yöntemin tercih edilme sebebidir. Bir model çalıştırmak zorunda kalmadan en üst düzey muhakeme yeteneğine sahip olursunuz ve ajanınızın nelere erişebileceği üzerinde tam kontrole sahip olursunuz; çünkü araçlar kendi donanımınız üzerinde çalışır. Eğer daha önce bir Claude programı oluşturduysanız, VPS üzerinde ilk Claude uygulaması rehberi, bu rehberin üzerine inşa edildiği temel bilgileri kapsamaktadır.

Claude'un beyni: Messages API

Claude'a yapılan her çağrı, tek bir uç nokta olan Messages API üzerinden gerçekleşir. Bu uç noktaya, o ana kadarki konuşmayı ve ajanın kullanabileceği araçların listesini gönderirsiniz; Claude ise size bir sonraki mesajını iletir. Bu mesaj ya nihai bir yanıt ya da bir araç çağırma isteğidir. Kendi çözümünüzü oluşturduğunuz senaryoda ayrı bir "ajan API'si" bulunmaz: araç kullanımı bu tek uç noktanın bir özelliğidir ve etrafındaki döngüyü yönetmek sizin sorumluluğunuzdadır.

Claude çağrılar arasında durum bilgisini tutmaz (stateless), yani kendi başına hiçbir şeyi hatırlamaz. Her istek, konuşmanın tamamını taşır. Geçmişi kodunuz tutar ve her adımda yeniden gönderir; uzun bir oturumdaki her adımın bir öncekinden daha fazla token tüketmesinin nedeni budur. Bu bir kısıtlamadan ziyade bir tasarım tercihidir: durum bilgisi sizin sunucunuzda yaşadığı için Claude'un neyi gördüğüne tam olarak siz karar verirsiniz ve görevle ilgili hiçbir veri sizin kontrolünüz dışında bir yerde saklanmaz. Bu durum, istemin (prompt) sürekli büyümesi anlamına gelir. Claude'un bağlam penceresi (context window) bunu rahatlıkla karşılasa da, aynı döngüdeki yerel bir model bunu yapamaz; Ollama'nın uzun istemleri kesmeyi bırakması için num_ctx değerinin artırılması gerekliliğinin nedeni budur.

Araç kullanımı bir aracı döngüsüdür

Claude ile aracı döngüsünü tanımlamak oldukça basittir. Araçlarınızı içeren bir istek gönderirsiniz. Claude görevi okur ve işlem yapması gerekirse, bir aracın adını belirten ve girdilerini dolduran bir araç kullanım isteğiyle yanıt verir. Kodunuz bu aracı çalıştırır ve ardından sonucu bir sonraki istekte Claude'a geri gönderir. Claude sonucu okur ve ya başka bir araç ister ya da nihai yanıtını yazar. Araç istemeyi bıraktığında görev tamamlanmış olur.

Bu döngüyü birkaç satırda elle yazabilirsiniz; birçok kişi bunu yapar çünkü kontrol etmesi ve görmesi kolaydır. Resmi SDK'lar da döngüyü sizin yerinize yöneten bir araç çalıştırıcı (tool runner) sağlar: araç fonksiyonlarını sağlarsınız, SDK ise Claude'u çağırma, araçlarınızı çalıştırma ve Claude işlemi bitirene kadar sonuçları geri besleme sürecini yönetir. Her iki durumda da yapı aynıdır. Çalıştırıcı, döngüyü kendiniz yazma zahmetinden sizi kurtarır. Eğer döngü hala soyut geliyorsa, bir çalıştırıcıya başvurmadan önce minimal bir tane yazmak en iyi çözümdür; diğer her şeyin üzerine inşa edildiği adım yapay zeka aracılarını sıfırdan öğrenmeye yönelik bu aşamalı yol içerisinde yer almaktadır.

Derleme için üç yöntem ve VPS için uygun olanlar

Bir Claude ajanı oluşturmanın üç yolu vardır ve bunlar, altyapının ne kadarını çalıştırdığınıza göre farklılık gösterir.

Birinci yöntem, kendi araçlarınızla Claude API'sini çağıran kendi kodunuzu kullanmaktır. Döngüyü siz yazarsınız veya SDK'nın araç çalıştırıcısını kullanırsınız ve tüm yapıyı VPS'niz üzerinde barındırırsınız. Araçlar, veriler ve güvenlik üzerinde tam kontrol sağladığı ve sunucunuzda sıradan bir program olarak çalıştığı için bu yaygın bir tercihtir. Bu kılavuzun büyük bir kısmı bu yolu temel alır.

İkinci yöntem, Claude Agent SDK'dır. Bu, üzerine inşa edebileceğiniz bir kütüphane olarak paketlenmiş kodlama ajanı Claude Code'dur. Tam bir ajan döngüsü ve dosya okuma/yazma, kabuk komutlarını çalıştırma ve arama yapma gibi yerleşik araçlarla birlikte gelir; böylece bunları sıfırdan bir araya getirmeniz gerekmez. Ayrıca kendi sunucunuzda çalışır; bu da onu, kendi altyapınızı kurmadan yetenekli bir dosya ve kabuk ajanı istediğinizde VPS için güçlü bir seçenek haline getirir. Dosya okuyan ve kabuk komutları çalıştıran bir ajanın, gözetimsiz çalışmadan önce kapsüllenmesi gerekir ve Claude Code'u bir sunucuda güvenli bir şekilde çalıştırma bölümü; izin sistemini, sandbox ortamını ve izolasyon seçeneklerini ele alır.

Üçüncü yöntem ise, döngünün Anthropic tarafından çalıştırıldığı ve ajanın araçlarının yürütüldüğü bir sandbox ortamının barındırıldığı Yönetilen Ajanlardır (Managed Agents). Bu, müdahale gerektirmeyen seçenektir: yönetmeniz gereken çok daha az şey vardır, ancak ajanın çalışma alanı VPS'niz yerine Anthropic'in altyapısında bulunur. Operasyonel iş yükünün en az olmasını istediğinizde ve araçların kendi makinenizde çalışmasına ihtiyaç duymadığınızda bu yöntemi tercih edin. Diğer iki yöntem için sunucunuz ajanın ana merkezidir ve bu kılavuzun geri kalanı bununla ilgilidir.

Araçları MCP ile bağlama

Hangi yolu seçerseniz seçin, ajanı gerçek sistemlere bağlamak isteyeceksiniz; Model Context Protocol (MCP) bunu yapmanın düzenli yoludur. MCP, araçları ve verileri bir ajana sunmak için kullanılan açık bir standarttır. Her servis için manuel olarak entegrasyon kodlamak yerine, Claude'u bu yetenekleri halihazırda araç olarak sunan bir MCP sunucusuna yönlendirirsiniz. MCP sunucularını aynı VPS üzerinde, her biri yalnızca ihtiyaç duyduğu erişim yetkisine sahip küçük servisler olarak çalıştırabilirsiniz; bu konuyu VPS üzerinde MCP sunucuları çalıştırma bölümünde ele alıyorum.

Model seçimi

Claude çeşitli modellerle sunulmaktadır; doğru modeli seçmek yetenek, hız ve maliyet arasında bir denge kurmayı gerektirir. Bu yazının hazırlandığı tarih itibarıyla ana seçenekler şunlardır: karmaşık mantık yürütme ve uzun süreli aracı (agent) görevleri için yetenekli varsayılan seçenek olan Claude Opus 4.8 (claude-opus-4-8); birçok görevde Opus'a yakın performans sergileyen, daha hızlı ve ekonomik dengeli bir seçenek olan Claude Sonnet 5 (claude-sonnet-5); ve basit, yüksek hacimli işlemler için en hızlı ve en ucuz model olan Claude Haiku 4.5 (claude-haiku-4-5). Bunların üzerinde, en zorlu işler için tasarlanmış en yetenekli model olan Claude Fable 5 (claude-fable-5) yer alır. Kodunuzda model tanımlayıcısını, sonuna tarih eklemeden tam olarak kullanın.

Pratik bir yöntem, bu modelleri birlikte kullanmaktır. Rutin araç çağrılarını daha ucuz bir modelin, zorlu kararları ise daha güçlü bir modelin yönetmesini sağlayın. Model ismi isteğiniz içerisinde yalnızca bir metin dizisi olduğundan, geçiş yapmak tek satırlık bir değişiklik gerektirir. Bu nedenle başlangıçta yetenekli bir varsayılan modelle başlayın ve hız veya maliyetin kaliteye göre daha kritik olduğu durumlarda daha düşük modelleri tercih ederek optimizasyon yapın.

Ajanı VPS üzerinde güvenli bir servis olarak çalıştırma

Bir ajan ancak çalışır durumda kaldığında faydalıdır ve yalnızca sınırlandırıldığında güvenlidir. Bir VPS üzerinde her iki durum da, ajanı terminalde elle başlatılan bir program yerine güvenli bir sistem servisi olarak çalıştırmakla sağlanır. Servis olarak başlatıldığında sistem açılışında otomatik devreye girer, çökerse yeniden başlar ve günlük kayıtlarını journal sistemine aktarır. Güvenlik katmanı olarak, yalnızca ihtiyaç duyduğu erişim haklarına sahip, yetkisiz bir kullanıcı olarak çalıştırılır; böylece bir hata veya hatalı komutun etkisi sınırlı kalır. Bir servis birimi yalnızca sürecin nelere erişebileceğini kısıtlayabilir; bu nedenle geri kalan güvenlik önlemleri, ajanın kendi yapısı içinde yer almalıdır. Yüklenmeye değer DeepSeek Harness eklentileri farklı bir katmanda harcama limitleri, araç bazlı izin kuralları ve istem enjeksiyonu taraması gibi görevleri üstlenir.

En önemli kural, Claude API anahtarınızı sunucu tarafında tutmaktır. Anahtar, yapılan her çağrıyı öder ve yetkilendirir; bu nedenle yalnızca ajanın kullanıcısı tarafından okunabilen bir dosyada bulunmalı, servis ortamına bir ortam değişkeni olarak yüklenmeli ve asla kod içinde, bir depoda veya tarayıcının erişebileceği herhangi bir yerde tutulmamalıdır. Ajanınız için eksiksiz ve güvenli bir servis birimini buradan oluşturun:

Ardından sunucunun kendisini yapılandırmayı tamamlayın. SSH erişimini yalnızca anahtarlarla sınırlandırın ve VPS üzerinde SSH güvenliğini sağlama rehberinde belirtildiği gibi yönetim hesabınızı kilitleyin. Ajanı geliştirirken etkileşimli bir oturum üzerinden yönetmeyi tercih ederseniz, tmux ile VPS üzerinde Claude Code çalıştırma iyi bir yardımcıdır. Aynı sunucuda ikinci bir oturum açtığınızda, her komutu bir bölmeden diğerine taşımak yerine iki oturum arasında iş akışı sağlayabilirsiniz. Tüm bunların arkasındaki kavramları belirli bir modele bağlı kalmadan öğrenmek isterseniz, VPS üzerinde kendi yapay zeka ajanınızı oluşturma rehberi temel prensipleri açıklamaktadır.

Eğer bir terminal kodlama asistanı arıyorsanız, VPS üzerinde kodlama yapay zeka ajanı çalıştırma rehberi Aider ve Goose araçlarını kapsamaktadır.

FAQ

Bir ajan oluşturmak için hangi Claude modelini kullanmalıyım?

Varsayılan ve yetenekli seçenek olan Claude Opus 4.8 (claude-opus-4-8) ile başlayın ve ihtiyaçlarınıza göre ayarlayın. Claude Sonnet 5 (claude-sonnet-5) çoğu iş için daha ucuz ve hızlıdır, Claude Haiku 4.5 (claude-haiku-4-5) basit ve yüksek hacimli adımlar için en iyisidir, Claude Fable 5 (claude-fable-5) ise en zorlu görevler için en yetenekli modeldir. Yaygın bir yöntem, rutin adımlar için daha ucuz bir model, zor kararlar için ise daha güçlü bir model kullanmaktır; çünkü modeller arası geçiş tek satırlık bir değişiklik gerektirir.

Ajanın tamamını kendi VPS'imde mi çalıştırmalıyım, yoksa Anthropic mi çalıştırıyor?

Bu, seçtiğiniz yaklaşıma bağlıdır. Claude API üzerinde kendi döngünüzü yazarsanız veya Claude Agent SDK kullanırsanız, ajan tamamen sizin VPS'inizde çalışır ve Anthropic'e yalnızca model çağrıları gider. Managed Agents kullanırsanız, döngüyü Anthropic çalıştırır ve araçların yürütüldüğü sandbox ortamını barındırır; bu durumda sunucunuzda daha az bileşen yer alır. Kendi makinenizde çalışan bir ajan için ilk iki yöntemden birini kullanın.

Claude API ile Claude Agent SDK arasındaki fark nedir?

Claude API, ham Messages uç noktasıdır: bir konuşma ve araçlar gönderir, etrafına ajan döngüsünü kendiniz yazarsınız veya yönlendirme için SDK'nın araç çalıştırıcısını kullanırsınız. Claude Agent SDK ise üzerine inşa etmeniz için paketlenmiş, tam bir döngü ile yerleşik dosya, kabuk ve arama araçlarını içeren daha üst seviye bir kütüphanedir (Claude Code). Her şeyi kendiniz tanımlamak istediğinizde API'yi, altyapıyı kurmakla uğraşmadan yetenekli bir ajana sahip olmak istediğinizde ise Agent SDK'yı kullanın.

Claude API anahtarımı sunucuda nasıl güvende tutarım?

Anahtarı sunucu tarafında tutun ve kodunuzun dışında bırakın. Yalnızca ajanı çalıştıran hesabın okuyabileceği bir dosyada saklayın, servis içine ortam değişkeni olarak yükleyin ve asla bir depoya (repository) işlemeyin veya tarayıcıya açık etmeyin. Claude'a yapılan her istek sunucunuzdan gittiği için anahtarın kullanıcının cihazına ulaşmasına gerek kalmaz; bu da sunucu tabanlı bir ajanı, istemci uygulamasında gömülü olan bir ajana göre güvenli hale getirmeyi kolaylaştırır.

Claude ile bir ajan oluşturmak için bir modeli kendi sunucumda barındırmam (self-host) gerekir mi?

Hayır. Claude ile model, API üzerinden çağırdığınız barındırılan bir servistir; bu nedenle GPU üzerinde çalıştırmanız gereken bir şey yoktur. VPS'iniz ajan döngüsünü, araçları ve verileri çalıştırır; mantıksal çıkarım ise Anthropic tarafında gerçekleşir. Mütevazı bir sunucunun yetenekli bir ajanı çalıştırmasını sağlayan şey budur. Eğer tamamen yerel bir model kullanmak isterseniz, bu durum kendi yapay zeka ajanı oluşturma rehberinde ele alınan self-hosted (kendi sunucunuzda barındırma) yoludur.