Claude ile ilk yapay zeka temsilcinizi nasıl oluşturursunuz: İlk API çağrısından otonom sisteme

Anthropic'teki kodun %90'ı Claude ajanları tarafından yazılıyor. Mühendislerin bir sohbet penceresine yazmasıyla değil. Ekip uyurken otonom döngüler çalıştıran, araçları çağıran ve kod gönderen ajanlar tarafından.

Taze AI alfa'sı için Substack'imi takip edin:

movez.substack.com

İşte tam kurulum. Adım adım. İlk API çağrısından, herhangi bir göreve yönlendirebileceğiniz çalışan bir ajana kadar.

Bu makale şunları kapsayacak:

1 - insanların kurduğu "ajanların" çoğunun neden ajan olmadığı

2 - her çalışan ajanın ihtiyaç duyduğu 5 parça

3 - her bir parçanın Claude ile kod kullanarak nasıl oluşturulacağı

4 - ajanları daha göndermeden öldüren hatalar

Bunu kaydedin. Aşağıdaki her kod bloğu çalışır.

01. Çoğu "AI ajanı" ajan değildir

Sayamayacağım kadar çok ajan kurdum ve bozdum. Bütün gece token yakıp hiçbir şey üretmediklerini izledim. Aynı dosyayı 30 kez yeniden yazdıklarını izledim. Testi silerek kendi testlerini geçtiklerini izledim.

Her başarısızlık bana aynı dersi öğretti: sorun model değil. Etrafındaki mimari. Bu rehber, öğrendiğim her şeyin size verebileceğim en kısa yola sıkıştırılmış hali.

İşte çoğu insanın "AI ajanı" dediğinde kurduğu şey:

1while True:
2    user_input = input("> ")
3    response = call_claude(user_input)
4    print(response)

Bu bir sohbet robotu. Sizi bekler. Ne derseniz onu yapar. Oturumlar arasında her şeyi unutur. Sekmeyi kapatınca durur.

Bir ajan, siz başında oturmadan bir hedefe doğru çalışan bir sistemdir. Ne yapılması gerektiğini keşfeder, bir plan yapar, uygular, sonucu kontrol eder ve henüz bitmediyse tekrar dener. Siz yönü belirlersiniz. Ajan işi yapar.

"Claude Code, birkaç ay içinde sıfırdan 400 milyon dolarlık gelire ulaştı. Bir hackathon projesi olarak başladı. Hâlâ yalnızca genel API'yi kullanıyor." -

Boris Cherny, Claude Code Başkanı

Şu anda erişiminiz olan aynı API. Aynı modeller. Fark, modelin etrafındaki mimaride.

02. Gerçek bir ajanın 5 parçası

Çalışan her ajan - Claude Code, Devin, Codex veya kendi kurduğunuz herhangi bir şey - beş parçadan oluşur. Birini kaçırırsanız bozulur.

03. API katmanı

Her şey burada başlar. Claude'u çağırırsınız, Claude yanıt verir. Ancak onu çağırma şekliniz, bir sohbet robotu mu yoksa bir ajan mı elde edeceğinizi belirler.

Üç şey önemlidir: sistem prompt'u, yapılandırılmış çıktı ve sıcaklık (temperature).

Sistem prompt'u bir selamlama değildir. Ajanınızın kullanım kılavuzudur. Her kural, kısıtlama ve davranış buraya gider. Onsuz Claude ne istediğinizi tahmin eder. Onunla Claude sizin belirttiğinizi takip eder.

1import anthropic
2
3client = anthropic.Anthropic()
4
5response = client.messages.create(
6    model="claude-sonnet-4-6",
7    max_tokens=4096,
8    system="""Sen bir kod inceleme ajanısın.
9
10Kurallar:
11- Yorum yapmadan önce tüm farkı (diff) oku
12- Yalnızca gerçek hataları işaretle, stil tercihlerini değil
13- Yanlış bir şey yoksa "LGTM" de ve dur
14- Zihinsel olarak test etmediğin değişiklikleri asla önerme
15- Çıktı formatı: {file, line, issue, fix} şeklinde JSON dizisi""",
16    messages=[{"role": "user", "content": diff_content}]
17)

Yapılandırılmış çıktı, ajanınızın yanıtını makine tarafından okunabilir hale getirir. Claude serbest metin döndürürse, kodunuz onu ayrıştırmak zorunda kalır. Claude JSON döndürürse, kodunuz onu doğrudan kullanabilir.

