Yapay zeka ajanları nasıl öğrenilir: Sıfırdan yol haritası

Altı aşamalı yol haritası

Yapay zeka ajanlarını sıfırdan öğrenmek için şu altı aşamayı sırasıyla takip edin: kavramlar, ilk döngünüz, araçlar, bellek, döngü tasarımı ve güvenlik. Her aşamada kendi ellerinizle inşa edeceğiniz bir uygulama bulunur. İlerideki aşamalara atlamak, insanların takılmasının en yaygın nedenidir; çünkü bir framework, tam olarak görmeniz gereken kısmı gizler.

Yapay zeka ajanı, araçları çağırmasına izin verilen bir dil modeli etrafındaki döngüdür. Bu cümle konunun tamamını özetler. Bundan sonraki her şey; döngünün içine nelerin girdiği, araçların nelere erişebileceği ve döngü hatalı çalıştığında nasıl durdurulacağı hakkındaki detaylardır. Döngüyü başka birine açıklayabiliyorsanız, konuyu öğrenmişsiniz demektir. Sadece framework isimlerini sayabiliyorsanız, öğrenmemişsinizdir.

Aşağıdaki plan, inşa ederek öğrendiğinizi varsayar. Bir aşamayı okuyun, küçük uygulamayı inşa edin, kasten bozun ve ardından bir sonrakine geçin. Sadece okuduğunuz bir aşama, tamamlamadığınız bir aşamadır.

1. aşamadan önce gerçekten neye ihtiyacınız var

Dürüst ön koşul listesi kısadır ve çoğu kurs sayfasının önerdiğinden daha az madde içerir.

• Elli satırlık bir betik yazabilecek düzeyde Python veya TypeScript okuyup yazabiliyor olmalısınız.
• Linux kabuğunda rahat olmalısınız: paket kurma, dosya düzenleme, günlük kaydı okuma gibi işlemleri yapabilmelisiniz.
• Barındırılan bir model için API anahtarına veya yerel bir modeli çalıştırabilecek bir makineye sahip olmalısınız.

Listenin tamamı budur. Makine öğrenmesi teorisine ihtiyacınız yok ve bir model eğitmiş olmanız gerekmiyor. Ajan çalışmalarının hiçbir aşaması gradyanlar veya eğitim verileriyle ilgili değildir. Bir grafik kartı yalnızca modeli kendiniz çalıştırmaya karar verirseniz önem taşır; bu, daha sonra bir VPS üzerinde Ollama barındırarak LLM'i kendi sunucunuzda çalıştırma rehberinden öğrenebileceğiniz ayrı bir beceridir.

İnsanların hafife aldığı kısım ise kabuk tarafıdır. Ajanlar; izinler, yollar, ortam değişkenleri ve sessizce sonlanan süreçler nedeniyle başarısız olur. Eğer PATH ile ilgili bir yığın izi (stack trace) veya bir dosya modu sizi terminali kapatmaya itiyorsa, önce bir hafta sonunuzu Linux temellerine ayırın. Bu, ileride size bir ay kazandıracaktır.

Aşama 1: Ajan nedir ve ne değildir

Tek bir API çağrısı ve döngü olmadan başlayın. Bir istem gönderin, yanıtı yazdırın ve yanıttaki token sayılarını inceleyin. Artık maliyet birimini ve gecikme birimini anlamış durumdasınız.

Ardından, tüm alandaki tek gerçek yeni fikir olan araç kullanımını öğrenin. Modele bir fonksiyonu; isim, açıklama ve girdileri için bir JSON (JavaScript object notation) şeması olarak tanımlarsınız. Model hiçbir şey çalıştırmaz. Bunun yerine yapılandırılmış bir istek ile yanıt verir: bu argümanlarla run_command çağrısını yap. Kodunuz fonksiyonu çalıştırır, çıktıyı bir mesaj olarak geri gönderir ve modele tekrar sorar. Model, metin okuyan ve metin yazan bir planlayıcıdır. Kodunuz ise elleri olan taraftır.

