Pydantic AI: Prodüksiyon Rehberi (Merhaba Dünya'nın Ötesinde)

Pydantic AI: Prodüksiyon Rehberi (Merhaba Dünya'nın Ötesinde)

Ham LLM çıktıları uygulamaları bozar. JSON istiyorsunuz, markdown alıyorsunuz. 1 ile 10 arasında bir sayı istiyorsunuz, "Tabii! İşte bir sayı: yedi" cevabı geliyor. LLM API'larıyla gerçekten bir şeyler geliştirdiyseniz, kariyer seçimlerinizi sorgulamanıza yol açan savunmacı ayrıştırma kodu yazdınız. Pydantic AI bunu düzeltiyor -- Pydantic ve FastAPI'nin arkasındaki aynı ekip tarafından oluşturulan tip güvenli ajan framework'üdür. Bunu "AI ajanlar için FastAPI" olarak düşünün: Python tip ipuçlarıyla ne istediğinizi tanımlıyorsunuz, framework doğrulama, yeniden deneme ve araç çağrılarını hallediyor.

Bu Pydantic AI rehberi, ilk LLM çağrısını yapmış ve prodüksiyon desenlerini isteyen geliştiriciler içindir: bozulmayan yapısal çıktılar, test edilebilir ajanlar için bağımlılık enjeksiyonu ve hava durumu API'larının ötesinde gerçek dünya araçları. Sonunda araçlarla, DI ile, akış ile ve testlerle çalışan ajanlarınız olacak.

Pydantic AI'ya Genel Bakış

Öne çıkan özellikler yapısal çıktılar (Pydantic modelleriyle doğrulanmış), bağımlılık enjeksiyonu (FastAPI'nin Depends'ine benzer) ve TestModel (API çağrısı yapmadan test için sahte LLM). LangChain'den geliyorsanız ve "daha temiz bir şey var mı?" diye soruyorsanız, bu muhtemelen cevaptır.

Kurulum ve İlk Ajan

# OpenAI desteğiyle kurun (openai yerine anthropic, google vb. kullanın)
pip install "pydantic-ai[openai]"

# API anahtarınızı ayarlayın
export OPENAI_API_KEY="sk-..."

5 satırda ilk ajanınız:

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o", system_prompt="You are a helpful assistant.")

result = agent.run_sync("What's the capital of France?")
print(result.output)  # "Paris"

Bu kadar. Agent modeli sarar, run_sync bir prompt gönderir ve sonuç döndürür. result.output burada düz bir string, ama bu değişmek üzere.

Yapısal Çıktılar -- Pydantic AI'nın Varoluş Nedeni

Bu temel özelliktir. LLM'den bir string almak ve bunun geçerli JSON olmasını ummak yerine, bir Pydantic modeli tanımlıyorsunuz ve ajan doğrulanmış bir Python nesnesi döndürüyor.

Önce: Ham LLM Çıktısı

# Eski yol -- en iyisini umin
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Review the movie Inception. Return JSON with title, rating (1-10), summary."}]
)
# response.choices[0].message.content bir stringdir
# Belki JSON'dur. Belki markdown kod çitleri vardır. Belki rating "eight"tir.
# Kendiniz çözün.

Sonra: Pydantic AI ile Yapısal

from pydantic import BaseModel
from pydantic_ai import Agent

class MovieReview(BaseModel):
    title: str
    rating: int  # int olması garanti, "eight" değil
    summary: str
    recommended: bool

agent = Agent("openai:gpt-4o", result_type=MovieReview)

result = agent.run_sync("Review the movie Inception")
review = result.output  # Bu bir MovieReview örneği, string değil

print(f"{review.title}: {review.rating}/10")
print(f"Önerildi: {review.recommended}")
print(review.summary)

Fark gece ile gündüz gibi. result.output gerçek bir MovieReview nesnesidir. LLM rating: 8 yerine rating: "eight" döndürürse, Pydantic'in doğrulaması bunu yakalar. Bunun farklı sağlayıcılarda nasıl çalıştığına daha ayrıntılı bakmak için yapısal çıktılar rehberimize göz atın.

Doğrulama Başarısız Olduğunda Ne Olur

İşte başka hiçbir öğreticinin göstermediği kısım: LLM hata yaptığında ne olur?

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class StrictReview(BaseModel):
    title: str
    rating: int = Field(ge=1, le=10)  # 1-10 arası olmalı
    pros: list[str] = Field(min_length=2)  # En az 2 artı

agent = Agent("openai:gpt-4o", result_type=StrictReview)

# LLM rating=15 veya yalnızca 1 artı döndürürse:
# 1. Pydantic doğrulaması başarısız olur
# 2. Hata mesajı LLM'e GERİ gönderilir
# 3. LLM düzeltilmiş çıktıyla tekrar dener
# 4. Bu yeniden deneme sınırına kadar tekrar eder
result = agent.run_sync("Review the movie Inception")

Bu geri bildirimli yeniden deneme döngüsü, Pydantic AI'nın katil özelliğidir. LLM kendi doğrulama hatalarından öğrenir. Yeniden deneme mantığı yazmazsınız -- framework halleder.

Karar: Yapısal çıktılar, Pydantic AI'yı ham API çağrıları yerine kullanmanın tek en iyi nedenidir. LLM JSON'ını elle ayrıştırıyorsanız, bırakın.

Araçlar ve Fonksiyon Çağrısı

Araçlar, ajanınızın gerçek verileri almak için Python fonksiyonları çağırmasını sağlar. LLM gerçekleri uydurmak yerine veritabanınızı sorgulayabilir, belgelerinizi arayabilir veya bir API çağırabilir.

Araç Kaydetme

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o")

@agent.tool
async def search_docs(query: str) -> str:
    """Search the documentation for relevant articles."""
    # Gerçek arama mantığınız buraya
    results = await doc_search_engine.search(query, limit=5)
    return "\n".join(r.title + ": " + r.snippet for r in results)

@agent.tool dekoratörü fonksiyonu kaydeder. Pydantic AI, LLM'e aracın ne yaptığını, hangi argümanları aldığını ve ne döndürdüğünü söylemek için fonksiyonun tip ipuçlarını ve docstring'ini okur. Manuel şema yazımı yok -- tip ipuçlarınız ŞEMAdir. LLM fonksiyon çağrısının arka planda nasıl çalıştığına dair özel bir rehberimiz var.

RunContext: Araçlara Veri Geçirme

Pydantic AI'nın diğer framework'lerden ayrıldığı yer burasıdır. RunContext, çalışma zamanı verilerini (veritabanı bağlantıları, kullanıcı bilgileri, API istemcileri) global durum olmadan araçlarınıza geçirmenizi sağlar.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class SupportDeps:
    customer_id: str
    db_connection: DatabaseConnection

agent = Agent("openai:gpt-4o", deps_type=SupportDeps)

@agent.tool
async def get_order_history(ctx: RunContext[SupportDeps], limit: int = 5) -> str:
    """Fetch recent orders for the current customer."""
    orders = await ctx.deps.db_connection.query(
        "SELECT * FROM orders WHERE customer_id = $1 ORDER BY date DESC LIMIT $2",
        ctx.deps.customer_id, limit
    )
    return format_orders(orders)

ctx.deps, araca çalışma zamanında geçirdiğiniz her şeye erişim sağlar. Araç global bir veritabanı bağlantısı içe aktarmaz -- bir tane alır. Bu bağımlılık enjeksiyonudur ve ajanlarınızı test edilebilir yapan şeydir.

Gerçek Dünya Araç Örneği

@agent.tool
async def run_sql_query(ctx: RunContext[SupportDeps], sql: str) -> str:
    """Run a read-only SQL query against the analytics database.
    Only SELECT queries are allowed."""
    if not sql.strip().upper().startswith("SELECT"):
        return "Error: only SELECT queries are allowed"
    results = await ctx.deps.db_connection.fetch(sql)
    return json.dumps(results, default=str)

Karar: Pydantic AI'da araç çağrısı, tip ipuçlarının ağır işi yapması sayesinde diğer tüm framework'lerden daha temizdir. Normal Python fonksiyonları yazıyorsunuz ve framework gerisini çözüyor.

Bağımlılık Enjeksiyonu -- LangChain'in Sahip Olmayı Dilediği Özellik

FastAPI'nin Depends'ini kullandıysanız, Pydantic AI'nın DI sistemini zaten anlıyorsunuzdur. Kullanmadıysanız, kısa sürüm şu: ajanınızın ihtiyaç duyduğu şeyleri dışarıya almak yerine (global veritabanı bağlantıları, API istemcileri, yapılandırma), çalışma zamanında her şeyi ona veriyorsunuz.

Bağımlılıkları Tanımlama

from dataclasses import dataclass
from pydantic_ai import Agent

@dataclass
class AppDeps:
    db: AsyncDatabasePool
    search_client: SearchAPIClient
    current_user: User

agent = Agent(
    "openai:gpt-4o",
    deps_type=AppDeps,
    system_prompt="You are a customer support agent."
)

Araçlarda Bağımlılıkları Kullanma

@agent.tool
async def lookup_account(ctx: RunContext[AppDeps]) -> str:
    """Look up the current user's account details."""
    account = await ctx.deps.db.fetchrow(
        "SELECT * FROM accounts WHERE user_id = $1",
        ctx.deps.current_user.id
    )
    return json.dumps(account, default=str)

# Gerçek bağımlılıklarla çalıştır
result = await agent.run(
    "What's my account status?",
    deps=AppDeps(db=real_db, search_client=real_search, current_user=user)
)

DI Ajanlarınızı Neden Test Edilebilir Yapıyor

Gerçek kazanım burada. LangChain'de bağlamı chain kwargs veya closure'lar aracılığıyla geçirirdiniz -- standart bir desen yok. Pydantic AI'da gerçek bağımlılıkları test ikilileriyle değiştirmek önemsizdir:

# Test dosyanızda
from pydantic_ai import Agent
from your_app import agent, AppDeps

async def test_account_lookup():
    mock_deps = AppDeps(
        db=MockDatabase({"user_123": {"status": "active", "plan": "pro"}}),
        search_client=MockSearch(),
        current_user=User(id="user_123")
    )
    result = await agent.run("What's my account status?", deps=mock_deps)
    assert "active" in result.output
    assert "pro" in result.output

Monkey-patching yok. Global içe aktarmaları mock'lama yok. Sadece farklı deps geçiriyorsunuz.

Karar: Bağımlılık enjeksiyonu, deneyimli Python geliştiricilerinin Pydantic AI'yı tercih etmesinin nedenidir. FastAPI etkisinin kendini göstermesi.

Model Sağlayıcıları -- OpenAI, Anthropic, Gemini, Ollama

Pydantic AI model agnostiktir. Sağlayıcı değiştirmek tek satırlık bir değişikliktir:

# OpenAI
agent = Agent("openai:gpt-4o")

# Anthropic
agent = Agent("anthropic:claude-sonnet-4-20250514")

# Google Gemini
agent = Agent("google-gla:gemini-2.0-flash")

# Yerel Ollama
agent = Agent("ollama:llama3.1")

Araçlar, yapısal çıktılar, DI -- her şey aynı kalır. Model değiştirdiğinizde iş mantığınız değişmez.

Karar: Model agnostik tasarım, hiçbir sağlayıcıya kilitli kalmadığınız anlamına gelir. Kolaylık için OpenAI ile başlayın, Anthropic ile karşılaştırın ve yerel geliştirme için Ollama kullanın.

Akış Yanıtları

Sohbet arayüzleri ve gerçek zamanlı uygulamalar için akış şarttır. Pydantic AI, tip güvenliğini korurken akışı destekler:

from pydantic_ai import Agent
from pydantic import BaseModel

class AnalysisResult(BaseModel):
    summary: str
    sentiment: str
    confidence: float

agent = Agent("openai:gpt-4o", result_type=AnalysisResult)

async def stream_analysis(text: str):
    async with agent.run_stream(f"Analyze this text: {text}") as stream:
        async for partial in stream.stream_structured():
            # partial kısmen doğrulanmış bir AnalysisResult'tır
            print(f"Akış: {partial}")

        # Nihai sonuç tamamen doğrulanmış
        result = await stream.get_output()
        print(f"Nihai: {result.summary} (%{result.confidence:.0%} güvenle)")

Bu, FastAPI'nin StreamingResponse'ı ile mükemmel çalışır -- aynı ekosistem, aynı desenler. Pydantic AI ajanlar belgeleri stream_text() ile yalnızca metin akışı da dahil olmak üzere gelişmiş akış seçeneklerini kapsar.

Pydantic AI vs LangGraph vs OpenAI Agents SDK

Buradasınız, yani muhtemelen şunu soruyorsunuzdur: "Pydantic AI mı yoksa LangGraph mı kullanmalıyım?" Dürüst cevap: farklı sorunları çözüyorlar ve ikisini de kullanabilirsiniz.

Özellik Karşılaştırma Tablosu

Her Birini Ne Zaman Kullanmalı

Pydantic AI seçin temiz, tip güvenli ajan kodu istediğinizde. Araçlarla birlikte tek ajan görevleri (müşteri destek botları, veri çıkarma, kod inceleme ajanları) ve test edilebilirliğin önemli olduğu durumlar için idealdir. Ekibiniz zaten FastAPI ve Pydantic kullanıyorsa, öğrenme eğrisi neredeyse düzdür.

LangGraph seçin koşullu dallanma, insan onayıyla döngü ve gelişmiş durum yönetimi içeren karmaşık çok adımlı iş akışlarına ihtiyaç duyduğunuzda. LangGraph bireysel ajan kalitesini değil, birden fazla adımı düzenlemeyi başarır. Derin bir inceleme için tam LangGraph vs CrewAI vs OpenAI Agents SDK karşılaştırmamıza bakın.

OpenAI Agents SDK seçin %100 OpenAI'daydınız, mümkün olan en basit kurulumu istiyorsunuz ve çok sağlayıcı desteğine veya DI'ye ihtiyacınız yok.

Kombinasyon Deseni

Deneyimli ekiplerin gerçekte yaptığı şey: bireysel ajanlar için Pydantic AI kullanmak (temiz kod, test edilebilir, tip edilmiş çıktılar) ve ajanlar arasındaki düzenleme için LangGraph (yönlendirme, durum makineleri, koşullu mantık). Birbirleriyle rekabet etmiyorlar -- tamamlayıcı katmanlar.

# Pydantic AI ajanı -- temiz, test edilebilir, tip güvenli
support_agent = Agent("openai:gpt-4o", result_type=SupportResponse, deps_type=SupportDeps)

# LangGraph grafiği -- hangi ajanı ne zaman çağıracağını düzenler
graph = StateGraph(SupportState)
graph.add_node("classify", classify_intent)
graph.add_node("support", lambda state: support_agent.run_sync(state["query"]))
graph.add_node("escalate", escalate_to_human)

Karar: Temiz, test edilebilir ajan kodu için Pydantic AI seçin. Karmaşık çok adımlı iş akışları için LangGraph seçin. Birbirini dışlamıyorlar.

TestModel ile Ajanlarınızı Test Etme

Bu bölüm, başlangıç kılavuzunu prodüksiyon kılavuzundan ayıran şeydir. Her gerçek kod tabanının testlere ihtiyacı vardır ve ajanları test etmek notoriously zordur -- LLM çağrıları yavaş, pahalı ve deterministik değildir. Pydantic AI bir çözüm sunar: TestModel.

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic import BaseModel

class SupportResponse(BaseModel):
    answer: str
    confidence: float
    escalate: bool

agent = Agent("openai:gpt-4o", result_type=SupportResponse)

# Testlerde: gerçek modeli TestModel ile değiştirin
def test_support_agent():
    with agent.override(model=TestModel()):
        result = agent.run_sync("I need help with billing")
        # TestModel result_type ile eşleşen geçerli yapısal veri döndürür
        assert isinstance(result.output, SupportResponse)
        assert isinstance(result.output.confidence, float)
        assert isinstance(result.output.escalate, bool)

TestModel, result_type'ınızla eşleşen geçerli veriler üretir, API çağrısı yapmadan. Sıfır maliyet, deterministik, hızlı. Pydantic AI test belgeleri özel yanıtlar için FunctionModel ve araç çağrılarını incelemek için capture_run_messages gibi gelişmiş desenleri kapsar.

Araçları ve DI'yi Birlikte Test Etme

def test_order_lookup_tool():
    # Mock bağımlılıklar
    mock_deps = SupportDeps(
        customer_id="test-123",
        db_connection=MockDB(orders=[{"id": "ord-1", "status": "shipped"}])
    )

    with agent.override(model=TestModel()):
        result = agent.run_sync(
            "Where is my order?",
            deps=mock_deps
        )
        assert isinstance(result.output, SupportResponse)

API çağrısı yok. Kararsız testler yok. Maliyet yok. Bunu CI/CD'de diğer test paketinizin yanında çalıştırın.

Bu tüm SERP'teki #1 içerik boşluğudur. Başka hiçbir Pydantic AI kılavuzu testi kapsamıyor. Prodüksiyon için ajanlar geliştiriyorsanız, işte ihtiyacınız olan bu.

Gözlemlenebilirlik -- 5 Dakikada Logfire Entegrasyonu

Prodüksiyon ajanlarına AI gözlemlenebilirliği gerekir. Her LLM çağrısını, araç çağrısını, gecikmeyi, token sayısını ve maliyeti görmek istiyorsunuz. Pydantic AI, Pydantic ekibinin gözlemlenebilirlik platformu olan Logfire ile yerel olarak entegre olur (OpenTelemetry tabanlı).

import logfire
from pydantic_ai import Agent

logfire.configure()  # LOGFIRE_TOKEN ortam değişkenini kullanır
logfire.instrument_pydantic_ai()

agent = Agent("openai:gpt-4o", result_type=MovieReview)
# Her çalıştırma artık otomatik olarak izlenir
result = agent.run_sync("Review Inception")

Üç satır. Tam izleme alıyorsunuz: gönderilen prompt, model yanıtı, araç çağrıları (varsa), doğrulama geçişleri/başarısızlıkları, yeniden denemeler, gecikme ve tahmini maliyet. Logfire sizin için uygun değilse, Langfuse prompt'larınızın nasıl geliştiğini izlemek için bağlam mühendisliği desteğiyle sağlam bir açık kaynak alternatifidir.

SSS

Pydantic AI nedir ve LangChain'den nasıl farklıdır?

Pydantic AI, Python tip ipuçlarının doğrulamayı, araç şemalarını ve bağımlılık enjeksiyonunu yönettiği, tip güvenli bir ajan framework'üdür. LangChain, LLM çağrılarını birbirine zincirlemek için daha büyük bir framework'tür. Temel fark: Pydantic AI çıktıları framework düzeyinde doğrular ve test edilebilirlik için dahili bağımlılık enjeksiyonu sağlar -- LangChain varsayılan olarak hiçbirini yapmaz.

Pydantic AI ile tip güvenli bir AI ajan nasıl oluşturabilirim?

Çıktınız için bir Pydantic BaseModel tanımlayın, Agent'a result_type olarak geçirin ve run_sync() veya run() çağırın. Ajan ham bir string değil, modelinizin doğrulanmış bir örneğini döndürür. Tam örnekler için Yapısal Çıktılar bölümüne bakın.

Prodüksiyon ajanları için Pydantic AI mi yoksa LangGraph mi kullanmalıyım?

Tip güvenliğinin, test edilebilirliğin ve temiz kodun önemli olduğu bireysel ajanlar için Pydantic AI kullanın. Koşullu yönlendirme ile karmaşık çok adımlı iş akışlarını düzenlemek için LangGraph kullanın. Pek çok ekip her ikisini de kullanır -- LangGraph düzenleme katmanı içinde Pydantic AI ajanları.

Pydantic AI araç çağrısını ve bağımlılık enjeksiyonunu nasıl halleder?

Bir fonksiyonu @agent.tool ile dekore edin; Pydantic AI araç şemasını oluşturmak için tip ipuçlarını okur. DI için Agent'ta deps_type ayarlayın ve araçlarda RunContext[YourDeps] kabul edin. Çalışma zamanı bağımlılıkları (DB bağlantıları, API istemcileri) global durum olmadan akar.

Pydantic AI ajanına akış nasıl eklerim?

agent.run() yerine agent.run_stream() kullanın. stream_structured() veya stream_text() aracılığıyla kısmi sonuçlar veren bir asenkron bağlam yöneticisi döndürür. Nihai sonuç hâlâ result_type'ınıza göre tamamen doğrulanmıştır.

Pydantic AI 2026'da prodüksiyon hazır mı?

Evet. Sürüm 1.0, Eylül 2025'te API kararlılık taahhüdüyle yayınlandı. En çok indirilen Python veri doğrulama kütüphanesinin arkasındaki Pydantic ekibi tarafından desteklenmekte olup düzenli güncellemelerle şu anda v1.74.0'dadır.

Pydantic AI'ı Ollama ve yerel modellerle kullanabilir miyim?

Evet. Agent("ollama:llama3.1") kullanın ve Ollama'nın yerel olarak çalıştığından emin olun. Ollama sağlayıcı ek özelliğini kurun: pip install "pydantic-ai[ollama]". Yapısal çıktılar ve araçlar bulut sağlayıcılarıyla aynı şekilde çalışır.

Pydantic AI ajanlarını nasıl test ederim?

TestModel kullanın -- API çağrısı yapmadan result_type'ınızla eşleşen geçerli yapısal veriler üreten bir mock model. Testinizi agent.override(model=TestModel()) ile sarın ve çıktı üzerinde assertion çalıştırın. Tam pytest örnekleri için Test bölümüne bakın.

Pydantic AI FastAPI ile çalışır mı?

Mükemmel. Aynı bağımlılık enjeksiyonu felsefesini paylaşırlar ve aynı ekip tarafından oluşturulmuşlardır. FastAPI endpoint'lerinde Pydantic AI ajanları kullanabilir, aralarında bağımlılık türlerini paylaşabilir ve StreamingResponse üzerinden ajan yanıtlarını akışa alabilirsiniz.

Pydantic AI ile OpenAI Agents SDK arasındaki fark nedir?

Pydantic AI model agnostiktir (OpenAI, Anthropic, Gemini, Ollama vb. ile çalışır), bağımlılık enjeksiyonu, test için TestModel ve Pydantic doğrulaması vardır. OpenAI Agents SDK daha basittir ancak OpenAI modelleriyle kilitlidir ve DI ile dahili testleri yoktur. Esneklik için Pydantic AI; mümkün olan en basit yalnızca OpenAI kurulumu için OpenAI Agents SDK'yı seçin.

Temel Çıkarımlar ve Sonraki Adımlar

Yapısal çıktılara sahip küçük bir ajanla başlayın. Bir araç ekleyin. Bağımlılıklar ekleyin. TestModel ile test yazın. Bu prodüksiyon yoludur -- ve şimdi onu yürümek için ihtiyacınız olan her şeye sahipsiniz.

Resmi Pydantic AI belgeleri ve GitHub deposu daha derine inmek için mükemmeldir. Framework hızla ilerliyor, bu yüzden değişiklik günlüğünü yer imlerine ekleyin.

Kaynaklar

• Pydantic AI -- Resmi Belgeler
• Pydantic AI Bağımlılıklar Belgeleri
• Pydantic AI Test Belgeleri
• Pydantic AI v1 Yayın Duyurusu
• Logfire AI Gözlemlenebilirliği
• pydantic/pydantic-ai -- GitHub Deposu