DEV Community

Cover image for PydanticAI Nedir? Tür Güvenli Python Ajan Çatısı Rehberi
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

PydanticAI Nedir? Tür Güvenli Python Ajan Çatısı Rehberi

Eğer bir LLM özelliğini üretime aldıysanız ve beklenmedik anda bozuk JSON döndürdüğünü gördüyseniz, PydanticAI tam bu problem için tasarlanmıştır. Pydantic ekibi tarafından geliştirilen bu Python ajan çerçevesi, tür güvenli ve doğrulanmış çıktıları ajan geliştirme akışının merkezine koyar.

Apidog'u bugün deneyin

PydanticAI nedir?

PydanticAI, Python için açık kaynaklı ve sağlayıcıdan bağımsız bir ajan çerçevesidir. Pydantic Validation ve Pydantic Logfire’ı geliştiren ekip tarafından sürdürülür. Tasarım hedefi nettir: ajan geliştirmeye “FastAPI hissi” getirmek.

Pydantic AI

PydanticAI ile şunları açıkça tanımlarsınız:

  • Ajanın hangi modeli kullanacağı
  • Hangi araçları çağırabileceği
  • Çıktının hangi Pydantic modeliyle doğrulanacağı
  • Çalışma sırasında hangi bağımlılıkların enjekte edileceği

Model geçersiz bir çıktı döndürürse PydanticAI doğrulama hatasını modele geri iletir ve yeniden deneme akışını yönetir. Böylece alt katmandaki kodunuz ham metin veya “çoğunlukla geçerli JSON” yerine doğrulanmış Python nesneleriyle çalışır.

Kurulum:

pip install pydantic-ai
Enter fullscreen mode Exit fullscreen mode

veya:

uv add pydantic-ai
Enter fullscreen mode Exit fullscreen mode

Proje, beta sürümlerinden sonra 23 Haziran 2026’da kararlı v2.0.0 sürümüne ulaştı. V2 tasarımı, araçlar, kancalar, talimatlar ve model ayarlarının yeniden kullanılabilir “harness-first” birimler olarak organize edilmesine odaklanır.

Ajanlar için tür güvenliği neden önemlidir?

LLM çıktıları deterministik değildir. Aynı prompt iki farklı yanıtta iki farklı JSON şekli üretebilir. Bu, sohbet arayüzünde tolere edilebilir; ancak çıktı şu sistemlere bağlandığında hata riski büyür:

  • Veritabanı yazma işlemleri
  • REST API çağrıları
  • Faturalama veya puanlama hesapları
  • Destek bileti sınıflandırma
  • Otomatik iş akışları

Tipik hata şudur:

{
  "category": "billing",
  "priority": "high"
}
Enter fullscreen mode Exit fullscreen mode

Kodunuz ise şunu bekliyordur:

priority: int
Enter fullscreen mode Exit fullscreen mode

Bu tür durumlarda çoğu ekip zamanla şunları yazmaya başlar:

  • Elle JSON ayrıştırma
  • Regex ile temizleme
  • Savunmacı try/except blokları
  • Özel retry mantığı
  • Eksik alanlar için fallback kodları

PydanticAI bu sorunu çerçeve seviyesinde çözer. Bir Pydantic modeli tanımlarsınız, ajan çıktısını bu modele bağlarsınız ve sonuç doğrulanmış nesne olarak gelir.

Aynı doğrulama araç çağrıları için de geçerlidir. Model bir tool çağırdığında, PydanticAI fonksiyon çalışmadan önce argümanları tür ipuçlarına göre doğrular. Hatalı argümanlar iş mantığınıza ulaşmaz.

Temel kavramlar

PydanticAI’nin pratikte en çok kullanacağınız parçaları şunlardır:

  1. Agent
  2. Türlenmiş çıktılar
  3. Araçlar
  4. Bağımlılıklar
  5. Sağlayıcıdan bağımsız model seçimi ve streaming

1. Agent oluşturma