Bir sohbet botu, tek bir yanıttan sonra sona erer. Bir ajan ise model araç istemeyi bırakana kadar bu değişimi tekrarlar. Tüm fark bu tekrardan ibarettir ve hata modlarının farklı olmasının nedeni de budur. Bir sohbet botu bir kez yanlış cevap verir. Bir ajan ise kimse fark etmeden önce yanlış bir cevap üzerinde defalarca işlem yapar.

Aşama 2: döngüyü kendiniz yazın, bir kez

Bir framework ile başlamayın. İşin yapısını kavramak için yaklaşık otuz satırlık Python kodu yazın.

sudo apt update && sudo apt install -y python3-venv
python3 -m venv ~/agent
source ~/agent/bin/activate
pip install anthropic
export ANTHROPIC_API_KEY=your-key-here

import subprocess
import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "run_command",
    "description": "Run a read only shell command and return its output.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

messages = [{"role": "user", "content": "How much disk space is free here?"}]

while True:
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )
    if response.stop_reason != "tool_use":
        break
    messages.append({"role": "assistant", "content": response.content})
    results = []
    for block in response.content:
        if block.type == "tool_use":
            done = subprocess.run(
                block.input["command"], shell=True,
                capture_output=True, text=True, timeout=10,
            )
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": done.stdout or done.stderr,
            })
    messages.append({"role": "user", "content": results})

print(next(b.text for b in response.content if b.type == "text"))

Kodu python3 agent.py ile çalıştırın. Sağlıklı bir çalışma, dosya sistemlerinizi ve boş alanlarını listeleyen bir paragraf çıktısı verir; çünkü model df -h komutunu talep etmiş, kodunuz bunu çalıştırmış ve ikinci geçişte bu tabloyu bir cümleye dönüştürmüştür. Eğer hiçbir çıktı alınmıyorsa, döngü bir metin bloğu gelmeden önce sona ermiş demektir. Döngünün içine print(response.stop_reason) ekleyin ve değerlerin değişimini izleyin.

Şimdi sistemi kasten bozun. tool_use_id satırını silin ve oluşan hatayı inceleyin; çünkü eşleşen bir kimliğe sahip olmayan araç sonucu API tarafından reddedilir ve bu, yeni başlayanların yaptığı en yaygın hatadır. İki komut gerektiren bir soru sorun ve döngünün iki kez çalıştığını gözlemleyin. İmkansız bir şey sorun ve sistemin ya pes ettiğini ya da sonsuz döngüye girdiğini görün.

Bu örnekle ilgili bir uyarı: Model çıktısını shell=True ile doğrudan kabuğa aktarır. Bu, yeniden oluşturulabilir bir test makinesinde kabul edilebilir olsa da, başka herhangi bir ortamda yanlıştır. 6. Aşama bu sorunu çözer. Döngünün temelindeki kavramlar kendi yapay zeka temsilcinizi bir VPS üzerinde oluşturma başlığında daha ayrıntılı ele alınmıştır.

Aşama 3: ajanın halihazırda sahip olmadığı araçlar

run_command aracınız çalışıyor, ancak gerçek bir ajanın kutunun dışına erişebilen araçlara ihtiyacı vardır: bir bilet sistemi, bir veritabanı, bir depo. Her servis ve her ajan için özel bir sarmalayıcı yazmak ölçeklenebilir değildir.

Model Context Protocol (MCP), sektörün üzerinde uzlaştığı çözümdür. Bir MCP sunucusu, bir dizi aracı standart bir taşıma katmanı üzerinden dışa aktarır ve MCP uyumlu herhangi bir ajan, özel bir ara katman (glue code) olmadan bu araçları kullanabilir. Referans dosya sistemi sunucusu tek bir komuttan ibarettir:

