Aracı Koşum Mühendisliği Rehberi: Modeller ile Eylem Arasındaki Boşluğu Kapatmak

Aynı büyük dil modelini (LLM) iki kez çalıştırdığınızı, ancak her birine tamamen farklı iki koşum verdiğinizi hayal edin. İlk çalışma karmaşık bir yeniden düzenleme görevini temizce tamamlar. İkinci çalışma durur ve tamamen başarısız olur. Model hiç değişmedi, ancak modelin etrafındaki iskele değişti.

Kısacası, aracı koşum mühendisliği bir LLM’in güvenilir biçimde hareket etmesini sağlayan çevresel mantığı, dosya sistemi erişimini, belleği ve kuralları inşa etme pratiğidir. 

Bu aracı koşum mühendisliği öğreticisinde, Akıl Yürüt ve Eyle (ReAct) döngüsü, araçlar ve kancalarla minimal bir Python kurulumu oluşturmayı öğreteceğim. Makinenizde Python 3, pip kurulu olmalı ve LLM API çağrıları yapmaya temel düzeyde aşina olmanız gerekir.

Aracı Koşum Mühendisliği Nedir?

Aracı koşum mühendisliği, büyük bir dil modelini saran altyapıyı, yapılandırmaları ve yürütme mantığını inşa etme pratiğidir; onu statik bir LLM metin üreticisinden özerk bir yapay zeka aracına dönüştürür

Aracı koşum mühendisliği, statik bir metin üreticisini özerk bir çalışana dönüştüren yapısal yapılandırmadır. 

Temel denklem basittir: ajan = model + koşum. Koşum; sistem istemlerini, araç tanımlarını, dosya sistemi çalışma alanlarını, orkestrasyon mantığını ve gözlemlenebilirlik kancalarını içerir.

Addy Osmani bu kavramı Nisan 2026’daki O’Reilly yazısında yapay zeka iş akışları üzerine kodlaştırdı. Koşumu, modelin kendisi olmayan her kod parçası, yapılandırma ve yürütme mantığı olarak tanımladı: sağlayıcının API’sinden ayrı, geliştirici olarak sizin yüzey alanınız. 

Makine öğrenimi iş akışları kurmaya ilk başladığımda, bir ajan bir Python bağımlılığını hayal ettiğinde her seferinde suçu modele atardım. Acı yoldan öğrendim ki, başarısızlıkların çoğu yapılandırma kaynaklıdır. 

Aynı model sürümü, daha iyi bir koşumla, kötü bir koşuma sahip halinden ölçülebilir şekilde daha iyi performans gösterir.

Yapay zeka mühendisliği merdiveni

Yapay zeka geliştirmeyi farklı kontrol katmanlarına ayırabiliriz. 

Koşum mühendisliği bu hiyerarşinin tam ortasında yer alır.

• İstem mühendisliği anlık metin talimatlarını belirler.
•  Bağlam mühendisliği isteme aktardığınız birebir veritabanı kayıtlarını veya API şemalarını yönetir. 
• Koşum mühendisliği, ajanın bir pandas betiğini fiilen nasıl çalıştırdığını veya yerel bir CSV’yi nasıl okuduğunu belirler. 

Ratcheting: her hata bir kurala dönüşür

Aracı koşum mühendisliğinin tanımlayıcı zihniyeti, mandal etkisidir. 

Bir ajan hata yaptığında, o hatanın bir daha tekrarlanmaması için bir düzeltme mühendisliği yaparsınız. İyi bir koşum, sıkıştırılmış deneme-yanılmadır.

Ajanın hataları tekrarlamasına izin vermek yerine, AGENTS.md dosyanıza bir satır eklersiniz, yeni bir kanca yazarsınız veya bir araç açıklamasını sıkılaştırırsınız. 

Refleks olarak yeni bir modele uzanmazsınız; bunun yerine, belirli başarısızlıkları ve onlara karşı nasıl sağlamlaştırdığınızı izlemenizi sağlayan bir külliyat oluşturursunuz.

Bir Yapay Zeka Aracı Koşumunun Temel Bileşenleri

Bir yapay zeka aracı koşumunun temel bileşenleri, modelin çalışmasını sağlayan dosya sistemi, araçlar, bellek, kancalar ve bağlam yönetim sistemleridir. 

