Model araç çalıştırmaz, araç ister

Bu, ajan mühendisliğinin en önemli cümlesidir. Modele araçların tanımını verirsin: ad, açıklama ve parametre şeması. Model bir araca ihtiyaç duyarsa cevap olarak “şu aracı şu parametrelerle çağır” diye yapılandırılmış bir istek üretir. Aracı senin kodun çalıştırır ve sonucu modele geri verir.

kullanıcı ──► sen ──► API (araç tanımlarıyla)
                      │
               model: "su_an aracını {zaman_dilimi: Europe/Istanbul} ile çağır"   (stop_reason = tool_use)
                      │
               senin kodun: su_an("Europe/Istanbul") çalışır
                      │
               sen ──► API (tool_result ile)
                      │
               model: "İstanbul'da saat 14:32."   (stop_reason = end_turn)

Araç tanımı

Bir araç üç şeyden oluşur: name, description ve parametreleri anlatan bir JSON Schema (input_schema). Açıklama, modelin aracı ne zaman ve nasıl kullanacağını anlamasının tek yoludur; yani bir istem metnidir.

TOOLS = [
    {
        "name": "su_an",
        "description": "Verilen saat diliminde şu anki tarih ve saati döndürür. "
                       "Saat veya tarih sorulduğunda kullan; tahmin yürütme.",
        "input_schema": {
            "type": "object",
            "properties": {
                "zaman_dilimi": {
                    "type": "string",
                    "description": "IANA saat dilimi adı, örn. Europe/Istanbul veya Asia/Tokyo",
                }
            },
            "required": ["zaman_dilimi"],
        },
    }
]

Bir tam tur: istek → araç → cevap

import anthropic
from datetime import datetime
from zoneinfo import ZoneInfo

client = anthropic.Anthropic()
MODEL = "claude-haiku-5-5"

TOOLS = [{
    "name": "su_an",
    "description": "Verilen saat diliminde şu anki tarih ve saati döndürür.",
    "input_schema": {
        "type": "object",
        "properties": {"zaman_dilimi": {"type": "string", "description": "IANA adı, örn. Europe/Istanbul"}},
        "required": ["zaman_dilimi"],
    },
}]

def su_an(zaman_dilimi):
    return datetime.now(ZoneInfo(zaman_dilimi)).isoformat(timespec="seconds")

mesajlar = [{"role": "user", "content": "Tokyo'da şu an saat kaç?"}]

# 1) Modele soruyu ve araç tanımlarını ver
yanit = client.messages.create(model=MODEL, max_tokens=500, tools=TOOLS, messages=mesajlar)
print("stop_reason:", yanit.stop_reason)        # tool_use

# 2) Modelin cevabını (araç isteği dahil) konuşmaya ekle
mesajlar.append({"role": "assistant", "content": yanit.content})

# 3) İstenen araçları çalıştır, sonuçları tool_result olarak geri ver
sonuclar = []
for blok in yanit.content:
    if blok.type == "tool_use":
        print("istek:", blok.name, blok.input)
        sonuc = su_an(**blok.input)
        sonuclar.append({
            "type": "tool_result",
            "tool_use_id": blok.id,     # hangi isteğe cevap verdiğimizi eşler
            "content": sonuc,
        })
mesajlar.append({"role": "user", "content": sonuclar})

# 4) Model sonucu görüp nihai cevabı yazar
son = client.messages.create(model=MODEL, max_tokens=500, tools=TOOLS, messages=mesajlar)
print(son.content[0].text)

Dikkat edilecek üç ayrıntı

1. tool_use_id eşleşmesi: Her tool_result, karşılık geldiği tool_use bloğunun id‘sini taşımalı.
2. Modelin mesajını eksiksiz ekle: yanit.content‘in tamamı (metin + araç istekleri) assistant mesajı olarak geri eklenmeli.
3. Tek seferde birden fazla araç: Model aynı turda birden çok araç isteyebilir. Hepsinin sonucunu tek bir user mesajında döndür.

Araç başarısız olursa

Araç hata verirse çökmek yerine hatayı modele anlatılır biçimde bildir. Model çoğu zaman parametreyi düzeltip yeniden dener:

try:
    sonuc = su_an(**blok.input)
    hata = False
except Exception as e:
    sonuc = f"Hata: {e}. Saat dilimi IANA biçiminde olmalı (örn. Europe/Istanbul)."
    hata = True

sonuclar.append({
    "type": "tool_result",
    "tool_use_id": blok.id,
    "content": sonuc,
    "is_error": hata,
})

Bu derste yalnızca bir tur yaptık: modelin ikinci cevabı yine araç isteseydi kodumuz bunu işlemezdi. Bir sonraki ders bu sorunu çözen döngüyü yazıyor.