Claude ile VPS üzerinde AI agent yapımı

Claude ile bir agent oluşturmanın anlamı

Claude ile bir agent oluşturmak, Claude'u akıl yürütme çekirdeği olarak kullanmak; döngü, araçlar ve verilerin ise kendi sunucunuzda bulunması demektir. Claude ne yapılacağına karar verir; VPS'iniz ise bunu uygular. Claude'a görevi ve mevcut durumu gönderirsiniz; Claude ise ya bir cevap ya da bir aracın kullanılması için bir istek ile yanıt verir; kodunuz aracı çalıştırır ve sonucu geri gönderir ve döngü iş bitene kadar devam eder. Zeka, internet üzerinden çağrılan bir hizmettir. Etrafındaki her şey size aittir.

Bu ayrım, sistemin cazibe noktasıdır. Bir modeli çalıştırmak zorunda kalmadan en üst düzey akıl yürütme yeteneğine sahip olursunuz ve agent'ın neye dokunabileceği üzerinde tam kontrole sahip olursunuz, çünkü araçlar size ait donanım üzerinde çalışır. Eğer halihazırda ilk Claude programınızı oluşturduysanız, ilk Claude uygulaması için VPS rehberi bu rehberin üzerine inşa edildiği temelleri kapsar.

Claude beyindir: Messages API

Claude'a yapılan her çağrı tek bir uç nokta olan Messages API üzerinden gerçekleşir. Mevcut konuşmayı ve agent'ın kullanabileceği araçların listesini gönderirsiniz; Claude ise bir sonraki mesajını geri gönderir. Bu mesaj ya nihai bir cevaptır ya da bir aracı çağırma isteğidir. Kendi sisteminizi kurma yolunda ayrı bir "agent API" bulunmamaktadır: araç kullanımı bu tek uç noktanın bir özelliğidir ve etrafındaki döngünün çalıştırılması size aittir.

Claude çağrılar arasında durum bilgisi tutmaz (stateless), bu da kendi başına hiçbir şeyi hatırlamadığı anlamına gelir. Her istek tüm konuşmayı taşır. Kodunuz geçmişi tutar ve her adımda bunu gönderir; bu durum uzun bir oturumda her adımın neden bir öncekinden daha fazla token maliyetine yol açtığını açıklar. Bu bir kısıtlamadan ziyade bir tasarım tercihidir: durum bilgisi sunucunuzda yaşadığı için Claude'un tam olarak neyi göreceğine siz karar verirsiniz ve görevle ilgili hiçbir şey kontrolünüz dışındaki bir yerde saklanmaz.

Araç kullanımı agent döngüsüdür

Claude ile agent döngüsünü tanımlamak basittir. Araçlarınızı içeren bir istek gönderirsiniz. Claude görevi okur ve eğer harekete geçmesi gerekirse, bir aracı isimlendiren ve girişlerini dolduran bir araç kullanım isteği ile 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 ve birçok kişi bunu yapar, çünkü görülmesi ve kontrol edilmesi kolaydır. Resmi SDK'lar ayrıca döngüyü sizin yerinize yöneten bir araç çalıştırıcı (tool runner) sağlar: siz araç fonksiyonlarını sağlarsınız ve SDK; Claude'u çağırma, araçlarınızı çalıştırma ve Claude işini bitirene kadar sonuçları geri besleme işlemlerini yönetir. Her iki durumda da yapı aynıdır. Çalıştırıcı sadece döngüyü kendiniz yazmaktan sizi kurtarır.

Üç inşa yöntemi ve VPS için uygun olanlar

Bir Claude agent'ı oluşturmanın üç yolu vardır ve bunlar, ne kadar mekanizmayı çalıştırdığınıza göre değişir.

Birincisi, kendi araçlarınızla Claude API'sini çağıran kendi kodunuzdur. Döngüyü yazarsınız veya SDK'nın araç çalıştırıcısını kullanırsınız ve tüm yapıyı VPS'inizde barındırırsınız. Bu yaygın bir seçimdir çünkü araçlar, veriler ve güvenlik üzerinde tam kontrol sağlar ve sunucunuzda sıradan bir program olarak çalışır. Bu rehberin çoğu bu yolu varsayar.