1# Claude'a tam şekli söyleyerek JSON çıktısını zorla
2system = """Yalnızca geçerli JSON döndür. İşaretleme yok. Açıklama yok.
3Şema:
4{
5  "status": "pass" | "fail",
6  "issues": [{"file": str, "line": int, "issue": str}],
7  "summary": str
8}"""

Sıcaklık (Temperature). Deterministik ajanlar için 0'a ayarlayın. Yaratıcı işler için 0.3-0.5'e ayarlayın. Varsayılan (1.0), bir ajanda neredeyse hiç istemediğiniz rastgelelik ekler.

04. Araçlar

Araçları olmayan bir model akıl yürütebilir ancak harekete geçemez. Size hangi dosyayı düzenleyeceğinizi söyleyebilir ancak düzenleyemez. Bir sorguyu tanımlayabilir ancak çalıştıramaz.

Claude'un araç kullanımı, modelin çağırabileceği işlevleri tanımlamanızı sağlar. İşlevi tanımlarsınız. Claude ne zaman çağıracağına karar verir. Siz çalıştırır ve sonucu döndürürsünüz. Claude, akıl yürütmeye devam etmek için sonucu kullanır.

1tools = [{
2    "name": "run_sql",
3    "description": "Veritabanına karşı salt okunur bir SQL sorgusu çalıştır",
4    "input_schema": {
5        "type": "object",
6        "properties": {
7            "query": {
8                "type": "string",
9                "description": "Çalıştırılacak SQL SELECT sorgusu"
10            }
11        },
12        "required": ["query"]
13    }
14},
15{
16    "name": "write_file",
17    "description": "Diske bir dosyaya içerik yaz",
18    "input_schema": {
19        "type": "object",
20        "properties": {
21            "path": {"type": "string"},
22            "content": {"type": "string"}
23        },
24        "required": ["path", "content"]
25    }
26}]

Araç açıklaması düşündüğünüzden daha önemlidir. Claude, aracı ne zaman ve nasıl kullanacağına karar vermek için onu okur. Belirsiz bir açıklama, yanlış çağrılar anlamına gelir. Kesin bir açıklama, doğru çağrılar anlamına gelir.

3-5 araçla başlayın. Dosya oku, dosya yaz, komut çalıştır, ara ve kullanım durumunuz için bir alana özgü araç. Bu, ajan görevlerinin %90'ını kapsar.

05. Döngü

Bir betiği ajana dönüştüren kısım budur. Döngü olmadan kodunuz Claude'u bir kez çağırır ve durur. Döngüyle kodunuz Claude'u çağırır, sonucu kontrol eder ve iş bitene kadar tekrar çağırır.

Üç bileşen:

• Doğrulayıcı (Verifier). Çıktının iyi olup olmadığını kontrol eden bir şey. Bir test paketi, bir tip denetleyicisi, bir lint aracı, katı kriterlere sahip ikinci bir Claude çağrısı. Bu olmadan ajan kendisiyle tekrar tekrar aynı fikirde olur.
• Durum (State). Ne olduğuna dair bir kayıt. Ne işe yaradı, ne başarısız oldu, sırada ne denenmeli. Durum olmadan ajan her geçişte aynı hatayı yapar.
• Durdurma koşulu (Stop condition). Hedefe ulaşıldı veya "N denemeden sonra dur ve raporla" diyen bir sabit sınır. Bu olmadan döngü sonsuza kadar çalışır ve hesabınızı tüketir.

1import json
2from pathlib import Path
3
4def run_agent(task: str, max_attempts: int = 5):
5    state = {"task": task, "attempts": [], "done": False}
6
7    for i in range(max_attempts):
8        # Durumdan bağlam oluştur
9        context = build_prompt(state)
10
11        # Claude'u araçlarla çağır
12        result = call_claude(context, tools)
13
14        # Herhangi bir araç çağrısını yürüt
15        output = execute_tools(result)
16
17        # Sonucu doğrula
18        check = verify(output)
19
20        # Durumu güncelle
21        state["attempts"].append({
22            "attempt": i + 1,
23            "action": result.summary,
24            "passed": check.passed,
25            "reason": check.reason
26        })
27
28        if check.passed:
29            state["done"] = True
30            break
31
32    # Bir sonraki çalıştırma için durumu kaydet
33    Path("state.json").write_text(json.dumps(state, indent=2))
34    return state

Bu, tam iskelet. Her üretim ajanı bu modelin bir varyasyonudur. Ayrıntılar değişir. Şekil değişmez.

06. Bellek

Bellek olmadan, her oturum sıfırdan başlar. Ajan proje yapınızı yeniden keşfeder. Kurallarınızı yeniden öğrenir. Dün yaptığı hataları yeniden yapar.

