pydantic/pydantic-ai

</picture>

Dokumentasyon: ai.pydantic.dev

Pydantic AI, Generative AI ile üretim kalitesinde uygulamalar ve iş akışları hızlı, güvenli ve sorunsuz bir şekilde geliştirmenize yardımcı olmak için tasarlanmış bir Python agent framework'üdür.

FastAPI, Pydantic Validation temelinde ve tür ipuçları gibi modern Python özellikleri üzerine inşa edilmiş, yenilikçi ve ergonomik tasarımıyla web geliştirmeyi devrim niteliğinde değiştirdi.

Ancak neredeyse her Python agent framework'ü ve LLM kütüphanesi Pydantic Validation kullanmasına rağmen, Pydantic Logfire'da LLM'leri kullanmaya başladığımızda, aynı hissi veren bir şey bulamadık.

Pydantic AI'ı bir basit amaçla geliştirdik: FastAPI hissiyatını GenAI uygulama ve agent geliştirmeye getirmek.

Neden Pydantic AI kullanmalı

1. Pydantic Ekibi tarafından geliştirildi: Pydantic Validation, OpenAI SDK'sının, Google ADK'nın, Anthropic SDK'sının, LangChain'in, LlamaIndex'in, AutoGPT'nin, Transformers'ın, CrewAI'nın, Instructor'ın ve birçok başka projenin validasyon katmanıdır. Türevini kullanırken neden doğrudan kaynağa gitmeyesiniz? :smiley:

2. Model-agnostik: Neredeyse her modeli ve sağlayıcıyı destekler: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral ve Perplexity; Azure AI Foundry, Amazon Bedrock, Google Cloud, Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks AI, Cerebras, Hugging Face, GitHub, Heroku, Vercel, Nebius, OVHcloud, Alibaba Cloud ve SambaNova. Favori modeliniz veya sağlayıcınız listede yoksa, kolayca özel bir model uygulayabilirsiniz.

3. Kusursuz Gözlemlenebilirlik: Pydantic Logfire ile sıkı entegrasyon sağlar, bu, genel amaçlı OpenTelemetry gözlemlenebilirlik platformumuzda gerçek zamanlı hata ayıklama, evals tabanlı performans izleme ve davranış, tracing ve maliyet takibi için. OTel'i destekleyen bir gözlemlenebilirlik platformunuz varsa, bunu da kullanabilirsiniz.

4. Tamamen Tür Güvenli: IDE'niz veya AI coding agent'ınıza otomatik tamamlama ve tür kontrolü için mümkün olduğunca fazla bağlam sağlamak için tasarlanmış, tüm hata sınıflarını çalışma zamanından yazma zamanına taşıyarak biraz Rust "if it compiles, it works" hissi verir.

5. Güçlü Evals: Oluşturduğunuz agentic sistemlerin performansını ve doğruluğunu sistematik olarak test etme ve değerlendirme yapmanızı sağlar ve performansı Pydantic Logfire'da zaman içinde izleyin.

6. Tasarımı Gereği Genişletilebilir: Tools, hooks, instructions ve model ayarlarını yeniden kullanılabilir birimler halinde paketleyen composable capabilities den agent'ler oluşturun. Web arama, thinking ve MCP için yerleşik capabilities'i kullanın, Pydantic AI Harness capability kütüphanesinden seçin, kendi oluşturun veya üçüncü taraf capability paketlerini yükleyin. Agent'leri tamamen YAML/JSON'de tanımlayın — kod gerekmez.

7. MCP, A2A ve UI: Model Context Protocol, Agent2Agent ve çeşitli UI event stream standartlarını entegre eder, agent'ınıza harici tools ve veriye erişim sağlayarak, diğer agent'lerle birlikte çalışmasını sağlayarak ve akış tabanlı iletişimle etkileşimli uygulamalar oluşturmanızı sağlar.

8. İnsan Müdahalesi Gerektiren Tool Onayı: Belirli tool çağrılarının devam etmeden önce onay gerektirdiğini kolayca belirtir, muhtemelen tool çağrısı argümanlarına, konuşma geçmişine veya kullanıcı tercihlerine bağlı olarak.

9. Dayanıklı Yürütme: Geçici API hataları ve uygulama hataları veya yeniden başlatmalar arasında ilerlemeyi koruyabilen ve uzun çalışan, asynchronous ve insan müdahalesi gerektiren iş akışlarını üretim sınıfı güvenilirlikle yapabilen dayanıklı agent'ler oluşturmanızı sağlar.

10. Akışlı Çıktılar: Yapılandırılmış çıktıyı sürekli akışlama yeteneği sağlar, anında validasyon ile, üretilen veriye gerçek zamanlı erişim sağlar.

11. Graph Desteği: Tür ipuçlarını kullanarak graph'ları tanımlamanın güçlü bir yolunu sağlar, standart kontrol akışının spagetti koduna dönüşebileceği karmaşık uygulamalar için.

Gerçekçi olarak, hiçbir liste deneyen ve size nasıl hissettirdiğini gören kadar ikna edici olmayacaktır!

Hello World Örneği

İşte Pydantic AI'ın minimal bir örneği:

from pydantic_ai import Agent

# Kullanılacak modeli de içeren çok basit bir agent tanımlayın, agent'i çalıştırırken modeli de ayarlayabilirsiniz.
agent = Agent(
    'anthropic:claude-sonnet-4-6',
    # Agent'e bir keyword argümanı kullanarak statik instructions kaydedin.
    # Daha karmaşık dinamik olarak üretilen instructions için aşağıdaki örneğe bakın.
    instructions='Be concise, reply with one sentence.',
)