İkincisi, Claude Agent SDK'dır. Bu, üzerine inşa edebileceğiniz bir kütüphane olarak paketlenmiş olan kodlama agent'ı Claude Code'dur. Dosyaları okumak ve yazmak, kabuk (shell) komutlarını çalıştırmak ve arama yapmak için tam bir agent döngüsü ve yerleşik araçlarla birlikte gelir, böylece bunları sıfırdan oluşturmanıza gerek kalmaz. Bu da kendi sunucunuzda çalışır; bu da kendi mekanizmanızı kurmak istemediğinizde yetenekli bir dosya ve kabuk agent'ı istiyorsanız VPS için güçlü bir seçenek olmasını sağlar. Dosyaları okuyan ve kabuk komutlarını çalıştıran bir agent'ın, gözetimsiz çalışmadan önce bir izolasyona ihtiyacı vardır ve Claude Code'u bir sunucuda güvenli bir şekilde çalıştırmak yetki sistemini, sandbox yapısını ve izolasyon seçeneklerini kapsar.

Üçüncüsü, Anthropic'in döngüyü çalıştırdığı ve agent araçlarının yürütüldüğü bir sandbox barındırdığı Yönetilen Agent'lardır (Managed Agents). Bu, zahmetsiz seçenektir: sizin işletmeniz gereken çok daha az şey vardır, ancak agent'ın çalışma alanı sizin VPS'iniz yerine Anthropic'in altyapısında bulunur. En az operasyonel işi istediğinizde ve araçların kendi makinenizde çalışmasına ihtiyaç duymadığınızda bu yöntemi tercih edin. Diğer ikisi için sunucunuz agent'ın evidir ve bu rehberin geri kalanı bunun hakkındadır.

Araçları MCP ile bağlamak

Hangi yolu seçerseniz seçin, agent'ı gerçek sistemlere bağlamak isteyeceksiniz ve Model Context Protocol (MCP) bunu yapmanın düzenli yoludur. MCP, araçların ve verilerin bir agent'a sunulması için açık bir standarttır. Her servis için ayrı bir entegrasyon kodu yazmak 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 ihtiyacı olan erişime sahip küçük servisler olarak çalıştırabilirsiniz; bunu bir VPS üzerinde MCP sunucuları çalıştırmak bölümünde ele alıyorum.

Model seçimi

Claude birkaç model ile gelir ve bir model seçmek; yetenek, hız ve maliyet arasında bir dengedir. Yazıldığı tarih itibarıyla yaygın seçimler şunlardır: Claude Opus 4.8 (claude-opus-4-8), zorlu akıl yürütme ve uzun agent çalıştırmaları için yetenekli varsayılan; Claude Sonnet 5 (claude-sonnet-5), birçok görevde Opus'a yakın kalırken daha ucuz ve daha hızlı olan dengeli bir seçenek; ve Claude Haiku 4.5 (claude-haiku-4-5), basit ve yüksek hacimli adımlar için en hızlı ve en ucuz olanıdır. Bunların üzerinde, en zorlu işler için en yetenekli model olan Claude Fable 5 (claude-fable-5) bulunur. Kodunuzda, tarih eklemeden tam model tanımlayıcısını kullanın.

Pratik bir yöntem bunları karıştırmaktır. Rutin araç çağrılarını daha ucuz bir modele, zor kararları ise daha güçlü bir modele bırakın. Model isteğinizde sadece bir dize (string) olduğu için geçiş yapmak tek satırlık bir değişikliktir; bu nedenle yetenekli bir varsayılanla başlayın ve hız veya maliyet kaliteden daha önemli olduğunda aşağı doğru ayarlama yapın.

VPS üzerinde güçlendirilmiş bir servis olarak çalıştırın

Bir agent, ancak çalışmaya devam ederse kullanışlıdır ve ancak izole edilirse güvenlidir. Bir VPS üzerinde her ikisi de, agent'ın bir terminalde elle başlatılan bir program yerine, güçlendirilmiş bir sistem servisi olarak çalıştırılmasından kaynaklanır. Bir servis olarak, önyüklemede başlar, çökerse yeniden başlatılır ve journal'a günlük tutar. Güçlendirilmiş olarak, yalnızca ihtiyacı olan erişime sahip yetkisiz bir kullanıcı olarak çalışır, böylece bir hata veya hatalı bir talimatın sınırı olur.

En önemli kural, Claude API anahtarınızı sunucu tarafında tutmaktır. Anahtar her çağrıyı öder ve yetkilendirir, bu nedenle yalnızca agent kullanıcısı tarafından okunabilen bir dosyada bulunmalı, servise bir ortam değişkeni olarak yüklenmeli ve asla koda, bir depoya (repository) veya bir tarayıcının ulaşabileceği herhangi bir yere konulmamalıdır. Agent'ınız için tam, güçlendirilmiş bir servis birimi burada oluşturulmuştur:

