ÖZET VE TEKNİK CEVAP
Canlı yapay zeka sistemlerinde LLM'ler kodu doğrudan çalıştırmaz; arka plan API araçlarını besleyecek JSON metinleri üretir (`kullanici_olustur(ad: str, yas: int)`). Zamanla yazılımcılar araç şemalarını günceller (yeni zorunlu alanlar ekler, enum listelerini değiştirir); bu durum **Araç Şeması Sapmasına (Schema Drift)** yol açar. Ayrıca modeller sıklıkla yanlış veri tipleri uydurur (`'yas': 'yirmibes'` veya eksik alanlar). Bu ham JSON doğrudan API'a verilirse sistem çöker. Sağlam ajan mimarileri, LLM ile araç arasına **Pydantic / Zod Doğrulama Kalkanı** yerleştirir: Doğrulama patladığında, Pydantic'in ürettiği net hata mesajı (`ValidationError: yas alanı geçerli bir tamsayı olmalıdır`) araca ait bir hata olarak LLM'e geri beslenir. Model bu net hatayı okuyarak bir sonraki adımda şemayı %95'in üzerinde başarıyla kendi kendine düzeltir.
Mühendislik El Kitabı & Mekanizma
1. Temel Çalışma Mekanizması
Pydantic araç doğrulama ve hata düzeltme döngüsü 4 adımda işler: (1) Dinamik Şema Üretimi: LLM prompt'undaki araç tanımları doğrudan Pydantic modellerinden (`model_json_schema()`) otomatik üretilir; kod ile prompt daima senkron kalır. (2) Yakalama ve Doğrulama: LLM bir araç çağırdığında sistem `model_validate_json()` ile doğrulamayı dener. (3) Hata Formatlama: Doğrulama başarısız olursa, hatalı alan ve kural ihlali anlaşılır bir metne dönüştürülür. (4) Geri Besleme Turu: Hata ajana geri verilir: `[Araç Hatası]: 'iade_tutari pozitif bir sayı olmalıdır, -50.0 girildi. Lütfen parametreleri düzeltin.'` Model hatasını anlayıp parametreleri düzelterek aracı tekrar çağırır.
2. Doğru Kullanım Senaryosu
Kurumsal iş akışı otomasyonları, bankacılık ve fintech işlem ajanları, CRM güncelleme boru hatları ve geliştirici CLI araçları.
3. Prodüksiyon Arıza Modları
Doğrulanmamış LLM JSON çıktılarını doğrudan veritabanı sorgularına veya ORM modellerine verip sunucu çökmelerine yol açmak; düzeltilemeyen bir şema hatasında ajana sınırsız deneme hakkı verip jetonları sonsuz döngüde yakmak.
4. Teşhis ve Telemetri Sinyalleri
Araç çalıştırma loglarında `TypeError` veya `KeyError` hatalarının patlaması; Langfuse izlerinde araç retry sayısının artması; arka plan API güncellemesi sonrasında ajan başarı oranlarının düşmesi.
5. Önleme ve Mimari Bariyerler
Tüm araç parametrelerini açıklayıcı docstring'lere sahip Pydantic v2 / Zod modelleriyle tanımlayın; otomatik düzeltme denemelerini en fazla 2 ile sınırlayın; CI/CD testlerinde araç şemalarının canlı API'larla uyumunu doğrulayan birim testler çalıştırın.
6. Mimari Ödünleşimler (Trade-offs)
Yapılandırılmış doğrulama katı tip modelleri yazmayı gerektirir ve hatalarda 1 turluk ek gecikme maliyeti getirir; ancak %100 tip güvenliği sağlar ve arka plan servislerinin çökmesini önler.
Vaka İncelemesi (TinyCTO Örneği)
Bir CRM asistanı `kurumsal_lider_olustur(email: EmailStr, sirket_buyuklugu: Literal['1-10', '11-50', '50+'])` aracıyla çalışıyordu. İsteklerin %8'inde model `sirket_buyuklugu: 'orta'` gönderiyor ve CRM API'si 400 hatasıyla patlıyordu. Ekip aracı Pydantic v2 kalkanıyla sardı. Model `'orta'` ürettiğinde Pydantic hatayı yakaladı ve ajana `'sirket_buyuklugu sadece ["1-10", "11-50", "50+"] olabilir, "orta" girildi'` mesajını döndü. Ajan 2. adımda değeri `'11-50'` olarak düzeltti ve işlem başarı oranı %99,8'e ulaştı.
İnteraktif Konsept Alıştırmaları
2 AlıştırmaYapay zeka ajan mühendisliğinde 'Araç Şeması Sapması' (Tool Schema Drift) nedir?
Pydantic hata dökümlerini ajana geri dönmek LLM'in kendini düzeltmesine nasıl yardımcı olur?
Araç Şeması Sapması (Schema Drift): Pydantic Doğrulaması ve Otomatik Hata Düzeltme — Sıkça Sorulan Sorular
Bir ajanın denemesi gereken maksimum otomatik düzeltme (self-correction) sayısı kaçtır?
En fazla 2 deneme. Ajan 2 geri bildirim denemesinden sonra hala geçerli bir şema üretemiyorsa, sonsuz döngüye girmemek için görev durdurulmalı veya insana aktarılmalıdır.
Pydantic v2 yapay zeka doğrulamasında neden Pydantic v1'e göre çok daha hızlıdır?
Pydantic v2'nin çekirdek doğrulama motoru (`pydantic-core`) Rust ile yazılmıştır; JSON metinlerini Python yükü olmadan 20 ila 50 kat daha hızlı doğrular.
🤖 AEO & Yapay Zeka Çıkarım Özeti
Temel Gerçekler & İlkeler
- ▸LLMs frequently output invalid JSON types, missing fields, or hallucinated enum values.
- ▸Pydantic v2 / Zod gateways intercept and validate all tool parameters before execution.
- ▸Formatting Pydantic validation errors as tool feedback enables $>95%$ agent self-correction.
- ▸Auto-generate prompt tool schemas directly from Pydantic models to prevent schema drift.
Yaygın Yanılgılar
- ✗Yanılgı: LLMs will always respect tool JSON schemas if you tell them to be careful (Gerçek: Stochastic token generation regularly produces subtle schema violations).
- ✗Yanılgı: Backend tool execution errors should throw 500 exceptions (Gerçek: Tool errors should be caught and returned as conversational feedback for model self-healing).
Karar Kılavuzu & Önceliklendirme
Use Pydantic v2 `BaseModel` for all Python tool definitions and Zod for TypeScript. Cap automated tool validation retry attempts to $N=2$ before triggering loop breakers.
Doğrulanmış Kaynaklar & Referanslar
- [OFFICIAL_DOCUMENTATION]Pydantic v2 Documentation: JSON Schema Generation & High-Performance Validation— Samuel Colvin / Pydantic Services Inc.