PydanticAI 2.30.0 ile Güvenli Yerel Web Ajanı: DNS Rebinding Testi

Kısa sonuç: PydanticAI 2.30.0, Python ile tip denetimli yapay zekâ ajanları kurmayı sağlayan MIT lisanslı bir çerçeve. 14 Ağustos 2026 sürümü özellikle önemli: yerel web sohbetine yönelik DNS rebinding açığını kapatıyor. Geçici bir Python 3.12 ortamında 2.30.0’ı kurdum, yerel sohbet arayüzünü çalıştırdım ve localhost isteğinin HTTP 200, saldırganı taklit eden Host: attacker.example isteğinin 421 döndürdüğünü doğruladım. Klavyeyle mesaj göndermek de çalıştı. Ancak Qwen 3.5 4B ile şema doğrulamalı gerçek model çağrısı iki denemede tamamlanmadı; bu bölüm çalışmış gibi gösterilmiyor.

PydanticAI ne işe yarar, kimler için?

PydanticAI bir sohbet uygulaması değil; model, araç, izin, bağımlılık ve çıktı şemasını Python kodunda bir araya getiren ajan geliştirme katmanıdır. Bir destek talebini serbest metin yerine doğrulanmış JSON’a çevirmek, modelin yalnız belirli işlevleri çağırmasına izin vermek, insan onayı gerektiren adımları ayırmak ve her çalışmanın maliyetini ya da izini kaydetmek gibi işler için uygundur.

FastAPI ve Pydantic kullanan Python ekipleri en hızlı uyumu sağlar. Yalnızca görsel sürükle-bırak akışı isteyenler için Dify veya n8n daha kolay olabilir. Bir defalık sohbet isteyen son kullanıcı için de bu çerçeve gereksiz derecede teknik kalır.

Mimari basitçe şöyledir: kullanıcı girdisi Agent nesnesine gelir; ajan seçilen modele talimat, konuşma geçmişi ve izin verilen araçların şemasını gönderir; model metin ya da araç çağrısı üretir; Pydantic çıktıyı belirtilen türe göre doğrular. Araç sonucu yeniden modele dönebilir. Sonuç, kullanım bilgisi ve mesaj geçmişiyle birlikte uygulamaya teslim edilir. OpenAI, Anthropic, Google, Ollama ve başka sağlayıcılar bağlanabilir; MCP, işlev araçları ve kalıcı yürütme seçenekleri ayrıca eklenebilir.

Kurulum ve güvenli başlangıç

Bu kılavuz 14 Ağustos 2026 tarihli 2.30.0 sürümünü sabitler. Python Package Index kaydı Python 3.10 ve üzerini istiyor. Ben Python 3.12.13 kullandım:

uv venv --python 3.12
source .venv/bin/activate
uv pip install "pydantic-ai==2.30.0"

Tam paket, web arayüzü ve entegrasyonlarla birlikte test ortamında 98 Python paketi kurdu. Daha küçük bir çalışma zamanı için resmî belgelerde pydantic-ai-slim seçenekleri var; fakat web arayüzünü kullanacaksanız gerekli ek grupları ayrıca seçmeniz gerekir. Üretimde yalnız ihtiyaç duyduğunuz bağımlılıkları sabitlemek, kilit dosyasını depoya eklemek ve güncellemeleri önce hazırlık ortamında denemek daha güvenlidir.

Yerel Ollama kullanacaksanız sunucuyu açıkça belirtin:

export OLLAMA_BASE_URL='http://localhost:11434/v1'

Bir bulut modelinde bunun yerine o sağlayıcının API anahtarı gerekir. Anahtarı koda, Git geçmişine veya sohbet istemine yazmayın. Yerel model kullanmak model girdisini üçüncü taraf API’ye göndermemeyi sağlayabilir; fakat ajan araçlarının ağ, dosya ve veri tabanı izinleri yine sizin sürecinizin yetkileriyle çalışır.

Gerçek senaryo: erişilebilirlik destek talebini yapılandırmak

Örnek amaç, ekran okuyucuyla ödeme alanına erişemeyen bir kullanıcının bildirimini dört alanlı bir destek kaydına dönüştürmek. Şema, önceliği üç değerle sınırlar; yanıt taslağının çok kısa olmasını ve adım listesinin kontrolsüz büyümesini engeller.

from typing import Literal
from pydantic import BaseModel, Field
from pydantic_ai import Agent
from pydantic_ai.output import NativeOutput

class DestekKaydi(BaseModel):
    oncelik: Literal['dusuk', 'orta', 'yuksek']
    insan_onayi_gerekli: bool
    yanit_taslagi: str = Field(min_length=20)
    adimlar: list[str] = Field(min_length=2, max_length=4)

