6. ünite / 10 · 4 saat

Araç kullanımı ve ajan döngüsü

Modele araç tanımlamak, düşün → araç çağır → gözle döngüsü, adım sınırı, hata ve yeniden deneme, ne zaman ajan kurulmamalı.

Bu ünitenin sonunda

Bir aracı ad, açıklama ve giriş şemasıyla tanımlamak
Araç çağrısı ve araç sonucu mesajlarının döngüdeki yerini açıklamak
Adım sınırı ve hata yönetimiyle güvenli bir döngü kurmak
Bir işin ajan mı yoksa sabit bir iş akışı mı gerektirdiğine karar vermek

Ders notları

Model kendi başına hesap makinesi çalıştıramaz, veritabanına bakamaz, takvim açamaz. Araç kullanımı (tool use) ile ona yapabileceği işleri tanımlarız: her aracın bir adı, ne işe yaradığını anlatan bir açıklaması ve argümanlarının JSON şeması vardır. Model gerekirse bir araç çağrısı döndürür; aracı senin kodun çalıştırır ve sonucu modele geri verir.

Döngü

İsteği araç tanımlarıyla gönder.
Cevabın durma nedeni tool_use ise içindeki araç çağrılarını çalıştır.
Sonuçları tool_result blokları olarak tek bir kullanıcı mesajında geri gönder; hata olduysa is_error ile bildir, sessizce atlama.
Model bir son cevap verene kadar tekrarla.

düşün → araç çağır → gözle → … → son cevap (en çok N adım)

Bu döngüyü elle yazabilir ya da Anthropic SDK'daki araç çalıştırıcı (tool runner) yardımcısına bırakabilirsin; ikinci kod örneği bunu gösterir.

Sınırlar

Ajan yanlış bir plana takılıp aynı aracı tekrar tekrar çağırabilir. Adım sınırı döngüyü keser ve o ana kadarki bulguları dürüstçe bildirir. Geçici bir araç hatası bir kez yeniden denenir; ikinci kez de başarısızsa ajan tahmin yürütmek yerine işi bitiremediğini söyler. Yazma, silme, ödeme gibi geri alınamaz araçlar için insan onayı istenir.

Ajan mı, iş akışı mı?

Adımları önceden bilinen bir iş (soruyu sınıflandır, RAG ile cevapla, biçimlendir) sabit bir iş akışıyla daha ucuz, hızlı ve öngörülebilir çalışır. Ajan, adımların önceden yazılamadığı açık uçlu işlerde değer katar. Simülasyondaki politika bir model değil önceden yazılmış bir plandır; ama araçlar gerçekten çalışır ve argümanlar önceki gözlemlerden çıkarılır.

Simülasyon

Öğretim modeli: bu sayfadaki simülasyonlar gerçek bir dil modeli değildir. Küçük, deterministik, tarayıcıda çalışan modellerdir; kavramı göstermek için yazıldılar. Site hiçbir dış LLM servisine istek göndermez.

Ajan döngüsü görselleştirici: düşün → araç çağır → gözle

Üç görevden birini seç ve ajanı adım adım çalıştır. Her adımda plan (düşünce), araç çağrısı ve argümanları, aracın döndürdüğü gözlem zaman çizelgesinde görünür. Azami adım sayısını düşür ya da bir aracı bozarak ajanın hatayla nasıl başa çıktığını gör. Politika deterministiktir; araçlar (hesap makinesi, not araması, birim çevirici, takvim) gerçekten çalışır.

Kendin dene

Ajan görselleştiricide "Proje teslimi" görevini adım adım çalıştır ve her gözlemin bir sonraki argümanı nasıl belirlediğini izle. Azami adımı 2'ye indir: ajan nerede durdu ve ne bildirdi? Sonra "hesapla" aracını boz ve "3S LiPo alt sınırı" görevinde yeniden denemenin bir kez yapıldığını doğrula.

Kod

Bunları kendi bilgisayarında çalıştır. Anahtar ANTHROPIC_API_KEY ortam değişkeninden okunur; koda asla yazma.

Python: araç kullanan ajan döngüsü (Anthropic SDK)

import json
import anthropic

client = anthropic.Anthropic()  # anahtar ANTHROPIC_API_KEY ortam değişkeninden okunur
MODEL = "claude-sonnet-5-5"
MAX_STEPS = 8  # sonsuz döngüye karşı adım sınırı

