Eğer bir LLM özelliğini yayınladıysanız ve üretimde bozuk JSON döndürdüğünü gördüyseniz, PydanticAI sizin için yapıldı. Pydantic'in arkasındaki ekip tarafından geliştirilen Python aracı çerçevesidir ve tür güvenli, doğrulanmış çıktıları ajan geliştirmenin merkezine koyar. Bu kılavuz, PydanticAI'nin ne olduğunu, tür güvenliğinin ajanlar için neden önemli olduğunu, gerçekten kullanacağınız temel kavramları ve LangGraph gibi diğer Python çerçevelerine karşı nasıl bir konumda olduğunu açıklar.
PydanticAI nedir?
PydanticAI, Python için açık kaynaklı, sağlayıcıdan bağımsız bir ajan çerçevesidir. Pydantic Validation ve Pydantic Logfire'ı geliştiren ekip tarafından sürdürülmektedir, bu nedenle güçlü bir doğrulama temeline ve net bir tasarım hedefine sahiptir: ajan geliştirmeye "o FastAPI hissini" getirmek.
Basitçe ifade etmek gerekirse, ajanınızın ne yapması gerektiğini, hangi araçları çağırabileceğini ve çıktısının hangi biçimde olması gerektiğini siz tanımlarsınız. PydanticAI model çağrılarını yönetir, her şeyi Pydantic modellerinize göre doğrular ve model uyumsuz bir şey döndürdüğünde yeniden dener. Proje, bir dizi beta sürümünden sonra 23 Haziran 2026'da istikrarlı bir v2.0.0 sürümüne ulaştı. V2, bir ajanın araçlarının, kancalarının, talimatlarının ve model ayarlarının yeniden kullanılabilir birimler olarak birleştiği bir "harness-first" (koşum takımı öncelikli) tasarımına odaklanır. `pip install pydantic-ai` veya `uv add pydantic-ai` komutlarıyla kurabilirsiniz.
Ajanlar için tür güvenliği neden önemlidir?
LLM'ler deterministik değildir. Aynı soruyu iki kez sorduğunuzda iki farklı yanıt şekli alabilirsiniz. Bu bir sohbet kutusu için sorun değil, ancak model çıktısını gerçek koda bağladığınız anda bozulur: bir veritabanı yazma işlemi, bir API çağrısı, bir faturalama hesaplaması. Çoğu ajan hatası bu boşluktan kaynaklanır. Model "çoğunlukla" geçerli JSON döndürür, ayrıştırıcınız testte çalışır, ardından bir üretim yanıtı bir alanı düşürür veya yanıtı nesirle sarar ve hattınız hata verir. Sonunda savunmacı ayrıştırma, regex temizleme ve tekrar deneme döngülerini elle yazarsınız. PydanticAI, çıktı sözleşmesini çerçevenin bir parçası haline getirerek bu boşluğu kapatır. Bir Pydantic modeli tanımlarsınız, bunu çıktı tipi olarak geçirirsiniz ve çerçeve, geri aldığınız değerin o modele uyduğunu garanti eder. Model geçersiz bir şey döndürürse, PydanticAI doğrulama hatasını LLM'e geri gönderir ve tekrar denemesini ister. Alt akış kodunuz, umut veren dizeler yerine türlenmiş nesneler alır. Aynı fikir, araç argümanları için de geçerlidir. Model, araçlarınızdan birini çağırdığında, PydanticAI, fonksiyon çalışmadan önce argümanları fonksiyonunuzun tür ipuçlarına göre doğrular. Hatalı argümanlar asla iş mantığınıza ulaşmaz.
Temel kavramlar
PydanticAI yüzey alanını küçük tutar. Beş fikir, geliştireceğiniz çoğu şeyi kapsar.
Ajanlar
`Agent` sınıfı ana giriş noktasıdır. Bir model tanımlayıcı ve isteğe bağlı talimatlarla bir ajan oluşturursunuz. Sınıf, iki tür parametresi üzerinde geneldir: bağımlılıklar tipi ve çıktı tipi, bu da editörünüze ve tür denetleyicinize ajanınız hakkında gerçek görünürlük sağlar. ```python from pydantic_ai import Agent agent = Agent( 'anthropic:claude-sonnet-4-6', instructions='Be concise, reply with one sentence.', ) result = agent.run_sync('Where does "hello world" come from?') print(result.output) ``` Sağlayıcıları değiştirmek için değiştireceğiniz tek şey o model dizesidir, bu da kodunuzu taşınabilir tutar.
Türlenmiş çıktılar
`output_type` olarak bir Pydantic modeli geçirdiğinizde, ajanın sonucu ona göre doğrulanır. Türlenmiş bir nesne geri alırsınız ve IDE'niz her alanı bilir. İşte yapılandırılmış bir çıktı taslağı: ```python 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.') print(result.output.priority) # bir int, doğrulanmış, bir tahmin değil ``` Model bir önceliği metin olarak döndürürse veya özeti atlarsa, doğrulama başarısız olur ve çerçeve yeniden ister. Ham yanıtı asla kendiniz ayrıştırmazsınız.
Araçlar
Araçlar, modelin kendi dışına erişmesini sağlar: bir veritabanını sorgulamak, bir REST API'sine istek göndermek, bir hesaplama yapmak. Bir aracı `@agent.tool` dekoratörüyle kaydedersiniz. PydanticAI, modelin gördüğü şemayı oluşturmak için fonksiyonun tür ipuçlarını ve belge dizesini okur, ardından her çağrıyı ona göre doğrular. ```python 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.""" # ctx.deps enjekte edilmiş bağımlılığınızı tutar return await lookup_balance(ctx.deps, account_id) ``` Model, aracı ne zaman çağıracağına karar verir. İşleviniz yalnızca zaten doğrulamayı geçen argümanlarla çalışır.
Bağımlılıklar
Gerçek ajanların bağlama ihtiyacı vardır: bir veritabanı bağlantısı, bir HTTP istemcisi, mevcut kullanıcı, bir API anahtarı. PydanticAI bunu bağımlılık enjeksiyonu ile halleder. Ajana bir `deps_type` tanımlarsınız, ardından araçlar ve dinamik talimatlar içinde `RunContext` aracılığıyla okursunuz. Tüm zincir tür güvenli kalır ve gerçek bağımlılıkları sahteleriyle değiştirebildiğiniz için test etmek kolaylaşır.
Modelden bağımsız sağlayıcılar ve akış
PydanticAI, OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity gibi uzun bir sağlayıcı listesini ve Azure AI Foundry ve Amazon Bedrock gibi bulut seçeneklerini ve kendi barındırılan modelleri destekler. Değişiklik yapmak genellikle model dizesinde tek satırlık bir değişikliktir. Ayrıca, veriler geldikçe uygulanan doğrulama ile yapılandırılmış çıktıyı akışla sunar, böylece tür garantilerinden vazgeçmeden kısmi sonuçları işleyebilirsiniz. Ve ekip aynı zamanda Pydantic Logfire'ı geliştirdiği için gözlemlenebilirlik yerleşiktir: her çalıştırma için izleme, hata ayıklama ve maliyet takibi.
PydanticAI, diğer Python ajan çerçeveleriyle nasıl karşılaştırılır?
Tek bir "en iyi" çerçeve yoktur. Farklı şeyler için optimize edilmişlerdir. İşte PydanticAI'nin nereye oturduğuna dair dürüst bir okuma.
| Ç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 | Bir OpenAI odaklı yığın ve hızlı kurulum |
PydanticAI'nin farkı doğrulama katmanıdır. Ajanınız diğer sistemlere türlenmiş veri besliyorsa, çıktının bir Pydantic modeliyle eşleştiği garantisi, bütün bir çalışma zamanı hatası sınıfını ortadan kaldırır. LangGraph size durum makineleri ve karmaşık akışlar üzerinde daha ince kontrol sağlar. OpenAI Agents SDK, zaten OpenAI'ye bağlıysanız ve ajan devir teslimi ve MCP sunucu desteği gibi özellikler istiyorsanız doğal bir seçimdir. Bunları karıştırıp kullanmak da mümkündür. PydanticAI, daha büyük bir orkestrasyon içinde türlenmiş çıktı katmanı olarak iyi çalışır.
PydanticAI ne zaman kullanılır?
PydanticAI'ye şu durumlarda başvurun: * Ajanınızın çıktısı sadece bir sohbet penceresine değil, koda gidiyor ve biçiminin doğru olması gerekiyor. * Tür denetleyicinizin ve IDE'nizin ajanınızı uçtan uca anlamasını istiyorsunuz. * Kod tabanınızda zaten Pydantic kullanıyorsunuz, bu nedenle model tanımları doğal geliyor. * Sağlayıcı esnekliğine ihtiyacınız var ve modelleri değiştirmek için ajanınızı yeniden yazmak istemiyorsunuz. * Gözlemlenebilirlik önemli ve Logfire'ın yerleşik izlemesi cazip geliyor. Karmaşık dallanmalarla yoğun grafik tabanlı orkestrasyona ihtiyacınız olduğunda başka bir yere bakın; bu durumda bir durum makinesi çerçevesi size daha doğrudan kontrol sağlar.
Ajanınızın arkasındaki API'leri test etme ve taklit etme
Bir PydanticAI ajanı, bağımlı olduğu API'ler kadar güvenilirdir. Her çalıştırma bir LLM sağlayıcısını çağırır ve çoğu kullanışlı ajan, kendi REST uç noktalarınızı veya üçüncü taraf araçları da çağırır. Bu çağrılar, hatalı davranışların, sürpriz maliyetlerin ve şekil uyuşmazlıklarının ortaya çıktığı yerlerdir. PydanticAI, modelin çıktısını doğrular, ancak çağırdığınız yukarı akış araç API'sinin beklediğinizi döndürdüğünü doğrulayamaz.
İşte burada Apidog devreye girer ve bu, çerçeveninkinden farklı bir iştir. Apidog, ajanınızın konuştuğu temel API'leri test ettiğiniz ve taklit ettiğiniz bir API platformudur. Birkaç somut kullanım: * **LLM'yi veya bir araç uç noktasını taklit edin.** Geliştirme sırasında, bir aracı deterministik yanıtlar döndüren bir taklit API'ye yönlendirin. Her test çalıştırmasında token harcamayı durdurur ve yineleme yaparken sağlayıcı hız sınırlarını aşarsınız. * **Yanıt şekillerini onaylayın.** Bir REST uç noktasını bir `@agent.tool` işlevine bağlamadan önce, gerçek yanıtın aracınızın beklediği yapıyla eşleştiğini doğrulamak için API onaylarını kullanın. Bir eksik alanı API katmanında yakalayın, ajanın derinliklerinde değil. * **Anahtarları ortama göre yönetin.** Sağlayıcı anahtarlarını ve temel URL'leri ayrı Apidog ortamlarında tutun, böylece yerel, hazırlık ve CI çalıştırmaları kod değişiklikleri olmadan doğru hedeflere ulaşır. * **LLM uç noktasını doğrudan doğrulayın.** Bir sağlayıcıyı HTTP üzerinden çağırırsanız, ajanınız onlara bağlı olmadan önce kimlik doğrulamasını, akışı ve araç çağırma biçimlerini doğrulamak için Apidog ile ChatGPT API'sini test edebilirsiniz. Apidog ajanlar inşa etmez veya orkestre etmez ve PydanticAI'ye bir alternatif değildir. Ajanınızın çalıştığı API yüzeyini test ettiğiniz ve taklit ettiğiniz tezgahtır. Denemek isterseniz, Apidog'u indirin ve önce araç uç noktalarınızdan birini taklit edin.
Sıkça Sorulan Sorular
PydanticAI ücretsiz ve açık kaynak mı?
Evet. PydanticAI açık kaynaklıdır ve `pip install pydantic-ai` veya `uv add pydantic-ai` komutlarıyla PyPI'dan kurabilirsiniz. Çerçeve bu API'leri sizin adınıza çağırdığı için kullandığınız LLM sağlayıcısı için yine de ödeme yapacaksınız. Geliştirme yaparken bu sağlayıcı maliyetlerini düşük tutmak için, her çalıştırmada canlı modeli kullanmak yerine test sırasında API yanıtlarını taklit edebilirsiniz.
PydanticAI hangi modellerle çalışır?
Sağlayıcıdan bağımsızdır. Belgelerde OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral ve Perplexity'nin yanı sıra Azure AI Foundry ve Amazon Bedrock gibi bulut seçenekleri ve kendi barındırılan modeller listelenir. `Agent` yapıcısına `'anthropic:claude-sonnet-4-6'` veya `'openai:gpt-4o'` gibi bir dize geçirerek bir model seçersiniz ve geçiş genellikle tek satırlık bir değişikliktir.
PydanticAI, LangChain veya LangGraph'tan nasıl farklıdır?
PydanticAI, tür güvenliğine odaklanır: Pydantic modelleriyle desteklenen doğrulanmış yapılandırılmış çıktılar ve doğrulanmış araç argümanları. LangGraph, çok adımlı, dallanan iş akışları için açık durum bilgisi olan grafiklere odaklanır. Önceliğiniz garanti edilmiş çıktı şekilleri ve temiz türlenmiş veri akışı ise, PydanticAI iyi uyar. Karmaşık bir durum makinesi üzerinde ince taneli kontrole ihtiyacınız varsa, bir grafik çerçevesi size daha doğrudan kontroller sağlar.
Kullanmak için Pydantic bilmem gerekiyor mu?
Yardımcı olur, ancak temelleri hızlıca kavrayabilirsiniz. Veri şekillerini `BaseModel`'den türeyen sınıflar olarak tanımlarsınız ve PydanticAI bunları çıktılar ve araç şemaları için kullanır. Python'ı API testi için kullandıysanız veya FastAPI ile çalıştıysanız, zihinsel model tanıdık gelecektir.
Sonuç
PydanticAI, ajan geliştirmeye pratik bir şey getiriyor: modelinizin çıktısının ve araç çağrılarının bildirdiğiniz türlerle eşleştiği garantisi. Bu, gerçek bir üretim hatası kaynağını ortadan kaldırır ve veri akışınızı temiz tutar. Güvenilirlik ve türlenmiş çıktılar, yoğun grafik orkestrasyonundan daha önemli olduğunda bunu seçin. Hangi çerçeveyi seçerseniz seçin, ajanınızın altındaki API'lerin yine de test edilmesi gerekir. LLM'nizi ve araç uç noktalarınızı taklit edin, yanıt şekillerini onaylayın ve Apidog'da anahtarları ortama göre yönetin, böylece ajanınız gerçekten doğruladığınız bir temel üzerinde çalışır.