Bu parçalar, izole API çağrılarını sürekli bir geri bildirim döngüsüne dönüştürmek için birlikte çalışır. Koda başlamadan önce size net bir harita vermek istiyorum.

Dosya sistemi ve Git: kalıcı durum

Bir model yalnızca sınırlı bağlam penceresinin içindeki bilgiyi işleyebilir. Bir dosya sistemi, verileri okumak, ara sonuçları yazmak ve oturumlar arasında koordinasyon kurmak için stabil bir çalışma alanı sağlar.

Git sürüm kontrolü eklemek gerekli bir emniyet ağı sağlar. Ajan ilerlemeyi takip edebilir, farklı hiperparametrelerle deneyler için dallanabilir ve bozuk kodu otomatik olarak geri alabilir. 

Araçlar: ajana eller vermek

ReAct döngüsü, akıl yürütme, bir araç çağrısı üzerinden eyleme geçme ve sonucu gözlemleme döngüsünde çalışır. Araç açıklamaları, model ile ortam arasındaki doğrudan arayüzü oluşturur. Belirsiz açıklamalar belirsiz davranış üretir.

Bash, çok amaçlı harika bir araçtır. Her olası eylem için önceden belirli bir Python fonksiyonu yazmak yerine, Bash ajanın ihtiyaç duyduğu tam komutları anında oluşturmasına olanak tanır. Bu komutları sistem hasarını önlemek için dikkatle sandbox’lamanız gerekir.

Bellek: AGENTS.md ve bilgi enjeksiyonu

Ajanınızın yerel teamülleri anlaması için projeye özgü belleğe ihtiyacı vardır. AGENTS.md dosyası, depo kökünde yer alan ve her turda sistem istemine giren düz bir markdown belgesidir. Teknoloji yığınınızı, biçimlendirme kurallarınızı ve yasaklı eylemleri tanımlar.

Bu dosyayı 60 satırın altında tutun. Bunu kapsamlı bir stil rehberi değil, bir pilot kontrol listesi olarak ele alın. Daha derin örnekler için eksiksiz bir AGENTS.md öğreticisi okuyabilirsiniz. Ayrıca kesim-sonrası bilgi için Model Context Protocol (MCP) araçlarını değerlendirmelisiniz.

Kancalar: yaptırım katmanı

Kancalar belirli yaşam döngüsü noktalarında çalışan küçük betiklerdir. 

Bir araç çağrısından önce, bir dosya düzenlemesinden sonra veya bir Git commit’inden önce bir kanca çalıştırabilirsiniz. Gelişmiş kanca kalıpları için şu rehbere göz atın: Claude Code Hooks.

Kancalar için temel tasarım ilkesi şudur: başarı sessizdir, başarısızlıklar ise detaylıdır. Başarılı bir tür denetimi sıfır çıktı üretir. 

Bir başarısızlık, tam hata metnini kendi kendini düzeltme için ajan döngüsüne geri enjekte eder.

Bağlam sıkıştırma: bağlam çürümesine karşı savaş

Bağlam çürümesi, uzun konuşma geçmişleri bağlam penceresini doldurdukça talimatlara uyma kalitesi bozulduğunda meydana gelir. Sağlam bir yapay zeka ajan iskelesi bunu aktif olarak yönetmelidir. Bu sınırlamaları anlamak için bağlam penceresi hakkında daha fazlasını okuyun.

Eski mesajları özetleyerek bağlamı azaltabilirsiniz. Büyük araç çıktıları disk’e boşaltılabilir ve istemde yalnızca kısa bir referans tutulabilir. 

Son olarak, belirteç yoğun alt görevleri, kendi taze bağlamına sahip bir alt ajana izole edebilirsiniz.

Python ile Minimal Bir Aracı Koşumu Oluşturma

Bir yapay zeka aracı koşumu inşa etmek, ReAct döngüsünü, araçları ve kancaları birbirine bağlayan Python orkestrasyon kodunu yazmayı içerir. 

Herhangi bir kod yazmadan önce ilişkiyi netleştirin: harness.py ajandır ve siz onu diğer betikler gibi python harness.py ile kendiniz başlatırsınız. 

Model, bu dosyayı asla görmeyen uzak bir API’dir; yalnızca betiğinizin gönderdiği sistem istemini, mesaj geçmişini ve araç şemalarını alır.