agent = Agent(
    'ollama:qwen3.5:4b',
    output_type=NativeOutput(DestekKaydi),
    model_settings={'thinking': False, 'max_tokens': 300, 'timeout': 60},
    instructions=(
        'Türkçe erişilebilirlik taleplerini yapılandır. '
        'Ödeme eylemi gerçekleştirme; işlem gerekiyorsa insan onayı iste.'
    ),
)

sonuc = agent.run_sync(
    'Kart son kullanma alanının etiketi ekran okuyucumla okunmuyor. '
    'Satın alma yapmadan sorunu bildirmek istiyorum.'
)
print(sonuc.output.model_dump_json(indent=2))

Buradaki NativeOutput, yerel Ollama’nın JSON şeması desteğini kullanır. Bu, modelin doğru karar verdiğini kanıtlamaz; yalnız biçimin şemaya uymasını güçlendirir. “İnsan onayı gerekli” gibi alanlar için ayrıca iş kuralı testi gerekir. Ödeme, hesap kapatma veya ileti gönderme aracı eklenirse requires_approval ve sunucu tarafı yetki denetimi birlikte kullanılmalıdır.

Benim testimde ne çalıştı, ne çalışmadı?

Kurulum, paket içe aktarma ve yerel web uygulaması çalıştı. PydanticAI’nin TestModel modeliyle açılan arayüzde mesajı yazıp Enter’a bastım; yeni konuşma URL’si oluştu ve test yanıtı ekranda göründü. Bu model yapay zekâ değildir; uygulama akışını API ücreti ve değişken model çıktısı olmadan sınamak için prosedürel bir test aracıdır.

Qwen 3.5 4B çağrısı ise iki denemede de sonuç vermedi. İlk denemeyi yaklaşık üç dakika sonra, thinking: false ve 60 saniye model zaman aşımı eklenen ikinci denemeyi de 90 saniyeyi geçince elle durdurdum. Aynı Ollama sunucusuna doğrudan, düşünme kapalı kısa istek 0,35 saniye civarında “OK” döndürdü. Bu karşılaştırma model sunucusunun tümüyle kapalı olmadığını, sorunun PydanticAI–Ollama şema çağrısı veya istem işleme yolunda araştırılması gerektiğini gösteriyor. Gerçek model çıktısı elde edilmedi; yukarıdaki kod doğrulanmış bir sonuç örneği değil, yeniden üretilebilir kurulum iskeletidir.

Web arayüzü, klavye ve ekran okuyucu notları

Agent.to_web() ile açılan yerel sayfada sol tarafta “New conversation”, konuşma geçmişi ve tema denetimi; ana bölgede mesajlar, “What would you like to know?” yer tutuculu metin alanı, gizli araçlar düğmesi, model seçimi ve “Effort: Medium” açılır denetimi bulunuyor. Mesaj Enter ile gönderilebildi. Yanıttan sonra “Edit message”, “Retry” ve “Copy” denetimleri oluştu.

Bu yalnız kısa bir erişilebilirlik gözlemidir, WCAG uygunluk denetimi değildir. Semantik tarayıcı ağacında “Toggle Sidebar”, “Toggle theme”, model ve efor denetimleri okunabildi. Buna karşılık yazı yazıldığında beliren gönder düğmesi ile bir üst araç düğmesi erişilebilir ada sahip görünmedi. İngilizce yer tutucu ve menü adları Türkçe ürünlerde dil tutarlılığını da bozabilir. Ekran okuyucu kullanıcıları için düğmelere kalıcı erişilebilir ad, gönderim ve hata durumlarına canlı bölge bildirimi, görünür odak ve konuşma başlıklarına anlamlı ad eklenmesi kontrol edilmelidir.

DNS rebinding düzeltmesini adım adım doğrulama

Güvenlik duyurusuna göre Agent.to_web() ve clai web, eski sürümlerde Host başlığını doğrulamıyordu. Saldırganın denetimindeki bir alan adı önce kendi sunucusuna, sonra 127.0.0.1’e çözümlenirse ziyaret edilen sayfa yerel ajan uç noktasına aynı kaynak gibi erişebilirdi. Sonuç, ajanın yerel sürecin dosya, ağ, araç ve kimlik bilgisi yetkileriyle çalıştırılması olabilirdi. Yalnız localhost’a bağlanmak bu saldırıyı tek başına durdurmuyordu.

2.30.0 testinde şu iki istek farklı sonuç verdi:

curl -i -H 'Host: localhost' \
  http://127.0.0.1:7932/api/health
# HTTP 200

curl -i -H 'Host: attacker.example' \
  http://127.0.0.1:7932/api/health
# HTTP 421 Misdirected Request

Gerçek bir ters vekil veya tünel alan adı kullanıyorsanız yalnız denetlediğiniz adı ekleyin:

app = agent.to_web(allowed_hosts=['ajan.example.com'])