TOOLS = [
    {
        "name": "search_notes",
        "description": "Ders notlarında arama yapar, en ilgili üç paragrafı kaynak kimliğiyle döndürür.",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
            "additionalProperties": False,
        },
    },
    {
        "name": "calculate",
        "description": "Dört işlem ve parantez içeren bir aritmetik ifadeyi hesaplar.",
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {"expression": {"type": "string"}},
            "required": ["expression"],
            "additionalProperties": False,
        },
    },
]

def run_tool(name: str, args: dict) -> str:
    if name == "search_notes":
        return json.dumps(search_notes(args["query"]))  # kendi arama fonksiyonun (5. ünite)
    if name == "calculate":
        return str(safe_eval(args["expression"]))  # eval() değil, güvenli ayrıştırıcı
    raise ValueError(f"unknown tool: {name}")

def ask(question: str) -> str:
    messages = [{"role": "user", "content": question}]
    for step in range(MAX_STEPS):
        response = client.messages.create(
            model=MODEL, max_tokens=16000, tools=TOOLS, messages=messages,
            # tool_choice varsayılan olarak "auto"; bu modelde "any"/"tool" zorlaması 400 döner
        )
        if response.stop_reason != "tool_use":
            return next((b.text for b in response.content if b.type == "text"), "")
        messages.append({"role": "assistant", "content": response.content})
        results = []
        for block in response.content:
            if block.type != "tool_use":
                continue
            try:
                results.append({"type": "tool_result", "tool_use_id": block.id,
                                "content": run_tool(block.name, block.input)})
            except Exception as err:  # hatayı modele gözlem olarak geri ver
                results.append({"type": "tool_result", "tool_use_id": block.id,
                                "content": f"error: {err}", "is_error": True})
        messages.append({"role": "user", "content": results})  # tüm sonuçlar tek mesajda
    return "Adım sınırına ulaşıldı; görev yarım kaldı."

Python: araç koşucusu (beta) ve insan onayı

import anthropic
from anthropic import beta_tool

client = anthropic.Anthropic()

@beta_tool
def send_email(to: str, subject: str, body: str) -> str:
    """E-posta gönderir. Geri alınamaz bir işlem.

    Args:
        to: Alıcının e-posta adresi.
        subject: Konu satırı.
        body: Mesaj metni.
    """
    # Geri alınamaz araçlarda insan onayı: araç fonksiyonunun içinde sor
    answer = input(f"Gönderilsin mi -> {to} / {subject}? [y/N] ")
    if answer.strip().lower() != "y":
        return "Kullanıcı reddetti; e-posta gönderilmedi."
    return mailer.send(to, subject, body)  # kendi posta istemcin

runner = client.beta.messages.tool_runner(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    tools=[send_email],
    messages=[{"role": "user", "content": "Ekibe proje teslim tarihini hatırlatan kısa bir e-posta yaz ve gönder."}],
)
for message in runner:  # her tur bir mesaj; döngüyü SDK yürütür
    print(message.stop_reason)

Sık yapılan hatalar

Araç açıklamasını tek kelimeyle geçmek: model aracı ne zaman kullanacağını açıklamadan anlar.
Araç hatasını modele bildirmeden yutmak: model başarılı sandığı bir sonuca dayanarak cevap uydurur.
Adım sınırı koymamak: döngü sonsuza kadar sürebilir ve fatura büyür.
Adımları belli bir iş için ajan kurmak: sabit bir iş akışı daha ucuz ve güvenilirdir.

Yazılım mühendisliği bağlantısı

Her araç bir API uç noktası gibi tasarlanır: dar yetki, doğrulanan girdi, anlamlı hata.

Araçları modelden bağımsız birim testleriyle sına; model yalnız onları çağıran bir istemcidir.
Her adımı (düşünce, araç, argüman, sonuç, süre) iz kaydına yaz; ajanın yanlış kararı bu izden ayıklanır.

Kendini sına

Model bir araç çağrısı döndürdüğünde aracı kim çalıştırır?
Bir araç hata verdiğinde modele ne gönderilmeli?
Adım sınırına ulaşıldığında iyi bir ajan ne yapar?
Hangi iş için sabit bir iş akışı ajandan daha uygundur?