Bu bölümdeki her parça tek bir dosyanın, harness.py’nin bir bölümüdür ve ilk 4 bölüm onu baştan sona inşa eder. Son 2 bölüm (kancalar ve sıkıştırma) yükseltme yapar ve döngüye Python ulaşır ulaşmaz yürütme başladığı için, bu bölümlerin fonksiyon tanımları döngünün üzerinde yer almalıdır; her bölüm kodunun tam olarak nereye ekleneceğini belirtir.

Hesap kurulumu ve proje yapısı

Bunu kurmak için seçtiğiniz sağlayıcıda bir geliştirici hesabına ihtiyacınız var. Standart tüketici abonelikleri (ChatGPT Plus veya Claude Pro gibi) API erişimi sağlamaz.

1. Anthropic/OpenAI kurulumu: Sağlayıcının geliştirici konsolunda kayıt olun ve kullanım başına ödeme faturalandırma profilini ayarlayın. Bir API anahtarı oluşturun ve yerel ortamınıza ANTHROPIC_API_KEY (veya OPENAI_API_KEY) olarak aktarın.
2. Yerel alternatif: API maliyetlerinden tamamen kaçınmak isterseniz, Ollama’yı yerelde çalıştırabilirsiniz. Ollama, herhangi bir API anahtarı olmadan sorgulayabileceğiniz yerel bir uç nokta sunar.

Bu örnekte Anthropic kullanacağız, bu nedenle pip install anthropic komutuyla Anthropic Python paketini kurduğunuzdan emin olun.  

Ardından proje iskeletini oluşturun. Her dosyayı en başta adlandırmak önemlidir: döngümüz başlangıçta AGENTS.md’yi okuyacak, bu yüzden döngü çalışmadan önce bu dosya mevcut olmalıdır.

agent-harness/
├── AGENTS.md        # Project memory (we write this first)
├── harness.py       # The ReAct loop, tools, and hooks
└── workspace/       # The only directory the agent may touch

workspace/ dizini ajanın sandbox’ıdır. Ajanın okuduğu, yazdığı veya yürüttüğü her şey bunun içinde olur; asla proje kökünüzde değil.

AGENTS.md yazmak ve sistem istemine enjekte etmek

AGENTS.md’yi döngüden önce yazarız çünkü döngü ona bağlıdır. 

Dosyayı proje kökünüzde oluşturun ve özgül yığın ayrıntılarınızı ile mimari sınırlarınızı dahil edin:

# Project Context
Stack: Python 3.11, Pytest
Workspace: All commands run inside the workspace/ directory.

# Rules
1. Never use rm -rf. Use standard rm with specific file names.
2. Never write tests inside the main application file.
3. When you finish the task, reply with a plain-text summary and no tool call.

Döngümüz "model bir araç talep etmeden yanıtladı" durumunu görev-tamamlandı sinyali olarak kabul edecek, bu yüzden modele tamamlamayı nasıl işaret edeceğini açıkça söylüyoruz. 

Kendi döngü mekaniğinize referans veren kurallar, koşum mühendisliğinin anahtarıdır. Bellek dosyası ve orkestrasyon kodu birlikte tasarlanır.

Şimdi harness.py’ye, bu dosyayı sistem istemi olarak oluşturarak ve çalışma alanını hazırlayarak başlayın:

import subprocess
from pathlib import Path

import anthropic

client = anthropic.Anthropic()

WORKSPACE = Path("workspace")
WORKSPACE.mkdir(exist_ok=True)

# Project memory: AGENTS.md lands in the system prompt on every turn
system_prompt = Path("AGENTS.md").read_text()

SDK her API çağrısında system_prompt’u gönderdiği için, AGENTS.md’deki kurallar her adımda yeniden enjekte edilir. Model, konuşma ortasında yazılmış talimatları unuttuğu gibi bunları "unutamaz".

Araçları tanımlama: döngüye eller vermek

İki araç tanımlıyoruz: genel amaçlı yürütme için run_bash ve dosya oluşturmak için write_file. 

İkinci araç, Bash heredoc’larıyla dosya yazabildiği için gereksiz görünebilir, ancak özel bir write_file post-edit kancamızın daha sonra yakalanabileceği temiz bir düzenleme olayı sağlar. 

Bu tür koşum tasarım kararları, daima neyi gözlemlemek ve uygulamak istediğinizle ilgilidir.