allowed_hosts=['*'] korumayı kaldırır; yalnız önünde güçlü kimlik doğrulama ve yetkilendirme varsa düşünülmelidir. Ayrıca web arayüzündeki “onayla” düğmesini tek güvenlik sınırı saymayın. Resmî belge, sunucunun istemciden gelen onay kararına güvendiğini belirtiyor. Araç işlevinin içinde kullanıcı, kaynak, kapsam ve eylem yetkisini yeniden denetleyin.

Gözlemlenebilirlik, hata kurtarma ve maliyet

PydanticAI, OpenTelemetry ile ajan çalışmasını, model isteğini ve araç yürütmesini izleyebilir; Pydantic Logfire veya başka bir OTel arka ucu kullanılabilir. Ancak istem, araç argümanı, yanıt ve hata kayıtları kişisel veri içerebilir. İçerik yakalamayı en düşük düzeyde tutun, erişim süresi ve rol denetimi belirleyin, ödeme ya da kimlik verisini maskeleyin.

Hata kurtarmada üç katman yararlıdır: önce model çağrısına makul zaman aşımı ve istek sınırı; sonra şema doğrulama hatası için kontrollü yeniden deneme; son olarak kullanıcıya “işlem yapılmadı” durumuyla insan devri. Kalıcı yürütme entegrasyonları uzun işleri sürdürebilir, fakat yan etkili bir araç yeniden oynatılırsa aynı e-postayı veya ödemeyi iki kez çalıştırmamak için idempotency anahtarı gerekir.

Çerçeve MIT lisanslıdır; lisans metni 2.30.0 etiketinde doğrulandı. MIT kullanım, değiştirme ve dağıtıma geniş izin verir, telif ve lisans bildirimini koruma yükümlülüğü taşır; güvenlik veya bakım garantisi vermez. Model API’si, Ollama modeli, Logfire, bulut veritabanı ve diğer araçların ayrı ücret ve koşulları vardır. Her çalışmanın result.usage() değerini kaydedin, sağlayıcı fiyatını tarihli yapılandırmada tutun ve kullanıcı/iş akışı başına bütçe sınırı koyun.

Alternatiflerle karşılaştırma

LangGraph, açık durum grafiği, kontrol noktası ve insan onaylı dallanma gereken uzun işlerde daha görünür bir yürütme modeli sunar. smolagents, küçük bir araç ajanını daha az soyutlamayla kurmak isteyenlere hafif gelir. Google ADK, Google model ve bulut ekosistemiyle bütünleşen ekipler için hazır dağıtım yolları sağlar. PydanticAI’nin güçlü yanı Python tipleri, doğrulanmış çıktı ve FastAPI’ye yakın geliştirici deneyimidir; zayıf yanı, hızla değişen API yüzeyi ve entegrasyon sayısı büyüdükçe ortaya çıkan bakım yüküdür.

Sınırlamalar ve sorun giderme

• Eski sürüm: pydantic-ai veya pydantic-ai-slim 2.x kullanıyorsanız en az 2.30.0’a; 1.x bakım hattındaysanız en az 1.107.5’e geçin.
• 421 hatası: Sağlık kontrolünüz gerçek alan adı gönderiyorsa o adı dar bir allowed_hosts listesine ekleyin; jokeri varsayılan çözüm yapmayın.
• Yerel model takılıyor: Önce Ollama’ya doğrudan kısa istek gönderin. Sonra düşünmeyi kapatın, token ve zaman aşımı sınırı koyun, şemasız metinle karşılaştırın ve sağlayıcı uyumluluğunu kontrol edin.
• Çıktı şemaya uyuyor ama yanlış: Pydantic biçimi doğrular, gerçeği değil. Alanlar arası iş kurallarını kodla doğrulayın ve riskli kararı insana bırakın.
• Web arayüzü dışarı açılacak: TLS, kimlik doğrulama, oran sınırlama, CSRF/CORS ayarları, araç içi yetki denetimi ve ayrı düşük yetkili süreç olmadan geliştirme arayüzünü internete sunmayın.

Kaynaklar

• PydanticAI 2.30.0 sürüm notları — 14 Ağustos 2026.
• GHSA-q2xc-rrxj-58×9 güvenlik duyurusu — etki, sürüm aralıkları ve düzeltme.
• PydanticAI web sohbeti kılavuzu — Host doğrulaması, araç onayı ve arayüz yolları.
• PydanticAI Ollama belgeleri — yerel sunucu ve yapılandırılmış çıktı.
• PydanticAI test kılavuzu — TestModel, FunctionModel ve gerçek model çağrılarını engelleme.
• OpenTelemetry enstrümantasyonu — model ve araç izleri.
• 2.30.0 etiketindeki MIT lisansı.

İnceleme ve test tarihi: 14 Ağustos 2026. GitHub issue sayıları ve ana dal hızla değiştiği için popülerlik ya da kalite kanıtı olarak kullanılmadı. Depoda 14 Ağustos itibarıyla ayrı bir SECURITY.md dosyası görünmese de bu sürüm için herkese açık GitHub güvenlik duyurusu yayımlandı.