Claude ajanları üç katman bellek kullanır:

CLAUDE.md, projenizin kökünde bir işaretleme dosyasıdır. Claude Code, her oturumun başında onu otomatik olarak okur. Kurallarınız, yığınınız, kurallarınız. Bir kez yazın, sonsuza kadar okuyun.

1# CLAUDE.md
2
3## Proje
4Görev yönetimi API'si. Python 3.12, FastAPI, PostgreSQL.
5
6## Kurallar
7- Tüm yanıtlar: {data, error, meta} şeması
8- Her yeni uç nokta için test gerekli
9- Commit mesajları: type(scope): description
10- Günlükleme için print() kullanma. structlog kullan.
11
12## Bilinen sorunlar
13- Kimlik doğrulama ara yazılımı Authorization değil x-auth-token bekler
14- Test paketinin tamamı 45 saniye sürer. Yineleme için --filter kullan.

Beceriler (Skills) tüm iş akışlarını yakalar. Sadece prompt'lar değil - tam şekil: girdi formatı, adımlar, çıktı formatı, doğrulama kuralları. İlk çalıştırma 20 dakika sürer. Tekrar oynatma 30 saniye sürer.

Öğrenmeler dosyası (Learnings file), hataların sürekli güncellenen bir günlüğüdür. Ajan her oturumdan sonra ona yazar. Bir sonraki oturum onu okur. Hatalar, yazılana kadar tekrarlanır. Sonra dururlar.

1# learnings.md
2
3- Ödeme API'si, idempotency anahtarını gövdede değil başlıkta bekler
4- PostgreSQL NOTIFY, bağlantı havuzunda açık LISTEN gerektirir
5- Hız sınırlayıcı, IP başına değil anahtar başına sayar. Testlerin benzersiz anahtarlara ihtiyacı vardır.

07. Doğrulama kapısı (Verification gate)

Kapı, inşa edilmesi en zor ve atlanması en kolay kısımdır. Çoğu insan onu atlar. Bu yüzden çoğu ajan üretimde bozulur.

Doğrulama kapısı, ajanın çalışmasını ajanın kendini değerlendirmesi olmadan kontrol eden bir şeydir. Kodu yazan model, kendi ödevini notlandırmada çok cömerttir. İkinci bir kontrole ihtiyacınız var.

İşe yarayan üç model:

1. Otomatik testler. Ajan kodu yazar. Test paketi çalışır. Testler başarısız olursa, ajan hata çıktısını alır ve tekrar dener. Claude Code dahili olarak böyle çalışır.

1def verify(output):
2    # Test paketini çalıştır
3    result = subprocess.run(
4        ["pytest", "tests/", "-x", "--tb=short"],
5        capture_output=True, text=True
6    )
7    return {
8        "passed": result.returncode == 0,
9        "reason": result.stdout if result.returncode != 0 else "tüm testler geçti"
10    }

2. Tip denetleyicisi / lint aracı. Her değişiklikten sonra mypy, ruff veya tsc --noEmit çalıştırın. Tek bir test yazmadan tüm hata kategorilerini yakalar.

3. İkinci modelin değerlendirici olarak kullanılması. Yalnızca sorunları arayan katı bir sistem prompt'una sahip ayrı bir Claude çağrısı kullanın. Yazar hızlı ve ucuzdur. Değerlendirici yavaş ve katıdır. Bu ayrım, kalitenin çoğunu oluşturur.

1# Değerlendirici prompt'u - yapıcıdan ayrı
2reviewer_system = """Sen katı bir kod incelemecisisin.
3Tek işin sorunları bulmak.
4
5Kontrol et:
6- Kod, belirtimle eşleşiyor mu?
7- Yakalanmamış uç durumlar var mı?
8- Tüm testler gerçekten doğru şeyi test ediyor mu?
9
10Her şey doğruysa, şu şekilde yanıtla: {"passed": true}
11Yanlış bir şey varsa, şu şekilde yanıtla: {"passed": false, "issues": [...]}
12
13İyileştirme önerme. Yalnızca gerçek hataları işaretle."""

Yazar hızlı ve ucuzdur. Değerlendirici yavaş ve katıdır. Bu ayrım, kalitenin çoğunu oluşturur.

08. Hepsini bir araya getirmek

İşte bir GitHub sorunu URL'sini alan, sorunu okuyan, kodu yazan, testleri çalıştıran ve bir PR açan eksiksiz bir ajan. Beş parça birlikte çalışıyor.