Araç açıklamaları arayüzdür ve kaliteleri doğrudan ajan davranışını kontrol eder:

• Belirsiz: "Bash çalıştırır." Ajan bunu her şey için kullanır; çok satırlı Python dosyalarını kırılgan kaçışlarla heredoc üzerinden yazmak dahil.
• Özgül: "workspace/ dizini içinde bir bash komutu çalıştırın. Dosyaları listelemek, betikleri ve testleri çalıştırmak için kullanın. Python dosyaları oluşturmak için kullanmayın; bunun yerine write_file kullanın." Ajan, ekstra isteme gerek kalmadan işi doğru araca yönlendirir.

harness.py dosyamızda devam ederek, şimdi bir sonraki satırda araç şemalarını tanımlayabiliriz:

TOOLS = [
    {
        "name": "run_bash",
        "description": (
            "Run a bash command inside the workspace/ directory and return "
            "its stdout, stderr, and exit code. Use it to list files, run "
            "scripts, and run tests. Do not use it to create Python files; "
            "use write_file instead."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "The bash command to run."}
            },
            "required": ["command"],
        },
    },
    {
        "name": "write_file",
        "description": (
            "Create or overwrite a file inside the workspace/ directory. "
            "Provide a path relative to workspace/ and the full file content."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Path relative to workspace/."},
                "content": {"type": "string", "description": "Full file content."},
            },
            "required": ["path", "content"],
        },
    },
]

Bir sonraki blok, bu komutları yürütecek gerçek Python fonksiyonlarını tanımlar. 

Şu yerleşik güvenlik özelliklerine dikkat edin: takılı kalan bir komutun koşumu kilitleyememesi için sert zaman aşımı, ajanın başarıyı başarısızlıktan ayırabilmesi için her sonuçta çıkış kodu, ve write_file()’ın sandbox’tan kaçmaması için yol denetimi.

def run_bash(command: str) -> str:
    result = subprocess.run(
        command,
        shell=True,
        capture_output=True,
        text=True,
        cwd=WORKSPACE,
        timeout=60,
    )
    output = (result.stdout + result.stderr).strip()
    return f"exit code: {result.returncode}\n{output or '(no output)'}"


def write_file(path: str, content: str) -> str:
    target = (WORKSPACE / path).resolve()
    if WORKSPACE.resolve() not in target.parents:
        return "Error: path escapes the workspace/ directory."
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text(content)
    return f"Wrote {len(content)} characters to {path}."


TOOL_EXECUTORS = {"run_bash": run_bash, "write_file": write_file}

or '(no output)' geri dönüşü kozmetik değildir. 

touch data.csv gibi bir komut sessizce başarılı olur ve boş bir dize döndürmek modele gözlemleyecek hiçbir şey vermez. 

Sessizlik için bile ajana açık bir sinyal verin.

ReAct ajan döngüsü

Koşumumuzun özü, yineleme sınırı olan standart bir Python for döngüsüdür. 

Her geçiş API’yi çağırır, modelin bir araç isteyip istemediğini kontrol eder, istenen her aracı yürütür ve sonuçları tek bir mesaj olarak geri besler. 

Bu blok, Python ona ulaştığı anda yürütmeye başladığı için harness.py’nin en altında yer alır.

	messages = [
	    {
	        "role": "user",
	        "content": "Create a fizzbuzz.py script in the workspace, "
	                   "then run it to verify the output.",
	    }
	]

	MAX_STEPS = 15

	for step in range(MAX_STEPS):
	    print(f"--- Iteration {step + 1} ---")

	    response = client.messages.create(
	        model="claude-sonnet-5",
	        max_tokens=2000,
	        system=system_prompt,
	        messages=messages,
	        tools=TOOLS,
	    )

	    # Append the model's turn to the history
	    messages.append({"role": "assistant", "content": response.content})

	    # Stop condition: the model answered without requesting a tool
	    if response.stop_reason != "tool_use":
	        final_text = "".join(b.text for b in response.content if b.type == "text")
	        print(f"Task complete: {final_text}")
	        break

	    # Execute EVERY tool call in this turn, collecting the results
	    tool_results = []
	    for block in response.content:
	        if block.type != "tool_use":
	            continue
	        print(f"Agent calling {block.name}: {block.input}")
	        output = TOOL_EXECUTORS[block.name](**block.input)
	        tool_results.append(
	            {"type": "tool_result", "tool_use_id": block.id, "content": output}
	        )

	    # All tool results for one assistant turn go back in ONE user message
	    messages.append({"role": "user", "content": tool_results})
	else:
	    print("Stopped: hit the maximum iteration cap without finishing.")