npx -y @modelcontextprotocol/server-filesystem /home/you/projects

Bu komut Node kurulumu gerektirir ve dizin argümanı, sunucunun erişebileceği tek yoldur. Bu, güvenlik modelinin minyatür halidir: sınırı model değil, sunucu belirler. Bir istemciyi bu sunucuya yönlendirdiğinizde, ajanınız sizin yazmadığınız dosya okuma ve yazma yetenekleri kazanır. Bunları bir servis hesabı altında ve açıklanan taşıma seçenekleriyle düzgün bir şekilde çalıştırmak, yapay zeka kodlama ajanları için VPS üzerinde MCP sunucuları çalıştırma rehberinde ele alınmıştır.

Bu aşamanın dersi, araç tasarımının asıl iş olduğudur. Belirsiz bir açıklama, modelin tahmin yürütmesine neden olur. Kırk bin karakter döndüren bir araç, bağlam penceresini (context window) zehirler. Bir şeyleri silme yetkisine sahip bir araç, er ya da geç bir şeyleri silecektir.

Aşama 4: Bellek, yani çoğunlukla sadece dosyalar

Yeni başlayanlar bu noktada bir vektör veritabanına yönelir. Bunu yapmayın, en azından henüz değil.

Bir ajanın çağrılar arasında belleği yoktur. Tüm konuşmayı her seferinde yeniden gönderirsiniz; uzun bir oturumun her adımda kısa bir oturumdan daha maliyetli olmasının nedeni budur. Dolayısıyla bellek iki soruna ayrılır. Birincisi, şu anda bağlam penceresine (context window) sığan kısımdır; bunu özetleme yaparak, eski araç çıktılarını kırparak ve isteminizin sabit önekini önbelleğe alarak yönetirsiniz; böylece bunun için maliyetin sadece bir kısmını ödersiniz. İkincisi ise yeniden başlatma sonrasında varlığını koruyan kısımdır, yani depolama.

İkinci sorun için, ajanın okuyup yazabileceği düz bir markdown dosyası, neredeyse tüm ilk projelerde bir vektör veritabanından daha iyi sonuç verir. Ona tek bir dosya verin, formatı belirtin, başlamadan önce o dosyayı okumasını ve bir şey öğrendiğinde dosyayı güncellemesini söyleyin. Avantajların çoğunu elde edersiniz ve dosyayı açıp ajanınızın neye inandığını görebilirsiniz. Gömme (embedding) ve getirme (retrieval) yöntemlerine, notlar artık bağlam penceresine sığmadığında başvurun, öncesinde değil.

Aşama 5: döngü ürünün kendisidir

Artık izlediğiniz sürece çalışan bir aracı oluşturabiliyorsunuz. Aşama 5, aracı siz başında değilken de çalışır hale getirmektir.

Gözetimsiz bir aracın yalnız bırakılmasının güvenli olup olmadığını dört soru belirler. Aracı ne tetikliyor; böylece boş yere çalışmaz. Hangi sınırlar içinde faaliyet gösteriyor; böylece bir hata küçük kalır. Sonuç nasıl doğrulanıyor; çünkü kendi ödevini notlayan bir araç her zaman geçer not alır. Hangi bütçe onu durduruyor; token veya duvar saati süresi cinsinden. Bu dört unsuru kasıtlı olarak tasarlamak, döngü mühendisliği ve bu tanımın neleri kapsadığı bölümünde açıklanan disiplindir.

Alıştırma: 2. aşamadaki aracınızı alın, dört veya beş adım gerektiren bir görev verin ve katı bir yineleme sınırı ekleyin. Ardından sınırı kaldırın ve sınırsız bir döngünün token faturanıza ne yaptığını izleyin. Bunu küçük bir bütçeyle bir kez yapın ki, büyük bir bütçede yanlışlıkla asla yapmayasınız.

Aşama 6: güvenlik, gizli bilgiler ve maliyet