Agent sınıfı ana giriş noktasıdır. Bir model tanımlayıcı ve isteğe bağlı talimatlarla ajan oluşturursunuz.

from pydantic_ai import Agent

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='Kısa cevap ver, tek cümle kullan.',
)

result = agent.run_sync('Where does "hello world" come from?')

print(result.output)
Enter fullscreen mode Exit fullscreen mode

Sağlayıcı değiştirmek genellikle yalnızca model dizesini değiştirmek anlamına gelir:

agent = Agent('openai:gpt-4o')
Enter fullscreen mode Exit fullscreen mode

Bu yapı, ajan kodunu belirli bir sağlayıcıya sıkı bağlamadan geliştirmenizi sağlar.

2. Türlenmiş çıktı kullanma

En önemli kullanım alanı, LLM çıktısını Pydantic modeliyle doğrulamaktır.

from pydantic import BaseModel
from pydantic_ai import Agent


class SupportTicket(BaseModel):
    category: str
    priority: int
    summary: str


agent = Agent(
    'openai:gpt-4o',
    output_type=SupportTicket,
)

result = agent.run_sync('My payment failed three times today.')

ticket = result.output

print(ticket.category)
print(ticket.priority)
print(ticket.summary)
Enter fullscreen mode Exit fullscreen mode

Burada result.output artık rastgele bir string değildir. Doğrulanmış bir SupportTicket nesnesidir.

Örneğin şu alan doğrudan int olarak kullanılabilir:

if ticket.priority >= 8:
    escalate_ticket(ticket)
Enter fullscreen mode Exit fullscreen mode

Model priority alanını metin olarak döndürürse veya summary alanını atlarsa doğrulama başarısız olur ve PydanticAI yeniden isteme akışını devreye alır.

3. Araç tanımlama

Araçlar, modelin dış sistemlerle çalışmasını sağlar:

  • Veritabanından veri okuma
  • REST API çağırma
  • Hesaplama yapma
  • Kullanıcı bilgisi getirme
  • Sipariş durumu sorgulama

Bir aracı @agent.tool dekoratörüyle kaydedersiniz.

from pydantic_ai import Agent, RunContext

agent = Agent(
    'openai:gpt-4o',
    deps_type=str,
)


@agent.tool
async def get_user_balance(ctx: RunContext[str], account_id: str) -> float:
    """Bir hesap için mevcut bakiyeyi döndürür."""
    return await lookup_balance(ctx.deps, account_id)
Enter fullscreen mode Exit fullscreen mode

PydanticAI burada şunları yapar:

  • Fonksiyon imzasını okur
  • Tür ipuçlarından tool şeması üretir
  • Docstring’i modele açıklama olarak verir
  • Model tool çağırdığında argümanları doğrular
  • Fonksiyonu yalnızca geçerli argümanlarla çalıştırır

Bu sayede model şu gibi hatalı bir çağrı yaparsa:

{
  "account_id": 12345
}
Enter fullscreen mode Exit fullscreen mode

ve fonksiyonunuz str bekliyorsa, doğrulama katmanı devreye girer.

4. Bağımlılık enjeksiyonu kullanma

Gerçek ajanlarda çoğu zaman dış bağlama ihtiyaç duyarsınız:

  • Veritabanı bağlantısı
  • HTTP istemcisi
  • API anahtarı
  • Mevcut kullanıcı
  • Ortam yapılandırması

PydanticAI bunu deps_type ve RunContext ile yönetir.

Örnek:

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext


@dataclass
class AppDeps:
    api_base_url: str
    api_key: str


agent = Agent(
    'openai:gpt-4o',
    deps_type=AppDeps,
)


@agent.tool
async def get_order_status(ctx: RunContext[AppDeps], order_id: str) -> str:
    """Sipariş durumunu döndürür."""
    return await fetch_order_status(
        base_url=ctx.deps.api_base_url,
        api_key=ctx.deps.api_key,
        order_id=order_id,
    )