Bu döngüde iki ayrıntı gerçek çöküşleri önler. 

İlk olarak, tek bir model turu birden fazla araç çağrısı içerebilir ve Anthropic API’si tüm sonuçlarının tek bir kullanıcı mesajı içinde geri gelmesini gerektirir. 

İkincisi, for/else yapısı, ajan yineleme sınırına ulaştığında raporlar; böylece tıkanmış bir çalışma sessizce bitmek yerine yüksek sesle başarısız olur.

Bu açık yapı, modelin düşünmeyi tam olarak nerede bıraktığını, komutu çalıştırmak için Python’un nerede devraldığını ve çıktının döngüye nasıl geri beslendiğini görmenizi sağlar.

Bir düzenleme sonrası kancası ekleme

Kancalar, daha büyük yapısal sorunlara dönüşmeden önce hataları yakalar. 

Koşumumuzda, bir kanca tamamlanmış bir araç çağrısını inceleyen ve araç sonucuna eklenecek fazladan metin döndüren bir fonksiyondur. 

Başarı boş dize döndürür; başarısızlık ayrıntılı bir rapor döndürür.

Bu fonksiyonu, ReAct döngüsünün üstüne, araç yürütücülerinin yanına harness.py’ye ekleyin. Python döngüye ulaştığı anda çalıştırmaya başladığından, döngünün çağırdığı her şey önceden tanımlanmış olmalıdır.

def post_edit_hook(tool_name: str, tool_input: dict) -> str:
    """Run pytest after any edit to a Python file. Silent on success."""
    edited_python = (
        tool_name == "write_file" and tool_input.get("path", "").endswith(".py")
    )
    if not edited_python:
        return ""

    tests = subprocess.run(
        ["pytest", "--tb=short", "-q"],
        capture_output=True,
        text=True,
        cwd=WORKSPACE,
        timeout=120,
    )
    # Exit code 5 means "no tests collected", which is fine for our purposes
    if tests.returncode in (0, 5):
        return ""
    return f"\n\n[HOOK] pytest failed after this edit:\n{tests.stdout}"

Bunu döngüye bağlamak, araç yürütme bloğu içinde tek satırlık bir değişikliktir:

output = TOOL_EXECUTORS[block.name](**block.input)
output += post_edit_hook(block.name, block.input)  # hooks run after every tool call

Kanca olmadan, ajan bozuk bir dosya yazar, Wrote 412 characters to fizzbuzz.py görür ve kendinden emin şekilde devam eder. 

Kancayla birlikte, aynı araç sonucu tam pytest traceback’ini taşır. Bir sonraki yinelemede, ajan hatayı okur ve hiçbir ek istem olmadan hatayı kendi başına düzeltir.

Temel bağlam sıkıştırma

messages listenizin uzunluğunu izleyerek ve çok uzadığında en eski turları özetleyerek bağlam çürümesine karşı koyun. 

Bir tuzak var: geçmişi keyfi bir noktadan kesemezsiniz; çünkü bir asistan tool_use bloğu ve onunla eşleşen tool_result mesajı birlikte kalmalıdır. Bir çifti bölmek anında API hatası üretir.

Sıkıştırma fonksiyonumuz, kesme noktasını güvenli bir sınıra oturana kadar ileri taşır. Bunu harness.py’nin üstünde inşa edin:

COMPACTION_THRESHOLD = 20
KEEP_RECENT = 6


def is_tool_result(message: dict) -> bool:
    return (
        message["role"] == "user"
        and isinstance(message["content"], list)
        and any(
            isinstance(b, dict) and b.get("type") == "tool_result"
            for b in message["content"]
        )
    )