Bu aşama isteğe bağlı değildir; listenin sonunda yer almasının tek nedeni, çalışan bir sistem inşa etmeden riskin boyutunun hissedilememesidir.

Ajanı, root veya kendi kullanıcı hesabınızla değil, kendi yetkisiz (unprivileged) kullanıcısı ile çalıştırın. Böylece olası bir güvenlik ihlalinin etki alanı tüm makine yerine yalnızca bir dizinle sınırlı kalır. Kimlik bilgilerini modelin erişemeyeceği yerlerde tutun; çünkü bağlam penceresinde (context window) bulunan her veri, bir araç çağrısı aracılığıyla dışarı sızdırılabilir. Bunun çözümü, yapay zeka ajanlarınızdan gizli bilgileri uzak tutma bölümünde açıklandığı gibi, yardımcı bir araç arkasında kısa ömürlü tokenlar kullanmaktır. Harcama için kesin bir üst sınır belirleyin; çünkü denetimsiz bir döngü, başında kimse yokken her iterasyonda fatura üretir. Sistemi makul sınırlar içinde tutacak limitler ve toplu işleme yöntemleri 7/24 çalışan bir VPS üzerinde yapay zeka ajanı maliyet kontrolü bölümünde yer almaktadır.

Maliyet konusu somut bir rakamı hak ediyor. Temmuz 2026 itibarıyla Claude Opus 5, milyon girdi tokenı başına 5 dolar ve milyon çıktı tokenı başına 25 dolar faturalandırılmaktadır. Sürekli büyüyen bir konuşmayı tekrar tekrar gönderen konuşkan bir ajan, tek bir görevde birkaç yüz bin token harcayabilir. Prompt önbellekleme (prompt caching) ve rutin adımlar için daha küçük bir model kullanmak, bu aritmetiği herhangi bir prompt iyileştirmesinden çok daha fazla değiştirir.

Prompt enjeksiyonu konusu da burada ele alınmalıdır. Eğer ajanınız bir web sayfasını, bir hata takip sistemini veya bir gelen kutusunu okuyorsa, o metni yazan kişi aslında ajanınıza talimat veriyor demektir. Bunun savunması daha zekice bir sistem promptu değildir. Savunma, sınırlardır; çünkü bir depoyu silme yetkisi olmayan bir ajan, ikna edilerek de bir depoyu silemez.

Hangi müfredatı takip etmelisiniz?

Altı farklı kaynağı yarım yamalak incelemek yerine, tek bir müfredatı seçip tamamlayın. Microsoft ai-agents-for-beginners deposu, Temmuz 2026 itibarıyla 70,000 yıldızı aşmış, on sekiz dersten oluşan ve yukarıdaki aşamalarla tam uyumlu, en kapsamlı ücretsiz kaynaktır. Trend olan ajan depolarının özetleri, neyin mevcut olduğunu görmek için faydalıdır ancak bir müfredat olarak kullanıldıklarında verimleri düşüktür; çünkü yıldız sayısına göre sıralanmış bir liste, öğretim sırasına göre değil popülariteye göre düzenlenmiştir.

Pratik yapmak için gerçek bir proje arıyorsanız, kodlama ajanı ilk hedef olarak en uygunudur: geri bildirim anlıktır, araçlar bellidir ve hataları geri almak kolaydır. Bir VPS üzerinde kodlama yapay zeka ajanı çalıştırma süreci uçtan uca açıklamaktadır. Sıfırdan inşa etmek yerine çalışan sistemleri incelemeyi tercih ederseniz, en iyi self-hosted yapay zeka ajanları karşılaştırması, çeşitli projelerin aynı döngüsel süreci nasıl farklı şekillerde çözdüğünü göstermektedir.

Bu süreç ne kadar sürer?