Enter fullscreen mode Exit fullscreen mode

Çalıştırırken bağımlılıkları verirsiniz:

deps = AppDeps(
    api_base_url='https://api.example.com',
    api_key='secret',
)

result = await agent.run(
    'Order 123 için durumu kontrol et.',
    deps=deps,
)
Enter fullscreen mode Exit fullscreen mode

Bu yapı testleri de kolaylaştırır. Gerçek API istemcisi yerine mock veya fake bağımlılık geçebilirsiniz.

5. Sağlayıcıdan bağımsız model seçimi ve streaming

PydanticAI şu sağlayıcılarla çalışacak şekilde tasarlanmıştır:

  • OpenAI
  • Anthropic
  • Gemini
  • DeepSeek
  • Grok
  • Cohere
  • Mistral
  • Perplexity
  • Azure AI Foundry
  • Amazon Bedrock
  • Kendi barındırdığınız modeller

Model seçimi genellikle Agent içindeki model dizesiyle yapılır:

agent = Agent('anthropic:claude-sonnet-4-6')
Enter fullscreen mode Exit fullscreen mode

veya:

agent = Agent('openai:gpt-4o')
Enter fullscreen mode Exit fullscreen mode

PydanticAI ayrıca yapılandırılmış çıktılarda streaming’i destekler. Veriler geldikçe doğrulama uygulanabilir; böylece kısmi sonuçları işlerken tür garantilerinden vazgeçmek zorunda kalmazsınız.

Pydantic Logfire entegrasyonu sayesinde çalıştırmalar için gözlemlenebilirlik de ekosistemin bir parçasıdır:

  • Trace
  • Hata ayıklama
  • Maliyet takibi
  • Çalıştırma geçmişi

PydanticAI diğer Python ajan çerçeveleriyle nasıl karşılaştırılır?

Tek bir “en iyi” ajan çerçevesi yoktur. Seçim, kontrol akışı, tür güvenliği, sağlayıcı tercihi ve orkestrasyon ihtiyacına göre değişir.

Çerçeve Temel güç İstediğinizde en iyisi
PydanticAI Tür güvenli, doğrulanmış çıktılar ve araç argümanları Üretim güvenilirliği ve temiz türlenmiş veri akışı
LangGraph Açık durum bilgisi olan grafikler ve kontrol akışı Uzun süreli, dallanan, çok adımlı iş akışları
Google ADK Google ekosisteminde çoklu ajan orkestrasyonu Derin Gemini ve Vertex AI entegrasyonu
OpenAI Agents SDK Devir teslimli sıkı OpenAI entegrasyonu OpenAI odaklı yığın ve hızlı kurulum

PydanticAI’nin ana farkı doğrulama katmanıdır. Ajanınız başka sistemlere veri gönderiyorsa, çıktının bir Pydantic modeliyle eşleşmesi önemli bir üretim güvenliği sağlar.

LangGraph daha çok şu durumlarda uygundur:

  • Uzun süreli ajan akışları
  • Açık durum makineleri
  • Dallanan iş akışları
  • Çok adımlı kontrol akışı

OpenAI Agents SDK ise OpenAI odaklı bir yığın kullanıyorsanız ve ajan devir teslimi veya MCP sunucu desteği gibi özellikler istiyorsanız doğal bir seçimdir.

Bu çerçeveler birbirini dışlamak zorunda değildir. PydanticAI, daha büyük bir orkestrasyon içinde türlenmiş çıktı katmanı olarak da kullanılabilir.

PydanticAI ne zaman kullanılır?

PydanticAI şu durumlarda iyi bir seçimdir:

  • Ajan çıktısı sadece sohbet ekranına değil, gerçek koda gidiyorsa
  • Çıktı biçiminin kesin olarak doğru olması gerekiyorsa
  • IDE ve type checker desteği istiyorsanız
  • Kod tabanınızda zaten Pydantic kullanıyorsanız
  • Sağlayıcı değiştirme esnekliği istiyorsanız
  • Araç argümanlarını çalıştırmadan önce doğrulamak istiyorsanız
  • Logfire ile gözlemlenebilirlik sizin için önemliyse