def compact(messages: list) -> list:
    if len(messages) <= COMPACTION_THRESHOLD:
        return messages

    # Never orphan a tool_result from its tool_use: slide the cut forward
    cut = len(messages) - KEEP_RECENT
    while cut < len(messages) and is_tool_result(messages[cut]):
        cut += 1

    old, recent = messages[1:cut], messages[cut:]
    transcript = "\n".join(f"{m['role']}: {str(m['content'])[:500]}" for m in old)

    summary = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=500,
        messages=[{
            "role": "user",
            "content": "Summarize this agent transcript. Preserve the task, "
                       "decisions made, files created, and any unresolved "
                       f"errors:\n\n{transcript}",
        }],
    )

    return [
        messages[0],  # always keep the original task verbatim
        {
            "role": "user",
            "content": f"[Earlier progress, summarized by the harness]\n"
                       f"{summary.content[0].text}",
        },
        *recent,
    ]

API çağrısından önce, ReAct döngüsünün başına bir satır ekleyin:

messages = compact(messages)

Özet için daha küçük ve ucuz bir model kullanıyoruz; çünkü sıkıştırma sık çalışır ve hıza ihtiyaç duyar. 

Ayrıca özetin onu koruyacağına güvenmek yerine orijinal görev mesajını birebir tutuyoruz.

Koşum artık tamamlandı. 

Devam etmeden önce, harness.py’nizin yukarıdan aşağıya şu sırayla okunduğunu kontrol edin:

1. İçe aktarımlar, client, WORKSPACE ve system_prompt
2. TOOLS şema listesi
3. Yürütücüler: run_bash(), write_file() ve TOOL_EXECUTORS
4. Kanca: post_edit_hook()
5. Sıkıştırma kodu: COMPACTION_THRESHOLD, KEEP_RECENT, is_tool_result() ve compact()
6. Her zaman en sonda ReAct döngüsü

Kanca ve sıkıştırma bölümlerini eklediğimiz için, son API döngüsünün nasıl görünmesi gerektiğine dair fikir vermek adına, işte tamamlanmış döngü:

messages = [
    {
        "role": "user",
        "content": "Create a fizzbuzz.py script in the workspace, "
                   "then run it to verify the output.",
    }
]

MAX_STEPS = 15

for step in range(MAX_STEPS):
    print(f"--- Iteration {step + 1} ---")

    # Compaction: summarize old turns before they rot the context
    messages = compact(messages)

    # The API call: model, memory, history, and tools travel together
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=2000,
        system=system_prompt,   # AGENTS.md text, re-injected every turn
        messages=messages,      # the full (possibly compacted) history
        tools=TOOLS,            # the schemas from the tools section
    )

    # Append the model's turn to the history
    messages.append({"role": "assistant", "content": response.content})

    # Stop condition: the model answered without requesting a tool
    if response.stop_reason != "tool_use":
        final_text = "".join(b.text for b in response.content if b.type == "text")
        print(f"Task complete: {final_text}")
        break

    # Execute EVERY tool call in this turn, collecting the results
    tool_results = []
    for block in response.content:
        if block.type != "tool_use":
            continue
        print(f"Agent calling {block.name}: {block.input}")
        output = TOOL_EXECUTORS[block.name](**block.input)
        output += post_edit_hook(block.name, block.input)  # hooks run after every tool call
        tool_results.append(
            {"type": "tool_result", "tool_use_id": block.id, "content": output}
        )

    # All tool results for one assistant turn go back in ONE user message
    messages.append({"role": "user", "content": tool_results})
else:
    print("Stopped: hit the maximum iteration cap without finishing.")

Şimdi aracı proje kökünden python harness.py ile çalıştırın.

Betik, görev listesindeki messages’dan görevi API’ye gönderir. 

Koşum işi yapar ve her yinelemenin terminalinizde yazdırıldığını görmelisiniz:

--- Iteration 1 ---
Agent calling write_file: {'path': 'fizzbuzz.py', 'content': 'def fizz(n):...'}
--- Iteration 2 ---
Agent calling run_bash: {'command': 'python fizzbuzz.py'}
--- Iteration 3 ---
Task complete: fizzbuzz.py is written and prints the correct sequence.

Program, model bir araç çağrısı olmadan yanıtladığında veya 15 yineleme sınırı tetiklendiğinde sona erer. 

Ajana farklı bir görev vermek için, başlangıçtaki messages listesinde content dizesini değiştirin; üretim koşumu bunun yerine input()’tan veya bir komut satırı argümanından okurdu.

Aracı Koşumunuzu İyileştirme: Mandal Etkisi İş Başında