Ardından sunucunun kendisini tamamlayın. SSH'ı yalnızca anahtarlara (keys) ayırın ve bir VPS üzerinde SSH güçlendirmesi kısmında olduğu gibi yönettiğiniz hesabı kısıtlayın. Eğer agent'ı inşa ederken etkileşimli bir oturumdan yönetmeyi tercih ederseniz, tmux ile bir VPS üzerinde Claude Code çalıştırmak iyi bir yardımcıdır. Ve tüm bunların arkasındaki kavramları, tek bir modele bağlamadan öğrenmek isterseniz, bir VPS üzerinde kendi AI agent'ınızı oluşturmak üzerine olan kardeş rehber temelleri ortaya koyar.

Eğer istediğiniz bir terminal kodlama asistanı ise, bir VPS üzerinde kodlama AI agent'ı çalıştırmak Aider ve Goose konularını kapsar.

FAQ

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

Yetenekli varsayılan olan Claude Opus 4.8 (claude-opus-4-8) ile başlayın ve oradan ayarlama yapın. Claude Sonnet 5 (claude-sonnet-5) çoğu iş için daha ucuz ve daha hızlıdır, Claude Haiku 4.5 (claude-haiku-4-5) basit yüksek hacimli adımlar için en iyisidir ve Claude Fable 5 (claude-fable-5) en zor görevler için en yeteneklisidir. Yaygın bir yöntem, geçiş yapmak tek satırlık bir değişiklik olduğundan, rutin adımlar için daha ucuz bir model, zor kararlar için ise daha güçlü bir model kullanmaktır.

Agent'ın tamamını ben mi çalıştırıyorum, yoksa Anthropic mi?

Bu yaklaşıma bağlıdır. Claude API'sine karşı kendi döngünüzü yazıyorsanız veya Claude Agent SDK'yı kullanıyorsanız, agent tamamen sizin VPS'inizde çalışır ve yalnızca model çağrıları Anthropic'e gider. Yönetilen Agent'ları (Managed Agents) kullanıyorsanız, döngüyü Anthropic çalıştırır ve araçların yürütüldüğü sandbox'ı barındırır, böylece sistemin daha azı sunucunuzda bulunur. Kendi makinenizde çalışan bir agent için ilk ikisinden 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önderirsiniz ve etrafına agent döngüsünü yazarsınız veya döngüyü yönetmek için SDK'nın araç çalıştırıcısını kullanırsınız. Claude Agent SDK ise daha üst düzey bir kütüphanedir; Claude Code'un üzerine inşa edilmek üzere paketlenmiş halidir, tam bir döngü ve yerleşik dosya, kabuk ve arama araçları ile birlikte gelir. Her şeyi kendiniz tanımlamak istediğinizde API'yi, mekanizmayı kurmakla uğraşmadan yetenekli bir agent istediğinizde ise Agent SDK'yı kullanın.

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

Onu sunucu tarafında ve kodunuzun dışında tutun. Agent'ın çalıştığı hesap tarafından okunabilen bir dosyada saklayın, servise bir ortam değişkeni olarak yükleyin ve asla bir depoya (repository) commit etmeyin veya bir tarayıcıya maruz bırakmayın. Her Claude isteği sunucunuzdan yapıldığı için anahtarın kullanıcının cihazına ulaşmasına gerek yoktur; bu da sunucuda çalışan bir agent'ı, bir istemci uygulamasına gömülü olandan daha güvenli kılar.

Claude ile bir agent oluşturmak için bir modeli kendi sunucumda barındırmam gerekiyor mu?

Hayır. Claude ile model, API üzerinden çağırdığınız barındırılan bir hizmettir, bu nedenle bir GPU üzerinde çalıştırılacak bir şey yoktur. VPS'iniz agent döngüsünü, araçları ve verileri çalıştırır ve akıl yürütme Anthropic tarafında gerçekleşir. Bu, mütevazı bir sunucunun yetenekli bir agent çalıştırmasına olanak tanır. Bunun yerine tamamen yerel bir model istiyorsanız, bu durum kendi AI agent'ınızı oluşturmak üzerine olan yardımcı rehberde ele alınan kendi sunucunuzda barındırma yoludur.