---
title: "Yapay zekâ ajanı nasıl yapılır? Yüz satırla başlayan, eval ile biten sıra"
url: https://komunite.com.tr/rehber/yapay-zeka-ajani-nasil-yapilir
updated: 2026-09-05
---

# Yapay zekâ ajanı nasıl yapılır? Yüz satırla başlayan, eval ile biten sıra

Ajan kurmanın işe yarayan sırası: önce döngü, sonra araç, bağlam, dış bağlantı, ölçüm ve sınır. Framework en sonda gelir, en başta değil.

- Kategori: Yapay zekâ pratiği
- Yayımlandı: 2026-09-05
- Yazar: [Fatih Güner](https://komunite.com.tr/fatih-guner.md)

Dayanak: Bu rehber Agentic AI Bootcamp'in kurulum sırasından (döngü, tool, bağlam ve skills, MCP, eval, containment) ve katılımcıların ilk ajanını kurarken takıldığı yerlerden yazıldı. Framework kıyaslaması, hız ölçümü veya başarı oranı içermez.

Yapay zekâ ajanı nasıl yapılır sorusuna herkes aynı yerden başlıyor: bir framework seçerek. Yanlış başlangıç.

Framework sana döngüyü saklıyor. Döngüyü görmeden kurduğun ajan çalıştığında neden çalıştığını, bozulduğunda neresinin bozulduğunu bilmiyorsun.

Bu yazı işe yarayan sırayı anlatıyor. Döngüyle başlıyor, ölçümle bitiyor. Framework ortada bir yerde, en başta değil.

## Yapay zekâ ajanı nasıl yapılır: önce döngü, yüz satırı geçmez

Bir ajanın çekirdeği beş adım. Modele soruyorsun. Model bir araç çağırmak istediğini söylüyor. Aracı sen çalıştırıyorsun. Sonucu bağlama ekliyorsun. Tekrar soruyorsun.

Bu döngü yüz satırı geçmiyor ve ilk gün kendi elinle ya da bir coding agent'a yazdırarak kurmalısın. Programda eğitmen tam bunu yapıyor: spec söyleniyor, kod doğuyor, davranış test ediliyor.

Bu adımı atlayan, ikinci haftada framework'ün belgelerinde kayboluyor. Atlamayan, belgeyi açtığında ne aradığını biliyor.

## Sonra araç, çünkü araç bir dil işi

Döngü çalışınca ajana ilk aracı veriyorsun. Burada ilk yanlış, mevcut bir API'yi olduğu gibi araç diye sunmak.

Araç API'nin kopyası değil, modelin arayüzü. Adı ve açıklaması bir mikro-prompt: model o açıklamaya bakıp aracı ne zaman kullanacağına karar veriyor. "Veri getir" diye bir araç, modelin her şeyi bununla getirmeye çalışması demek.

Doğru sıra spec'ten kod'a: aracın ne yaptığını, hangi durumda çağrılacağını ve neyi asla yapmayacağını doğal dilde yazıyorsun. Coding agent koda çeviriyor. Sen davranışı test ediyorsun. Kod okuyabiliyorsan şemayı elle sıkılaştırmak derin görev.

Üç ayrıntı sonucu belirliyor. Parametreler belirsizliği azaltmalı. Hata mesajı modelin okuyup düzeltebileceği biçimde olmalı. Riskli aksiyonun önünde bir onay eşiği durmalı.

## Coding agent'a nasıl tarif edilir

Kod yazmayan için kilit beceri burada: aracı ve döngüyü bir coding agent'a tarif etmek.

Tarif dört parçadan oluşuyor. Amaç: bu araç ne işe yarıyor, tek cümle. Girdi: hangi bilgiyle çağrılıyor, hangi alan zorunlu. Çıktı: ne döndürüyor, hata olunca ne söylüyor. Sınır: neyi asla yapmıyor, hangi durumda insana soruyor.

Bu dört parçayı düz Türkçe yazıyorsun; coding agent koda çeviriyor. Sonra sen kodu okumak yerine davranışı test ediyorsun: doğru girdiyle çağır, eksik girdiyle çağır, saçma girdiyle çağır. Üçünde de ne olduğuna bak.

Tarif net olmayınca kod da net olmuyor. Programda mentörlerin en çok düzelttiği şey kod değil, tarifin belirsiz kalan cümlesi.

## Bağlam bir bütçe, beceri bir dosya

Ajan çalışıp araç çağırdıkça bağlam penceresi doluyor. Uzun görevde ajan kendi geçmişinde boğuluyor ve kalite düşüyor.

Üç önlem: geçmişi sıkıştırmak, bilgiyi ihtiyaç anında getirmek, kalıcı bilgiyi dosyaya yazmak. Üçü de basit ve üçü de ilk günde kurulmalı.

Dosya fikrinin bir adım ötesi beceri dosyası. Kendi alanından bir işi nasıl yaptığını yazıyorsun: adımlar, dikkat edilecekler, yasaklar. Ajan görev sırasında o dosyayı okuyup senin gibi davranıyor. Kod yazmayanın en güçlü sahası burası; buradaki para birimi kod değil, alan bilgisi.

## Şimdi harness, çünkü ikinci ajan yorucu

İlk ajanı çıplak kurmak öğretici. İkincisini de öyle kurmak yorucu; döngü, araç, bağlam ve sandbox her projede yeniden yazılıyor.

Harness bu dördünü görünür bir sözleşmeye çeviren katman. Ajan bir düz fonksiyon oluyor; modele, araca ve beceriye küçük kancalarla erişiyor. Sabah kurduğun iki araç bir klasöre, beceri dosyan başka bir klasöre geçiyor ve taşımayı coding agent yapıyor. Sen farkı onaylıyorsun.

Framework'ü bu noktada seçmenin sebebi basit: artık neyi sakladığını biliyorsun. Riskli araca onay eşiği koyduğunda onay akışını canlı görüyorsun, kara kutuya güvenmiyorsun.

## Dış dünya: MCP

Ajan kendi araçlarıyla bir yere kadar gidiyor. Bir noktada dışarıdaki bir sisteme bağlanması gerekiyor: takvim, depo, veritabanı, bir başkasının servisi.

Her bağlantıyı ayrı yazmak eskiden zorunluydu. Model Context Protocol bu yükü ortak bir protokole indiriyor: bir sunucu araçlarını standart biçimde ilan ediyor, ajanın istemcisi bağlanıp kullanıyor. Hazır bir sunucuyu bağlamak on beş dakikalık iş; kendi sunucunu yazmak hızlı bitirenlerin görevi. [Protokolün üç rolü ve çözdüğü N çarpı M sorunu](/rehber/mcp-nedir) ayrı bir yazıda duruyor.

Sıra önemli. MCP'yi döngüden ve araç tasarımından önce öğrenen, protokolü anlamış ama ajanı anlamamış oluyor. Bağlantı en sonda gelir, çünkü neye bağlanacağını ancak ajan çalışınca biliyorsun.

## Ölçüm olmadan "çalışıyor" bir his

Ajan ilk kez doğru cevabı verince insan durmak istiyor. Tam burada durmamak gerekiyor.

On gerçek vaka yaz. Ajanın karşılaşacağı tipik istekler, birkaç zor durum, bir iki tuzak. Ajanı üzerinde koştur ve sonuca değil ize bak: doğru aracı mı çağırdı, doğru argümanla mı, gereksiz adım attı mı, ne zaman durdu.

Bu set senin gerçek ölçütün. Araç açıklamasını değiştirdiğinde, modeli güncellediğinde, beceri dosyasına satır eklediğinde aynı seti koşturuyor ve neyin bozulduğunu görüyorsun. Set yoksa her değişiklik bir kumar.

Yirmi satırlık bir set yeter. Mükemmel set beklerken ölçümsüz kalanlar, ilk müşteri şikâyetiyle ölçmeye başlıyor.

Seti tutmanın bir yan faydası daha var: model sürümü değiştiğinde aynı seti bir saatte koşturup yeni sürümün işini bozup bozmadığını görüyorsun. Set yoksa yeni sürüm bir sürpriz; sürprizi de genelde kullanıcı buluyor.

Ajan üretimde tutarsızlaşınca da bakacağın yer bu set. [Tutarsızlığın nereden geldiğini ayıklamak](/rehber/ajan-uretimde-tutarsiz) kendi başına bir iş.

![Şema: on vakanın dört ölçütteki izi ve dördünde birden düşen tek vaka.](/rehber/yapay-zeka-ajani-nasil-yapilir-figur.svg)

## Sınır: güven katmanı en son değil

Ajan çalışınca ilk refleks ona daha çok yetki vermek. Tam tersi gerekiyor.

Programın son bloğunda eğitmen kendi ajanına canlı bir saldırı yapıyor. Ajan güvenilmeyen bir içerik okuyor; içeriğin içindeki talimat onu özel veriyi dışarı göndermeye ikna ediyor. Salon o anı görüyor. Sen saldırı yapmıyorsun, bu bir demo; ama mekanizmayı bir kez görünce unutmuyorsun.

Tehlike üç şeyin bir araya gelmesinden doğuyor: özel veriye erişim, güvenilmeyen içerik, dışarı iletişim. Bu üçünü aynı ajanda birleştirmemek ilk kural.

Üç containment kuralı: en az yetki, riskli aksiyonda onay kapısı, sandbox. Bunlar ileri seviye değil; ilk ajanın kurulduğu gün konuşulan konular.

## Nerede biter

Dürüst sınır. Tek günde makinede çalışan, araçlu, beceri dosyalı, en az bir dış bağlantısı olan ve on vakalık bir ölçümden geçmiş kişisel bir ajan çıkıyor.

Üretimde, gerçek kullanıcı yüküyle, gece gündüz çalışan bir sistem çıkmıyor. Oraya giden yol aynı sıranın tekrarı: daha çok vaka, daha sıkı araç, daha dar yetki. Sıçrama yok, tekrar var.

## Kim için

Kendi işinde tekrar eden ama karar isteyen bir süreci olan herkes için. Müşteri taleplerini sınıflandırmak, raporu bağlı veriden kurmak, gelen belgeyi okuyup sıradaki adımı seçmek.

Adımları belli ve her seferinde aynı olan iş için değil. O iş için workflow yeter; ajan pahalı ve öngörülemez bir fazlalık olur. Bu ayrımı [Agentic AI nedir](/rehber/agentic-ai-nedir) yazısı açıyor.

## Bu hafta kurulacak ajan

Framework seçme. Araç listesi yapma.

Kendi işinden bir süreç seç ve sırayla git: döngüyü kur, tek bir araç ver, beceri dosyanı yaz, bir dış bağlantı ekle, on vaka yaz ve koştur. Her adımda çalışan bir parça olsun; sonraki adıma geçmeden onu göster.

Gösterecek kimse yoksa "çalışıyor" kararını yine sen veriyorsun. [Komünite üyeliğinde](/uyelik) ajanını çalıştıran başka üyeler o kararı seninle paylaşıyor.

Hafta sonunda elinde bir demo değil, ölçülmüş bir ajan olacak. Ölçülmüş ajan, çalışmaya devam eden ajan.

Sıra basit. Zor olan sıraya uymak.

## Sık sorulanlar

### Yapay zekâ ajanı yapmak için kod bilmek gerekiyor mu?

Ön koşul değil. Aracı ve beceri dosyasını doğal dilde tarif ediyorsun, coding agent onu koda çeviriyor, davranışı sen test ediyorsun. Kod okuyabilen daha derine iniyor; okuyamayan aynı makineyi dört parça olarak kuruyor.

### Hangi framework ile başlamalıyım?

Hiçbiriyle. İlk ajanı çıplak döngüyle kur: modele sor, araç çağrısını çalıştır, sonucu bağlama ekle, tekrar sor. Yüz satırı geçmiyor. Framework, döngüyü anladıktan sonra seçilen bir kolaylık; anlamadan seçilen bir kara kutu.

### Ajanımın doğru çalıştığını nasıl anlarım?

Ölçerek. On gerçek vaka yaz, ajanı üzerinde koştur ve iz düzeyinde bak: doğru aracı mı çağırdı, doğru argümanla mı, gereksiz adım attı mı. Bu set olmadan 'çalışıyor' bir his, ölçüm değil.

### Ajanın güvenliği için ilk günde ne yapmalıyım?

Üç kural: en az yetki, riskli aksiyonda onay kapısı, sandbox. Özel veri, güvenilmeyen içerik ve dışarı iletişim bir araya geldiğinde ajan veri sızdırmaya ikna edilebilir; bu üçlüyü baştan ayır.