Mandal etkisi, ajan hatalarını teşhis edip koşumunuzu bunları önleyecek şekilde güncellemenin sürekli sürecidir. 

Bir koşum, yalnızca gerçek dünyadaki uç durumlara maruz kalarak katı biçimde gelişir.

Gerçek bir rota optimizasyon projesine dayalı tam bir başarısızlık ve düzeltme döngüsü üzerinden yürüyelim. 

Ajansınızın, güncellenmiş sürüm yerine legacy_route_math adlı kullanımdan kaldırılmış dahili yönlendirme kütüphanesini içe aktarmaya devam ettiğini hayal edin. 

Ajan betiği yazar, testler başarısız olur ve kütüphaneyi değiştirmek yerine sözdizimini düzeltmeye çalışarak bir döngüde sıkışıp kalır.

Buradaki teşhis açıktır. 

Ajan yalnızca kütüphanenin kullanımdan kaldırıldığını bilmiyor. Bu, altta yatan sinir ağının bir başarısızlığı değil, eksik bir kuraldır.

Düzeltme 1 bellek katmanını günceller, AGENTS.md’ye şu tek kuralı ekleyin:

# Rules
1. Never use rm -rf. Use standard rm with specific file names.
2. Never write tests inside the main application file.
3. When you finish the task, reply with a plain-text summary and no tool call.
4. Do not import legacy_route_math; it is deprecated. Use routes_v2 instead.

Düzeltme 2 kalıcı bir yaptırım kancası ekler. 

Kurallar ajana tavsiyedir, kancalar ise komut. Bu düzeltme birkaç satırdır ve ReAct döngüsünden önce olmak kaydıyla post_edit_hook()’un yanına eklenebilir.

def deprecated_import_hook(tool_name: str, tool_input: dict) -> str:
    if tool_name != "write_file":
        return ""
    if "import legacy_route_math" in tool_input.get("content", ""):
        return (
            "\n\n[HOOK] Blocked pattern: legacy_route_math is deprecated. "
            "Rewrite this file using routes_v2 instead."
        )
    return ""

Bunu araç yürütme bloğunda pytest kancasının yanına kaydedin:

output += post_edit_hook(block.name, block.input)
output += deprecated_import_hook(block.name, block.input)

Her iki düzeltme de yerleştikten sonra transkriptteki kendi kendini düzeltme şöyle görünür. 

Ajan dosyayı yazar, kanca tetiklenir ve bir sonraki turda hiçbir insan müdahalesi olmadan içe aktarmayı düzeltir:

--- Iteration 3 ---
Agent calling write_file: {'path': 'optimizer.py', ...}
  [HOOK] Blocked pattern: legacy_route_math is deprecated...
--- Iteration 4 ---
Agent calling write_file: {'path': 'optimizer.py', ...}   # now imports routes_v2
--- Iteration 5 ---
Task complete: Rewrote optimizer.py using routes_v2 and verified the tests pass.

Bu önemlidir çünkü bağlam çürümesine geri bağlanır. Çok uzun oturumlarda bozulan bağlam, sonunda bellek kurallarını görmezden gelecektir. 

AGENTS.md kuralı hatayı çoğu zaman önler ve kural kaçırıldığında kanca hatanın hasara yol açmasını kesin olarak engeller. 

Teşhis ettiğiniz her başarısızlık size iki soru sordurmalıdır: hangi kural eksikti ve onu yine de yakalayacak hangi kontrol vardı?

Aracı Koşum Mühendisliği için En İyi Uygulamalar

Aracı koşum mühendisliği için en iyi uygulamalar, yapılandırmaları yalın tutmaya ve gelecekteki model yükseltmeleri için tasarım yapmaya odaklanır. 

Amaç, modeli boğmadan onu destekleyen bir iskele inşa etmektir. 

Çeşitli ajan yetenekleri ve mimarileri inşa ederken birkaç zor ders öğrendim.

AGENTS.md’yi kısa ve sahaya dayalı tutun

Bağlam dosyanız için en fazla 60 satırı hedefleyin. 

Her bir kural yaşadığınız gerçek, belgelenmiş bir başarısızlığa dayanmalıdır. Kural için olayı hatırlayamıyorsanız, silmeye değerdir.

Bu disiplin önemlidir çünkü AGENTS.md her turda ücretlendirilecektir. 