# Agent'i senkron olarak çalıştırın, LLM ile konuşma yapın.
result = agent.run_sync('Where does "hello world" come from?')
print(result.output)
"""
The first known use of "hello, world" was in a 1974 textbook about the C programming language.
"""

(Bu örnek tamamlanmıştır, "olduğu gibi" çalıştırılabilir, pydantic_ai paketini yüklediğinizi varsayarak)

Değişim çok kısa olacaktır: Pydantic AI instructions ve user prompt'u LLM'e gönderecek ve model bir metin response döndürecek.

Henüz çok ilginç değil, ancak tools, dynamic instructions, structured outputs veya composable capabilities ekleyerek kolayca daha güçlü agent'ler oluşturabiliriz.

İşte aynı agent thinking ve web search capabilities'i ile:

from pydantic_ai import Agent
from pydantic_ai.capabilities import Thinking, WebSearch

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='Be concise, reply with one sentence.',
    capabilities=[Thinking(), WebSearch()],
)

result = agent.run_sync('What was the mass of the largest meteorite found this year?')
print(result.output)

Tools & Dependency Injection Örneği

İşte bir banka için destek agent'i oluşturmak için Pydantic AI'ı kullanarak kısa bir örnek:

(Daha iyi belgelendirilmiş örnek docs'da)

from dataclasses import dataclass

from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

from bank_database import DatabaseConn


# SupportDependencies, çalıştırırken gereken veriler, bağlantılar ve mantığı modele iletmek için kullanılır
# instructions ve tool fonksiyonları. Dependency injection, agent'lerinizin davranışını tür güvenli bir şekilde özelleştirmenin bir yoludur.
@dataclass
class SupportDependencies:
    customer_id: int
    db: DatabaseConn


# Bu Pydantic modeli, agent tarafından döndürülen çıktının yapısını tanımlar.
class SupportOutput(BaseModel):
    support_advice: str = Field(description='Advice returned to the customer')
    block_card: bool = Field(description="Whether to block the customer's card")
    risk: int = Field(description='Risk level of query', ge=0, le=10)


# Bu agent bir bankada birinci seviye destek olarak hareket edecektir.
# Agent'ler, kabul ettikleri dependencies türü ve döndürdükleri çıktı türü için geneldir.
# Bu durumda, destek agent'ı `Agent[SupportDependencies, SupportOutput]` türündedir.
support_agent = Agent(
    'openai:gpt-5.2',
    deps_type=SupportDependencies,
    # Agent'den gelen response, SupportOutput olması garantilidir,
    # validasyon başarısız olursa agent tekrar denemeye istenir.
    output_type=SupportOutput,
    instructions=(
        'You are a support agent in our bank, give the '
        'customer support and judge the risk level of their query.'
    ),
)


# Dinamik instructions, dependency injection'ı kullanabilir.
# Dependencies, yukarıdaki `deps_type`'la parametreleştirilen `RunContext` argümanı aracılığıyla taşınır.
# Buradaki tür ek açıklaması yanlışsa, statik tür denetleyicileri bunu yakalayacaktır.
@support_agent.instructions
async def add_customer_name(ctx: RunContext[SupportDependencies]) -> str:
    customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id)
    return f"The customer's name is {customer_name!r}"


# `tool` dekoratörü, LLM'in bir kullanıcıya yanıt verirken çağırabileceği fonksiyonları kaydetmeyi sağlar.
# Yine, dependencies `RunContext` aracılığıyla taşınır, diğer argümanlar LLM'e iletilen tool schema'sı olur.
# Pydantic bu argümanları validate etmek için kullanılır ve hatalar LLM'e geri iletilir, böylece yeniden deneyebilir.
@support_agent.tool
async def customer_balance(
        ctx: RunContext[SupportDependencies], include_pending: bool
) -> float:
    """Returns the customer's current account balance."""
    # Bir tool'un docstring'i, LLM'e tool'un açıklaması olarak da iletilir.
    # Parametre açıklamaları docstring'den çıkarılır ve LLM'e gönderilen parametre schema'sına eklenir.
    balance = await ctx.deps.db.customer_balance(
        id=ctx.deps.customer_id,
        include_pending=include_pending,
    )
    return balance


...  # Gerçek bir kullanım durumunda, daha fazla tool ve daha uzun bir sistem prompt eklerdiniz


async def main():
    deps = SupportDependencies(customer_id=123, db=DatabaseConn())
    # Agent'i asenkron olarak çalıştırın, final response'a ulaşılıncaya kadar LLM ile konuşma yapın.
    # Bu oldukça basit durumda bile, agent bir output almak için tools çağrılırken LLM ile birçok mesaj değiştirecektir.
    result = await support_agent.run('What is my balance?', deps=deps)
    # `result.output`, `SupportOutput` olduğunu garantilemek için Pydantic ile validate edilecektir. Agent genellik içinde olduğundan,
    # statik tür kontrolüne yardımcı olmak için `SupportOutput` olarak da türlenecektir.
    print(result.output)
    """
    support_advice='Hello John, your current account balance, including pending transactions, is $123.45.' block_card=False risk=1
    """

    result = await support_agent.run('I just lost my card!', deps=deps)
    print(result.output)
    """
    support_advice="I'm sorry to hear that, John. We are temporarily blocking your card to prevent unauthorized transactions." block_card=True risk=8
    """

Sonraki Adımlar

Pydantic AI'ı kendiniz denemek için, kurun ve örneklerdeki talimatları izleyin.

Pydantic AI ile uygulama oluştturma hakkında daha fazla bilgi edinmek için docs'u okuyun.

Pydantic AI'ın arayüzünü anlamak için API Reference'ı okuyun.

Herhangi bir sorunuz varsa Slack'a katılın veya GitHub'da bir issue açın.