Şu durumda farklı bir çerçeve daha uygun olabilir:

  • Karmaşık, dallanan, uzun süreli grafik tabanlı orkestrasyon gerekiyorsa
  • Açık bir state machine üzerinde ince taneli kontrol istiyorsanız

Bu senaryoda LangGraph gibi grafik tabanlı bir yapı daha doğrudan kontrol sağlar.

Ajanınızın arkasındaki API’leri test etme ve taklit etme

Bir PydanticAI ajanı, bağlı olduğu API’ler kadar güvenilirdir. Her çalıştırma genellikle bir LLM sağlayıcısını çağırır. Kullanışlı ajanların çoğu ayrıca kendi REST uç noktalarınızı veya üçüncü taraf servisleri de çağırır.

Riskli noktalar genellikle buradadır:

  • Hatalı API yanıt şekilleri
  • Eksik alanlar
  • Beklenmeyen durum kodları
  • Sağlayıcı hız sınırları
  • Gereksiz token maliyeti
  • Ortam bazlı yanlış anahtar kullanımı

PydanticAI model çıktısını doğrular; ancak çağırdığınız yukarı akış API’nin beklediğiniz yanıtı döndürdüğünü tek başına garanti edemez.

Burada Apidog farklı bir problemi çözer. Apidog, ajanınızın konuştuğu API’leri test etmek ve taklit etmek için kullanabileceğiniz bir API platformudur.

Pratik kullanım senaryoları:

LLM veya tool uç noktasını taklit edin

Geliştirme sırasında gerçek sağlayıcıya gitmek yerine bir tool’u deterministik yanıtlar döndüren mock API’ye yönlendirebilirsiniz.

Bu şunları sağlar:

  • Her testte token harcamazsınız
  • Sağlayıcı rate limit’lerine takılmazsınız
  • Aynı girdiye aynı çıktıyı alarak daha güvenilir test yazarsınız
  • Tool mantığını LLM belirsizliğinden bağımsız test edersiniz

Yanıt şekillerini doğrulayın

Bir REST uç noktasını @agent.tool fonksiyonuna bağlamadan önce, gerçek API yanıtının beklenen yapıyla eşleştiğini kontrol edin.

Bunun için API assertions kullanabilirsiniz.

Örneğin tool’unuz şunu bekliyorsa:

class BalanceResponse(BaseModel):
    account_id: str
    balance: float
    currency: str
Enter fullscreen mode Exit fullscreen mode

API’nin gerçekten balance ve currency alanlarını döndürdüğünü ajan katmanına gelmeden önce doğrulayabilirsiniz.

Anahtarları ortama göre yönetin

Yerel geliştirme, staging ve CI için farklı değerler kullanmanız gerekir:

  • Base URL
  • API key
  • LLM sağlayıcı anahtarı
  • Mock endpoint
  • Timeout ayarları

Apidog ortamlarıyla bu değerleri ayrı tutabilir, kod değiştirmeden farklı hedeflere istek gönderebilirsiniz.

LLM uç noktasını doğrudan doğrulayın

Bir sağlayıcıyı HTTP üzerinden çağırıyorsanız, ajanınızı bağlamadan önce kimlik doğrulama, streaming ve tool calling biçimlerini test edebilirsiniz.

Örneğin Apidog ile ChatGPT API’sini test edebilirsiniz.

Apidog ajan inşa etmez ve PydanticAI’ye alternatif değildir. Ajanınızın dayandığı API yüzeyini test ettiğiniz, doğruladığınız ve taklit ettiğiniz çalışma alanıdır.

Başlamak için Apidog’u indirin ve önce bir tool endpoint’inizi mock olarak çalıştırın.

Sıkça Sorulan Sorular