300 satırlık bir stil rehberi, her API çağrısında size belirteçlere mal olur ve önem arz eden kuralları seyreltir; zira modeller 80 muğlak kuraldan ziyade 10 keskin kurala çok daha iyi uyar. 

Bir tarih damgası eklemek, önerdiğim bir sonraki uygulamaya da yardımcı olabilir.

Eskimeye göre tasarlayın

Temel modeller yerel yeteneklerini geliştirdikçe koşumlar sürekli yeniden mimariye ihtiyaç duyar. 

Bileşenlerinizi kolayca sökebileceğiniz şekilde inşa edin.

Bu nedenle bu öğreticideki kanca deseni bilerek modülerdir. 

Her kanca ayrı bir fonksiyondur ve tek bir satırla eklenir. Kancayı kullanımdan kaldırırsanız, döngüde tek satır silersiniz. 

Döngüde başka hiçbir şey değişmez. 

Bunu, doğrulama mantığının doğrudan ReAct döngünüze dokunduğu ve eski bir denetimi kaldırmanın tüm orkestrasyon yolunu yeniden test etmek anlamına geldiği yaklaşımla karşılaştırın.

Bugün gerekli bir koltuk değneği gibi hissettiren şey, gelecek çeyrekte gereksiz ek yüke dönüşecektir. 

Yeni bir model çıktığında, eski başarısızlık vakalarınızı her kancayı tek tek devre dışı bırakarak yeniden çalıştırın ve artık hiçbir şeyi yakalamayan her kancayı silinme adayı olarak değerlendirin. 

Daha fazla mimari ipucu için Claude Code En İyi Uygulamalar’a göz atın.

Basit başlayın ve karmaşıklığı katman katman ekleyin

Bir dosya sistemi ve bir Bash aracıyla yalın bir ReAct döngüsü bile oldukça pratiktir. 

Ağır çerçevelerle önleyici olarak karmaşık bir grafik sistemi kurma dürtüsüne direnin. Mandal yalnızca tek yönde çalışır: gözlenen başarısızlıktan hedefli düzeltmeye. Spekülatif düzeltmeler bunu tersine çevirir.

Özel kancaları ancak onları haklı çıkaran belirli başarısızlığı gördükten sonra ekleyin. Temel sistemleri yapılandırmak hakkında daha fazlası için şu rehbere göz atın: LLM ajanları.

Ajanın yaptığı her şeyi kaydedin

Görmediğinizi mandallayamazsınız. 

Döngümüz zaten her araç çağrısını yazdırıyor ve bu asgari gözlemlenebilirliktir: bir çalışma başarısız olduğunda, yazdırılan transkript teşhis malzemenizdir.

Koşumunuz olgunlaştıkça, her oturumun tam mesaj geçmişini çalışmanın sonunda zaman damgalı bir JSON dosyasına yazın. 

Başarısız transkriptler regresyon paketiniz olur; her koşum değişikliğinden sonra, eski hatalı görevleri yeniden oynatın ve düzeltmenin hâlâ geçerli olduğunu doğrulayın. 

Bu, bir koşum mühendisinin test paketi eşdeğeridir ve gelişen bir koşumu, yalnızca değişen bir koşumdan ayırır.

Son Düşünceler

Aracı koşum mühendisliği, yapay zeka modellerini işe yarar işler yaptırmanın pratik gerçeğidir. 

Bugünün modellerinin teoride yapabildiği ile üretimde gerçekten gördükleriniz arasındaki boşluk büyük ölçüde bir koşum boşluğudur.

Bu disiplin belirli bir çerçeveyi öğrenmekle ilgili değildir. 

Kod tabanınız için doğru yapay zeka aracı koşumu, tamamen benzersiz başarısızlık geçmişiniz tarafından şekillenir ve mandal yöntemiyle kademeli olarak inşa edilir.

Bu kavramları pratiğe dökmeye hazır mısınız? 

DataCamp’in AI Agent Fundamentals beceri yoluna göz atarak üretime hazır sistemler kurmaya devam edebilirsiniz. Ayrıca daha uygulamalı kod örnekleri için Claude Agent SDK Öğreticisi’ni keşfedebilirsiniz. 

Ayrıca Yazılım Mühendisliği için Yapay Zeka beceri yoluna da bakmak isteyebilirsiniz.