Programlama bilgisine sahip kişiler için 1. ve 2. aşamalar bir akşamlık iştir. 3. aşama bir hafta sonu sürer; bu sürenin büyük kısmı protokollerden ziyade araç tanımlamalarına harcanır. 4. ve 5. aşamalar birkaç haftalık gerçek kullanım gerektirir, çünkü temsilcinizin neleri unuttuğunu ancak unutmasını izleyerek öğrenebilirsiniz. 6. aşama ise hiçbir zaman tam olarak bitmez; çünkü temsilciye kazandırdığınız her yeni yetenek, bu aşamayı yeniden başlatır.

Düzenli olarak akşamlarını ayıran çoğu kişi, iki ay içinde çalışan, sınırları belirlenmiş ve kullanışlı bir temsilci elde eder. Bir yıl sürenler ise genellikle inşa etmek yerine sürekli okumaya devam edenlerdir.

FAQ

Bir yapay zeka ajanı oluşturmak için makine öğrenmesi bilmem gerekiyor mu?

Hayır. Bir ajan oluşturmak, bir modeli API üzerinden çağırmak ve onun araç isteklerini gerçek fonksiyonlara yönlendirmekten ibarettir; bu da standart uygulama programlamadır. Eğitim, gradyanlar veya veri setleri ile hiçbir işiniz olmaz. Ajanınızın çalışıp çalışmayacağını belirleyen beceriler; araçlar için şema tasarımı, hata yönetimi ve Linux izinleridir. Makine öğrenmesi teorisi, yalnızca bir modeli ince ayar (fine-tune) aşamasına getirdiğinizde önem kazanır; bu ise farklı ön koşulları olan bambaşka bir iştir.

LangChain veya CrewAI gibi bir çerçeve ile mi başlamalıyım?

Önce ham bir döngü yazın, ardından bir çerçeveye geçin. Bir çerçeve, 2. aşamadaki otuz satırlık kodu bir yapılandırma nesnesi ile değiştirir; bu, neyin yerini aldığını bildiğinizde kullanışlıdır, ancak öncesinde kafa karıştırıcıdır. Ajanınız hatalı davrandığında, mesaj listesi ve araç sonuçları üzerinde doğrudan mantık yürütmeniz gerekir; bunları daha önce hiç görmediyseniz bu çok daha zordur. Kendi yazdığınız bir döngüden sonra, bir çerçeve mekanizmayı gizlemek yerine size zaman kazandıracaktır.

Yapay zeka ajanlarını öğrenmenin maliyeti nedir?

Sınır koyduğunuz takdirde, çoğu insanın beklediğinden daha düşüktür. Barındırılan bir API anahtarı ve küçük bir VPS, bu altı aşamadaki her şeyi karşılar. Asıl risk saatlik ücret değil, siz uyurken her iterasyonda fatura çıkaran sınırsız bir döngüdür. İlk günden API hesabınıza katı bir harcama limiti koyun, yazdığınız her döngüye bir iterasyon sınırı ekleyin ve rutin adımlar için daha ucuz bir model kullanın. Modeli yerel olarak çalıştırmak, token faturasını ortadan kaldırır ancak bunun yerine donanım gereksinimi getirir.

Yapay zeka ajanı ile sohbet botu arasındaki fark nedir?

Bir sohbet botu tek bir yanıt verir. Bir ajan ise bir döngüyü tekrarlar: model bir araç ister, kodunuz bunu çalıştırır, sonuç geri döner ve model bir sonraki adımda ne yapacağına karar verir. Bu tekrarlama, bir ajanın birkaç adımlı bir görevi tamamlamasını sağlar; aynı zamanda ajanların sohbet botlarında olmayan sınırlara ihtiyaç duymasının nedeni de budur. Bir sohbet botundan gelen yanlış bir yanıt kötü bir paragraftır. Bir ajandan gelen yanlış bir yanıt ise kötü bir paragrafın yanı sıra, o yanıtla ilgili yaptığı her türlü işlemdir.