PydanticAI ücretsiz ve açık kaynak mı?

Evet. PydanticAI açık kaynaklıdır ve PyPI üzerinden kurulabilir:

pip install pydantic-ai
Enter fullscreen mode Exit fullscreen mode

veya:

uv add pydantic-ai
Enter fullscreen mode Exit fullscreen mode

Ancak kullandığınız LLM sağlayıcısı için ödeme yapmanız gerekebilir. Çerçeve bu sağlayıcı API’lerini sizin adınıza çağırır.

Geliştirme ve test sırasında maliyeti azaltmak için canlı modeli her çalıştırmada çağırmak yerine API yanıtlarını mock edebilirsiniz.

PydanticAI hangi modellerle çalışır?

PydanticAI sağlayıcıdan bağımsızdır. Belgelerde şu sağlayıcılar listelenir:

  • OpenAI
  • Anthropic
  • Gemini
  • DeepSeek
  • Grok
  • Cohere
  • Mistral
  • Perplexity
  • Azure AI Foundry
  • Amazon Bedrock
  • Kendi barındırılan modeller

Model seçimi Agent yapıcısına verilen dizeyle yapılır:

agent = Agent('anthropic:claude-sonnet-4-6')
Enter fullscreen mode Exit fullscreen mode

veya:

agent = Agent('openai:gpt-4o')
Enter fullscreen mode Exit fullscreen mode

Geçiş çoğu durumda tek satırlık değişikliktir.

PydanticAI, LangChain veya LangGraph’tan nasıl farklıdır?

PydanticAI’nin odağı tür güvenliğidir:

  • Pydantic modelleriyle doğrulanmış yapılandırılmış çıktılar
  • Doğrulanmış tool argümanları
  • Temiz ve türlenmiş veri akışı

LangGraph ise çok adımlı ve dallanan iş akışları için açık durum bilgisi olan grafiklere odaklanır.

Önceliğiniz çıktı şekillerinin garanti edilmesi ve üretim koduna güvenli veri akışıysa PydanticAI iyi bir seçimdir. Önceliğiniz karmaşık durum makineleri ve kontrol akışıysa grafik tabanlı bir çerçeve daha uygun olabilir.

Kullanmak için Pydantic bilmem gerekiyor mu?

Temel Pydantic bilgisi yardımcı olur, ancak başlamak için çok derin bilgi gerekmez. Veri şekillerini BaseModel’den türeyen sınıflar olarak tanımlarsınız.

from pydantic import BaseModel


class UserIntent(BaseModel):
    intent: str
    confidence: float
Enter fullscreen mode Exit fullscreen mode

PydanticAI bu modelleri çıktı doğrulama ve tool şemaları için kullanır.

Daha önce Python ile API testi yaptıysanız veya FastAPI kullandıysanız, modelleme yaklaşımı tanıdık gelecektir.

Sonuç

PydanticAI, ajan geliştirmede pratik bir güvenlik katmanı sağlar: model çıktıları ve tool çağrıları bildirdiğiniz türlerle eşleşmek zorundadır. Bu, üretimde sık görülen bozuk JSON, eksik alan ve hatalı argüman problemlerini azaltır.

Şu durumda PydanticAI kullanın:

  • Ajan çıktısı gerçek koda bağlanıyorsa
  • Yapılandırılmış çıktı güvenilirliği önemliyse
  • Pydantic tabanlı veri modelleriyle çalışmak istiyorsanız
  • Tool argümanlarını çalıştırmadan önce doğrulamak istiyorsanız

Hangi ajan çerçevesini seçerseniz seçin, alttaki API’leri ayrıca test etmeniz gerekir. LLM ve tool endpoint’lerinizi mock edin, yanıt şekillerini doğrulayın ve ortam bazlı anahtarları Apidog üzerinde yönetin. Böylece ajanınız, gerçekten doğrulanmış bir API temeli üzerinde çalışır.

Top comments (0)