1import anthropic, subprocess, json
2from pathlib import Path
3
4client = anthropic.Anthropic()
5CLAUDE_MD = Path("CLAUDE.md").read_text()
6LEARNINGS = Path("learnings.md").read_text()
7
8SYSTEM = f"""Sen bir kodlama ajanısın.
9Sorunu oku. Düzeltmeyi yaz. Testleri çalıştır.
10
11Proje bağlamı:
12{CLAUDE_MD}
13
14Bilinen sorunlar:
15{LEARNINGS}
16
17Kurallar:
18- Bir şeyi değiştirmeden önce tüm kod tabanını oku
19- Her değişiklik için test yaz
20- Testler başarısız olursa, testleri değil kodu düzelt
21- Tüm testler geçtiğinde dur"""
22
23TOOLS = [
24    read_file_tool,
25    write_file_tool,
26    run_command_tool,
27    search_codebase_tool,
28]
29
30def run(issue_text, max_attempts=5):
31    messages = [{"role": "user", "content": issue_text}]
32
33    for attempt in range(max_attempts):
34        # Claude'u çağır
35        response = client.messages.create(
36            model="claude-sonnet-4-6",
37            max_tokens=8192,
38            system=SYSTEM,
39            tools=TOOLS,
40            messages=messages
41        )
42
43        # Araç çağrılarını yürüt
44        messages = handle_tool_use(response, messages)
45
46        # Doğrula: testleri çalıştır
47        test_result = subprocess.run(
48            ["pytest", "-x", "--tb=short"],
49            capture_output=True, text=True
50        )
51
52        if test_result.returncode == 0:
53            print(f"{attempt + 1} denemede tamamlandı")
54            return True
55
56        # Başarısızlığı döngüye geri besle
57        messages.append({
58            "role": "user",
59            "content": f"Testler başarısız oldu:\n{test_result.stdout}\nDüzelt ve tekrar dene."
60        })
61
62    return False

Bu, çalışan bir ajandır. Sistem prompt'u ve CLAUDE.md ile API katmanı. Dosya işlemleri için araçlar. Yeniden denemeli bir döngü. learnings.md'den bellek. Pytest aracılığıyla bir doğrulama kapısı.

50 satırın altında. Claude Code'un dahili olarak kullandığı aynı mimari.

**

09. Her ajanı bozan 5 hata

1. Doğrulama kapısı yok. Ajan kendi ödevini notlandırır. Kod yazar, "iyi görünüyor" der ve devam eder. Çıktı doğru görünür ve üretimde bozulur.
2. Durdurma koşulu yok. Döngü, API faturanız 200 dolar olana kadar çalışır. Sabit bir sınır olmadan ajan sonsuza kadar yeniden dener, aynı dosyayı 40 kez yeniden yazar. Her zaman max_attempts ayarlayın. Her zaman.
3. Durum dosyası yok. 1. denemede ve 50. denemede aynı hata. Ajan neyi zaten denediğini bilmez. Aynı bozuk düzeltmeyi arka arkaya üç kez önerir çünkü hiçbir şey başarısızlığı kaydetmez.
4. Çok fazla araç. Claude'a 20 araç verirsiniz ve yanlış olanı seçer. 5 net aracı olan bir model, 20 örtüşen aracı olan bir modelden daha iyi seçimler yapar. Küçük başlayın. Araçları yalnızca ajan bir duvara çarptığında ekleyin.
5. Belirsiz sistem prompt'u. "İyi bir kodlama asistanı ol" size genel çıktı verir. "Tüm yanıtlar geçerli JSON olmalı, her değişiklik için test gerekli, /src dışındaki dosyaları asla değiştirme" size davranan bir ajan verir.

Sonuç:

Çalışan bir ajan daha iyi bir prompt değildir. Bir sistemdir: API + araçlar + döngü + bellek + doğrulama kapısı. Beş parça. Birini kaçırırsanız bozulur.

Çoğu insan bunu okuyacak, kaydedecek ve Claude'u bir sohbet robotu olarak kullanmaya devam edecek. Her seferinde bir soru yapıştıracak ve yanıtı elle kod tabanlarına kopyalayacak.

Döngüyü kuranlar, uyurken iş gönderecek. Aynı model. Aynı API. Aynı fiyat. Farklı mimari.

Yukarıdaki kod bloklarının tümü çalışır. Kopyalayın. Çalıştırın. Kullanım durumunuza göre değiştirin.

Bu hafta bir ajan kurun. Onu her gün yaptığınız bir göreve yönlendirin. Çalışmasına izin verin.