Pydantic AI: Uygulamalı Örneklerle Yeni Başlayanlar İçin Kılavuz

Yapay zekâ destekli uygulamalar geliştirmek çoğu zaman yapılandırılmamış çıktılara, tür uyumsuzluklarına ve üretimde güvenilirlik sorunlarına yol açar. LLM’leri Python uygulamalarına entegre etmenin geleneksel yaklaşımları, üretim sistemleri için gereken yapı ve doğrulamadan yoksundur. Pydantic AI, Pydantic’in veri doğrulamasını LLM etkileşimleri için bir ajan çerçevesiyle birleştirerek bunu çözer.

Bu eğitimde, doğrulanmış çıktılar üreten ve tür güvenliğini koruyan yapılandırılmış yapay zekâ ajanları oluşturmayı öğreneceksiniz. Sistem komutlarıyla ajan kurulumunu, sohbet sırasında LLM’lerin çağırabileceği fonksiyon araçları (tools) oluşturmayı ve yapılandırılmış çıktı doğrulamasını uygulamayı ele alacağız. Ayrıca, ajan bileşenleri arasında bağımlılıkları nasıl yöneteceğinizi ve gerçek zamanlı uygulamalar için yanıtları nasıl akışla ileteceğinizi keşfedeceksiniz. Sonunda, karmaşık iş akışlarını yöneten yapay zekâ uygulamaları geliştirme konusunda pratik deneyim kazanmış olacaksınız.

Eğer ajan temelli yapay zekâ sistemleri kurmaya yönelik uygulamalı bir kurs arıyorsanız, LangGraph ile Çoklu Ajan Sistemleri Oluşturma kursunu öneririm. 

Pydantic AI nedir?

Pydantic AI, LLM uygulamalarına yapı ve tür güvenliği getiren bir Python ajan çerçevesidir. Ham metin döndüren basit LLM entegrasyonlarının aksine, Pydantic AI yapay zekâ etkileşimlerini doğrulanmış girdi ve çıktılara sahip yapılandırılmış sohbetler olarak ele alır; bu da güvenilir uygulamalar oluşturmayı kolaylaştırır.

Öne çıkan özellikler ve faydalar:

• Yapılandırılmış çıktı doğrulaması — Yapay zekâ yanıtlarınız otomatik olarak Pydantic modellerine uyar; ayrıştırma hatalarını önler ve veri tutarlılığını sağlar
• Fonksiyon araçları — LLM’ler, sohbet sırasında Python fonksiyonlarınızı çağırarak gerçek verilere ve hesaplamalara erişebilir
• Tür güvenliği — Tam tipleme desteği, çalışma zamanı hatalarını azaltır ve karmaşık yapay zekâ iş akışları kurarken IDE desteğini iyileştirir
• Sistem komutları — Ajanlarınız için tüm etkileşimlerde tutarlı kalan net talimatlar tanımlayın
• Bağımlılık enjeksiyonu — Bağlamı, veritabanı bağlantılarını ve kullanıcı tercihlerini tüm ajan bileşenleri arasında temiz biçimde paylaşın
• Birden çok yürütme modu — İhtiyaçlarınıza göre ajanları eşzamanlı, eşzamansız çalıştırın veya gerçek zamanlı yanıtları akışla iletin
• Ajan yeniden kullanılabilirliği — Ajanları bir kez oluşturup uygulamanız genelinde, FastAPI router’larına benzer şekilde, yeniden kullanın

Bu yaklaşım, yapay zekâyı öngörülemeyen metin üretiminden, mevcut Python uygulamalarına doğal biçimde uyan güvenilir, tipleştirilmiş etkileşimlere dönüştürür. İstem mühendisliği ve çıktı ayrıştırmayla boğuşmak yerine, kullanıcılarınızın ihtiyaç duyduğu gerçek işlevleri geliştirmeye odaklanabilirsiniz.

Önkoşullar

Bu eğitime başlamadan önce birkaç şeye ihtiyacınız olacak:

Gerekli bilgi:

• Python temelleri : Sınıflar ve fonksiyonlarla rahat olun
• Python’da eşzamansız programlama temelleri
• Pydantic temelleri : Modelleri, alan doğrulamasını ve tür açıklamalarını anlayın
• LLM aşinalığı :  Dil modellerinin nasıl çalıştığına dair temel bilgi ve istemlerin ne olduğuna dair fikir

Faydalı ama zorunlu değil:

• Ajan kavramları :  Yapay zekâ ajanlarına ve tool calling’e biraz aşinalık; yine de burada ele alacağız

Kurulum gereksinimleri:

• Python 3.9 veya üzeri
• OpenAI ve Anthropic API anahtarları
• Paket kurulumu için temel terminal/komut satırı becerileri

Pydantic’e yeniyseniz, onların resmî dokümantasyonu temelleri iyi kapsar. LLM temelleri için, ChatGPT veya benzeri modellere giriş niteliğindeki herhangi bir kılavuz bu içeriği takip etmek için yeterli arka planı sağlayacaktır.

Pydantic AI ile Başlarken

Bu eğitim boyunca, farklı bölge ve ürünlerdeki satış performansını anlamamıza yardımcı olacak bir veri analizi ajanı oluşturacağız. Bu ajan basit başlayacak ve özel araçlar, yapılandırılmış çıktılar ve akış yetenekleri gibi özellikler ekledikçe daha da gelişmiş hale gelecek.

Kurulum ve yapılandırma

Koda dalmadan önce, Pydantic AI’yi kuralım ve ortamımızı hazırlayalım:

pip install pydantic-ai

Ayrıca hem bir OpenAI hem de bir Anthropic API anahtarına ihtiyacınız olacak. Bunları ortam değişkeni olarak ayarlayın:

export OPENAI_API_KEY="your-api-key-here"export ANTHROPIC_API_KEY="your-api-key-here"

> Pydantic AI’de bazı özellikler birinde desteklenip diğerinde desteklenmediği için hem OpenAI hem de Anthropic modellerini kullanacağız.

Veri analizi örneklerimiz için, veri işleme amacıyla pandas’ı da kullanacağız:

pip install pandas

İlk ajanınızı oluşturma

En basit ajanla başlayalım — satış verileri hakkında temel soruları yanıtlayabilen bir ajan. Pydantic AI’de bir ajan, LLM etkileşimleri için ana arayüzünüzdür (aşağıdaki kodu bir Python betiğinde çalıştırın):

from pydantic_ai import Agent# Create a basic sales analysis agentsales_agent = Agent(   'openai:gpt-4o',   system_prompt=(       "You are a data analyst specializing in sales performance. "       "Provide clear, actionable insights based on the data provided."   ))# Run the agent with a simple questionresult = sales_agent.run_sync("What are the key metrics I should track for sales performance? Answer in two sentences.")print(result.output)

Çıktı:

Key metrics to track for sales performance include conversion rate, which measures the percentage of leads that result in sales, and average deal size, indicating the average revenue earned per transaction. Additionally, monitoring customer acquisition cost (CAC) and customer lifetime value (CLV) helps evaluate the efficiency and profitability of sales efforts.

Bu, rolünü satış analisti olarak anlayan ve ilgili tavsiyeler sunabilen bir ajan oluşturur. system_prompt LLM’e nasıl yanıtlar istediğinize dair bağlam verirken, run_sync() ajanı çalıştırır ve bir sonuç döndürür.

Burada run_sync() fonksiyonu yalnızca Python betiklerinde çalışır. Ajanları bir Jupyter Notebook’ta çalıştırmak için şu söz dizimini kullanabilirsiniz:

result = await agent.run("...")print(result.output)

LLM’i ve ayarlarını değiştirme

Pydantic AI birden çok LLM sağlayıcısını destekler ve model davranışını özelleştirmenize izin verir. Farklı seçeneklerle şöyle denemeler yapabilirsiniz:

# Creating agents with different modelsclaude_agent = Agent('anthropic:claude-3-5-sonnet-20241022', system_prompt="You are a sales analyst.")gpt_mini_agent = Agent('openai:gpt-4o-mini', system_prompt="You are a sales analyst.")

Her model, veri analizi iş akışınıza farklı yetenekler katar. Claude modelleri ayrıntılı akıl yürütme ve karmaşık analizlerde başarılıdır; satış verilerinizden kapsamlı içgörüler gerektiğinde idealdir. GPT-4o-mini ise daha hızlı yanıtlar ve daha düşük maliyet sunar; hızlı sorular veya çok sayıda sorgunun işlendiği durumlar için uygundur.

Farklı modelleri seçmenin ötesinde, model ayarlarını kullanarak davranışlarını ince ayar yapabilirsiniz:

# Add model-specific settingsconfigured_agent = Agent(   'openai:gpt-4o',   system_prompt="You are a sales analyst.",   model_settings={       'temperature': 0.3,  # More focused, less creative responses       'max_tokens': 500,   # Limit response length   })

Özelleştirebileceğiniz model ayarları:

• temperature — Yaratıcılığı kontrol eder (0.0 = odaklı, 1.0 = yaratıcı)
• max_tokens — Yanıt uzunluğunu sınırlar
• top_p — Rastgeleliği kontrol etmek için temperature’a alternatif

Veri analizi görevleri için düşük temperature değerleri (0.1–0.3) genellikle daha iyi sonuç verir; çünkü yaratıcı yorumlar yerine tutarlı ve olgusal yanıtlar istersiniz. max_tokens ayarlamak, yanıt uzunluğunu kontrol etmeye yardımcı olur; bu da kısa özetler gerektiğinde veya API maliyetleri konusunda endişeleriniz olduğunda kullanışlıdır.

Ajanlarda Araç Kullanımı

Şu ana kadar satış analizi ajanımız yalnızca istemlerimizde verdiğimiz bilgilerle çalışabiliyor. Oysa gerçek veri analizi çoğu zaman harici bilgilere erişmeyi, hesaplamalar yapmayı veya iş sistemlerine bağlanmayı gerektirir. İşte burada araçlar devreye girer — ajanınıza sohbet sırasında eyleme geçme ve bilgi toplama yeteneği kazandırırlar.

Yerleşik araçlar

Yerleşik araçlar, LLM sağlayıcıları tarafından sunulan kullanıma hazır fonksiyonlardır. Pydantic AI, sağlayıcının altyapısında doğrudan çalışan web araması ve kod yürütme araçlarını destekler.

Güncel pazar bilgisi almak için ideal olan web aramasıyla başlayalım:

from pydantic_ai import Agent, WebSearchTool# Create an agent with web search abilitiesmarket_research_agent = Agent(   'anthropic:claude-3-5-sonnet-20241022',   builtin_tools=[WebSearchTool()],   system_prompt=(       "You are a sales analyst. Use web search to find current information. "       "Keep responses to 3-4 sentences maximum."   ))# Get current market informationresult = market_research_agent.run_sync(   "Search for 2025 laptop sales trends and average selling prices. Give me the main trends.")print(result.output)

Let me search for current laptop sales trends.Based on the search results, here are the key laptop market trends for 2025:…

Bu, veri analizini eski bilgilerle çalışmaktan çıkarıp gerçek zamanlı pazar verilerini dahil etmeye dönüştürür. Ajanınız artık yalnızca veriyi analiz etmekle kalmaz, şirketinizin performansını güncel sektör trendleriyle karşılaştırabilir.

Şimdi de matematiksel analiz ve veri işleme için kod yürütmeyi ekleyelim:

from pydantic_ai import Agent, CodeExecutionTool# Agent that can run calculations and data analysiscalculation_agent = Agent(   'anthropic:claude-sonnet-4-0',   builtin_tools=[CodeExecutionTool()],   system_prompt=(       "You are a data analyst. Use code to perform calculations and create visualizations. "       "Show your work and provide clear explanations."   ))# Analyze sales data with calculationsresult = calculation_agent.run_sync("""I have sales data for Q1 2025:- North region: 150 laptops at $1,500 each, 320 phones at $500 each- South region: 89 laptops at $1,500 each, 245 phones at $500 each - East region: 201 laptops at $1,500 each, 180 phones at $500 each- West region: 167 laptops at $1,500 each, 290 phones at $500 eachCalculate total revenue by region and create a simple chart showing the results.""")print(result.output)```plaintext## SummaryBased on the Q1 2025 sales data analysis, here are the key findings:**Total Revenue by Region:**- **West Region**: $395,500 (highest)- **East Region**: $391,500- **North Region**: $385,000- **South Region**: $256,000 (lowest)

Kod yürütme, basit metin yanıtlarının ötesine geçerek gerçek hesaplamalı analize olanak tanır. Ajanınız artık karmaşık hesaplamalar yapabilir, görselleştirmeler oluşturabilir ve yalnızca sohbetle mümkün olmayan verileri işleyebilir. Sonuç nesnesi, hem ajanın analizini hem de kod yürütme sırasında üretilen dosyaları içerir; bunları indirip daha sonra kullanabilirsiniz.

Özel araçlar yazma

Yerleşik araçlar faydalıdır, ancak çoğu zaman belirli iş sistemlerinizle çalışan özel araçlara ihtiyaç duyarsınız. Özel araçlar, ajanınızın sohbet sırasında çağırabileceği Python fonksiyonlarıdır.

Sık kullanılan satış metriklerini hesaplayan araçlar oluşturalım:

from pydantic_ai import Agent# Create an agent with custom business toolssales_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt=(       "You are a sales analyst. Use tools to calculate metrics and analyze business data. "       "Give concise answers in 3-4 sentences maximum."   ))@sales_agent.tool_plaindef calculate_conversion_rate(leads: int, sales: int) -> str:   """Calculate conversion rate from leads to sales."""   if leads == 0:       return "Cannot calculate conversion rate: no leads provided"     conversion_rate = (sales / leads) * 100   return f"Conversion rate: {conversion_rate:.2f}% ({sales} sales from {leads} leads)"@sales_agent.tool_plaindef calculate_average_order_value(total_revenue: float, total_orders: int) -> str:   """Calculate average order value."""   if total_orders == 0:       return "Cannot calculate AOV: no orders provided"     aov = total_revenue / total_orders   return f"Average Order Value: ${aov:.2f} (${total_revenue:,.0f} revenue from {total_orders} orders)"# Use the custom toolsresult = sales_agent.run_sync(   "Calculate conversion rate for 500 leads that resulted in 75 sales, and AOV for $180,000 revenue from 120 orders")print(result.output)

Your conversion rate is 15.00%, meaning you're successfully converting 75 out of every 500 leads into sales. The average order value is $1,500.00, indicating strong revenue per transaction. These metrics suggest effective sales processes with high-value customers, though there's room to improve lead conversion rates.

Bu özel araçlar, işletmenizin düzenli olarak kullandığı belirli satış hesaplamalarını gerçekleştirir. Dönüşüm oranı aracı pazarlama performansını ölçmeye yardımcı olurken, ortalama sipariş değeri aracı müşteri harcama eğilimlerini izler. Özel araçlar, ajanınızı belirli iş mantığınız ve sistemlerinizle buluşturur.

Bağımlılık enjeksiyonu ve hata yönetimi dâhil daha gelişmiş araç desenleri için kapsamlı araç dokümantasyonuna göz atın.

Yapılandırılmış Çıktılar Kullanma

Şimdiye kadar ajanlarımız düz metin yanıtları döndürdü; bu keşif için iyi çalışsa da üretim uygulamalarında sorun çıkarır. Ajan yanıtlarını programatik olarak işlemeniz, belirli veri noktalarını ayrıştırmanız veya yapay zekâ çıktısını diğer sistemlerle entegre etmeniz gerektiğinde, garantili bir yapıya ihtiyaç vardır.

Diyelim ki satış verilerini analiz etmek ve her seferinde belirli metrikleri geri almak istiyorsunuz. Düz metinle, yapay zekâ her defasında farklı formatlar döndürebilir. Yapılandırılmış çıktılarla, tam olarak ne istediğinizi tanımlarsınız:

from pydantic import BaseModelfrom pydantic_ai import Agentclass SalesInsight(BaseModel):   total_revenue: float   best_performing_region: str   worst_performing_region: str   recommendation: str# Create an agent that returns structured analysisanalysis_agent = Agent(   'anthropic:claude-sonnet-4-0',   output_type=SalesInsight,   system_prompt="Analyze sales data and provide structured insights with clear recommendations.")# Get structured analysisresult = analysis_agent.run_sync("""Q1 2025 sales data:- North: $385,000 revenue (470 units)- South: $256,000 revenue (334 units) - East: $391,500 revenue (381 units)- West: $395,500 revenue (457 units)Analyze this data and provide insights.""")print(f"Total Revenue: ${result.output.total_revenue:,.0f}")print(f"Best Region: {result.output.best_performing_region}")print(f"Recommendation: {result.output.recommendation}")

Total Revenue: $1,428,000Best Region: WestRecommendation: Focus on improving South region performance through targeted marketing and sales training, as it significantly underperforms with only $256,000 revenue. The West region's success ($395,500) should be analyzed and replicated across other regions. Additionally, investigate why East region has the lowest average selling price per unit ($1,028) compared to West's highest ($865) - there may be pricing strategy opportunities.

output_type=SalesInsight parametresine dikkat edin. Bu, ajana tam olarak bu dört alana sahip bir SalesInsight nesnesi döndürmesi gerektiğini söyler. Ne eksik, ne fazla. Sonuç result.output olarak geri gelir ve otomatik olarak doğrulanır ve tipleştirilir.

Yapılandırılmış çıktılar, Pydantic modelinizi LLM’in takip ettiği bir JSON şemasına dönüştürerek çalışır. Yapay zekâ yapınızdan sapamaz — farklı bir şey döndürmeye çalışırsa, Pydantic AI ondan yeniden denemesini ister.

Daha karmaşık analiz senaryoları için modelleri iç içe yerleştirebilir ve listeler kullanabilirsiniz:

from typing import Listfrom pydantic import BaseModelclass RegionalMetrics(BaseModel):   region: str   revenue: float   units_sold: int   average_price: float   performance_rating: str  # "excellent", "good", "needs_improvement"class ComprehensiveAnalysis(BaseModel):   total_revenue: float   total_units: int   regional_breakdown: List[RegionalMetrics]   top_performer: str   areas_for_improvement: List[str]   quarterly_grade: str# Agent with detailed structured outputdetailed_agent = Agent(   'anthropic:claude-sonnet-4-0',   output_type=ComprehensiveAnalysis,   system_prompt=(       "Provide comprehensive sales analysis with detailed regional metrics. "       "Rate each region's performance and give an overall quarterly grade (A-F)."   ))result = detailed_agent.run_sync("""Analyze Q1 2025 performance:- North: $385k revenue, 470 units- South: $256k revenue, 334 units- East: $391.5k revenue, 381 units - West: $395.5k revenue, 457 units""")# Access structured datafor region in result.output.regional_breakdown:   print(f"{region.region}: {region.performance_rating} (${region.average_price:.2f} avg price)")print(f"Quarterly Grade: {result.output.quarterly_grade}")

North: B ($819.15 avg price)South: C ($766.47 avg price)East: A ($1027.56 avg price)West: A- ($865.43 avg price)Quarterly Grade: B+

Bu yaklaşım, yapay zekâyı öngörülemeyen metin üretiminden güvenilir veri işlemeye dönüştürür. Her bölgesel metriği bir veritabanında saklayabilir, performans derecelerine göre uyarılar tetikleyebilir veya yönetici panolarını otomatik olarak oluşturabilirsiniz. Regex ayrıştırma yok, farklı yanıt formatlarıyla uğraşma yok — her seferinde temiz, doğrulanmış veri.

output_type parametresi herhangi bir Pydantic modelini, Python dataclass’ını, TypedDict’i veya int ya da list[str] gibi basit türleri kabul eder. Veri analizi iş akışları için bu, yapay zekâ analizinin doğrudan mevcut iş sistemlerinize beslenebildiği güvenilir boru hatları kurabileceğiniz anlamına gelir.

Pydantic Ajanlarında Mesajlar ve Sohbet Geçmişi

Veri analizi ajanlarıyla çalışırken, çoğu zaman birden fazla etkileşime yayılan sohbetlere ihtiyaç duyarsınız. Belki satış trendlerini sormakla başlar, ardından belirli bölgelere derinleşmek veya farklı dönemleri karşılaştırmak istersiniz. Mesajlar ve sohbet geçmişi bu sohbetler boyunca bağlamı korumanıza olanak tanır.

Mesaj geçmişine erişim

Her ajanı çalıştırdığınızda, Pydantic AI tüm sohbetin kaydını tutar. Neler olduğunu anlamak veya daha sonra sohbete devam etmek için bu geçmişe erişebilirsiniz:

from pydantic_ai import Agent# Create our sales analysis agentsales_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt="You are a sales analyst. Provide clear, concise analysis.")# First questionresult1 = sales_agent.run_sync("What are the main KPIs I should track for Q1 2025 sales?")print(result1.output)# Access the conversation historyall_messages = result1.all_messages()print(f"Total messages in conversation: {len(all_messages)}")# Just the new messages from this runnew_messages = result1.new_messages()print(f"New messages from this run: {len(new_messages)}")

Here are the essential KPIs to track for Q1 2025 sales:...Total messages in conversation: 2New messages from this run: 2

all_messages() yöntemi size her şeyi verir - sistem komutları, kullanıcı soruları ve ajan yanıtları. new_messages() yöntemi ise yalnızca mevcut çalıştırmada olanları döndürür. Bu, daha uzun sohbetler kurarken nelerin değiştiğini izlemek için kullanışlıdır.

Sohbet geçmişiyle konuşmaları sürdürme

Önceki sohbetlerin üzerine inşa etmek için, mesaj geçmişini bir sonraki ajan çalıştırmasına iletin. Bu, ajanın daha önce ne konuştuğunuzu hatırlamasını sağlar:

# Continue the conversation from where we left offresult2 = sales_agent.run_sync(   "How should I calculate conversion rates for each of those KPIs?",   message_history=result1.all_messages())print(result2.output)# The agent now has context from both interactionsprint(f"Full conversation length: {len(result2.all_messages())}")# Ask a follow-up that references the entire conversationresult3 = sales_agent.run_sync(   "Which of these metrics would be most important for a monthly executive report?",   message_history=result2.all_messages())print(result3.output)

Her yeni çalıştırma önceki bağlamın üzerine eklenir. Ajan yalnızca sorularınızı değil, kendi önceki yanıtlarını da hatırlar; böylece tutarlı bir analitik sohbet oluşur.

Mesajları JSON olarak saklama ve yükleme

Daha uzun süreli saklama veya sistemler arasında sohbet paylaşımı için mesaj geçmişini JSON’a serileştirebilirsiniz:

import json# Get the conversation as JSONconversation_json = result3.all_messages_json()# Save to filewith open('sales_analysis_conversation.json', 'w') as f:   f.write(conversation_json.decode('utf-8'))print("Conversation saved to JSON file")# Load it back laterwith open('sales_analysis_conversation.json', 'r') as f:   loaded_conversation = f.read()# You can now use this loaded conversation in a new agent run# (Note: You'd need to convert back from JSON to message objects for actual use)print(f"Loaded conversation size: {len(loaded_conversation)} characters")

all_messages_json() yöntemi, sohbeti JSON baytları olarak döndürür; veritabanlarına kaydetmek, API’ler üzerinden göndermek veya analiz oturumlarını arşivlemek için idealdir. Yalnızca sohbetin en son bölümünü kaydetmek istiyorsanız new_messages_json() da vardır.

Bu yaklaşım kalıcı analitik iş akışları kurmanızı sağlar. Her müşterinin analiz oturumunu kaydedebilir, karmaşık veri incelemelerine günler boyunca kaldığınız yerden devam edebilir veya aynı analizi yürüten farklı ekip üyeleri arasında sohbet bağlamını paylaşabilirsiniz.

Görseller ve Belgelerle Çalışma

Gerçek veri analizi çoğu zaman yalnızca metin ve sayılardan ibaret değildir. Raporlardaki grafikleri analiz etmeniz, PDF’lerden veri çıkarmanız veya grafik ve görselleştirmeleri yorumlamanız gerekebilir. Pydantic AI, görsel ve belge girdisini destekler; böylece ajanlarınız bu zengin veri kaynaklarıyla doğrudan çalışabilir.

URL’lerden görsel analiz etme

Çevrimiçi barındırılan grafikleriniz veya görselleştirmeleriniz olduğunda, ajanınızı doğrudan onlara yönlendirebilirsiniz:

from pydantic_ai import Agent, ImageUrl# Create an agent that can analyze visual datavisual_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt="You are a data analyst who can interpret charts, graphs, and business documents.")# Analyze a sales chart from a URLresult = visual_agent.run_sync([   "What are the main trends shown in this sales chart? Give me 3 key takeaways.",   ImageUrl(url='https://example.com/q1-sales-chart.png')])print(result.output)

Ajan, grafik türlerini tanımlayabilir, eksenlerden değerler okuyabilir, eğilimleri tespit edebilir ve aynı görselle bakarken bir insan analistin sunacağı iş içgörülerini sağlayabilir.

Yerel görsellerle çalışma

Yerel olarak saklanan görseller için — BI araçlarınızdan ekran görüntüleri veya Excel’den dışa aktarılan grafikler gibi — BinaryContent kullanın:

from pathlib import Pathfrom pydantic_ai import Agent, BinaryContent# Load a local sales dashboard screenshotdashboard_path = Path('sales_dashboard_jan_2025.png')result = visual_agent.run_sync([   "Analyze this sales dashboard. What metrics need attention based on what you see?",   BinaryContent(       data=dashboard_path.read_bytes(),       media_type='image/png'   )])print(result.output)

Bu yaklaşım, otomatik raporlama iş akışları için harikadır. Panolarınızın ekran görüntülerini programlı olarak alabilir, ardından görsellere eşlik edecek yazılı analizleri yapay zekânın üretmesini sağlayabilirsiniz.

URL’lerden belgelerle çalışma

Birçok iş belgesi URL’ler üzerinden paylaşılır — şirket intranetlerindeki raporlar, bulut depolamadaki PDF’ler veya analizinizi bilgilendiren herkese açık araştırma makaleleri gibi:

from pydantic_ai import Agent, DocumentUrl# Create an agent for document analysisdoc_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt="Extract and summarize business-relevant insights from documents.")# Analyze a quarterly report PDFresult = doc_agent.run_sync([   "Read this quarterly earnings report and summarize the revenue trends and outlook.",   DocumentUrl(url='https://company.com/reports/q1-2025-earnings.pdf')])print(result.output)

Ajan, tüm belgeyi okuyabilir, ilgili veri noktalarını çıkarabilir ve insanların çok daha uzun sürede derleyebileceği özetleri sunabilir.

Yerel belgeleri işleme

Yerel sisteminizdeki belgeler için — dışa aktarılan raporlar, sözleşmeler veya iç sunumlar gibi — BinaryContent kullanın:

from pathlib import Pathfrom pydantic_ai import Agent, BinaryContent# Load a local Excel export saved as PDFreport_path = Path('monthly_sales_analysis_jan_2025.pdf')result = doc_agent.run_sync([   "Extract the key performance metrics from this monthly sales report and identify any concerning trends.",   BinaryContent(       data=report_path.read_bytes(),       media_type='application/pdf'   )])print(result.output)

Bu, güçlü otomasyon olanakları sunar. Yığınla raporu işleyebilir, faturalar’dan veri çıkarabilir veya sözleşme hükümlerini analiz edebilirsiniz — normalde manuel inceleme gerektiren tüm görevler.

Önemli notlar:

Farklı modeller farklı dosya formatlarını destekler. Çoğu, yaygın görsel formatlarını (PNG, JPEG) ve PDF’leri işler; ancak detaylar için modelinizin dokümantasyonuna bakın. Google’ın Vertex AI gibi bazı modelleri bulut depolama URL’lerine doğrudan erişebilirken, diğerleri içeriği önce indirir.

Veri analizi iş akışları için bu çok kipli (multimodal) yetenek, görsel raporlarınız ile yapay zekâ destekli içgörüler arasındaki boşluğu kapatır; günlük çalıştığınız tüm iş belgelerinin analizini otomatikleştirmeyi mümkün kılar.

Pydantic AI’de Akış (Streaming) Etkinleştirme

Karmaşık veri analizi görevlerinde, tamamlanmış yanıtı beklemek yerine sonuçları oluşurken görmek istersiniz. Akış, kullanıcıların analizin gerçek zamanlı olarak ilerleyişini izlemesine olanak tanır; bu da satış performansına dair ayrıntılı sorular sorarken değerlidir.

Pydantic AI, run_stream() yöntemi aracılığıyla yerleşik akış sunar. İşleyişi şöyle:

import asynciofrom pydantic_ai import Agent# Create our sales analysis agentsales_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt=(       "You are a data analyst specializing in sales performance. "       "Provide detailed, actionable insights based on the data provided."   ))async def demo_streaming():   question = """   Analyze this sales scenario: Our company sold 1,200 laptops and 2,300 phones   last quarter across 4 regions. Laptops average $1,500 each, phones $500 each.   What are the key insights and recommendations?   """     async with sales_agent.run_stream(question) as result:       async for text in result.stream_text():           print(text, end='', flush=True)# Run the streaming analysisasyncio.run(demo_streaming())

Akış söz dizimini anlama:

async with, metin parçaları alınırken açık kalan LLM bağlantısı oluşturur. Bunu bir telefon görüşmesi açmak gibi düşünün — bağlantıyı kurmanız, konuşmanızı yapmanız ve düzgünce kapatmanız gerekir.

async for döngüsü, her metin parçasını geldiği anda işler. stream_text()’in her seferinde metnin tamamını yeniden oluşturduğuna dikkat edin — önce "Hello", sonra "Hello world", ardından "Hello world, how" gibi. Bu, tam bağlamı verir ancak görüntüleme açısından tekrarlı olabilir.

Neden async ve asyncio birlikte çalışır:

Bir LLM’e soru sorduğunuzda, yanıt üretmesi zaman alır — genelde 3–10 saniye. Bu süre boyunca model, her 50–200 milisaniyede bir küçük metin parçaları gönderir.

Async olmadan, programınız her parça için beklerken tamamen donup kalırdı. Async ile Python’un olay döngüsü (bu bekleme dönemlerini yöneten sistem) görevler arasında geçiş yapabilir. Bu, programınızın duyarlı kalmasını ve hatta aynı anda birden çok sohbeti yürütebilmesini sağlar.

asyncio.run() ise tüm süreci başlatır — her şeyi koordine eden olay döngüsünü oluşturur. asyncio.run(demo_streaming()) çağrısı yaptığınızda, LLM yanıtlarını beklerken async fonksiyonlarınızın gerektiğinde durup devam edebildiği ortamı kurar.

Şimdi, daha iyi bir akış deneyimi için yalnızca yeni metin deltalarını gösteren yeniden kullanılabilir bir fonksiyon oluşturalım:

from pydantic_ai.messages import PartDeltaEvent, TextPartDeltaasync def stream_agent_response(agent: Agent, task: str):   """   Stream a response from any Pydantic AI agent showing just new text deltas.   """   async def event_handler(ctx, event_stream):       async for event in event_stream:           if isinstance(event, PartDeltaEvent) and isinstance(               event.delta, TextPartDelta           ):               print(event.delta.content_delta, end="", flush=True)   # Use agent.run() with event_stream_handler for proper streaming   result = await agent.run(task, event_stream_handler=event_handler)   print()  # Add a newline when streaming is complete   return result# Usage exampleresponse = asyncio.run(stream_agent_response(   sales_agent,   "What are the top 3 metrics I should track for quarterly sales analysis?"))

Akış fonksiyonunun ayrımı:

stream_agent_response() fonksiyonu, yalnızca yeni metin geldikçe göstererek daha doğal bir akış deneyimi sunar. İşleyişi şöyle:

1. Olay işleyici kurulumu: İçteki event_handler() fonksiyonu, ajanın işleme sürecindeki belirli olayları dinler. Yeni metin parçalarını temsil eden TextPartDelta ile PartDeltaEvent’leri filtreler.
2. Delta içeriği: Her seferinde tam yeniden oluşturulmuş metni almak yerine, event.delta.content_delta yalnızca yeni kelimeleri veya karakterleri verir. Bu, yanıtın kelime kelime yazıldığı bir daktilo etkisi yaratır.
3. Ajan yürütümü: agent.run()’i event_stream_handler parametresiyle kullanırız. Bu, ajanın her akış olayı için özel işleyicimizi çağırmasını sağlar; böylece neyin görüntüleneceği üzerinde ince ayar kontrolü elde ederiz.
4. Gerçek zamanlı çıktı: print(event.delta.content_delta, end="", flush=True) her yeni parçayı satır sonu eklemeden anında gösterir; akıcı bir metin akışı sağlar.

Bu yaklaşım, tamamlanmış bir yanıtı beklemek veya tekrarlı yeniden oluşturulmuş metin görmek yerine, yapay zekânın analizi gerçek zamanlı düşünüşünü izliyormuş hissi verir. Veri analizi örneklerimiz boyunca akış yanıtlarını göstermek için bu fonksiyonu kullanacağız.

Sonuç

Bu eğitim boyunca, pratik veri analizi örnekleri üzerinden Pydantic AI’ye dair kapsamlı bir anlayış kazandınız. Sistem komutlarıyla ajanlar oluşturmayı, yerleşik ve özel araçlar eklemeyi, Pydantic modelleriyle çıktıları yapılandırmayı ve gerçek zamanlı geri bildirim için yanıtları akışla iletmeyi öğrendiniz. Bu bileşenler bir araya gelerek, basit sohbet botlarından ziyade analitik ortaklar gibi davranan yapay zekâ sistemleri oluşturur.

Uygulamalar, ele aldığımız satış analizi örneklerinin çok ötesine uzanır. Artık, kendi veri kaynaklarınızı okuyan, iş kurallarınızı izleyen ve mevcut sistemlerinizle uyumlu formatlarda sonuç döndüren yapay zekâ ajanları oluşturabilirsiniz. İster rapor üretimini otomatikleştirin, ister müşteri geri bildirimlerini analiz edin veya finansal verileri işleyin; Pydantic AI size üretim uygulamaları için gereken yapı ve güvenilirliği sağlar.

Eğer LangGraph ile çoklu ajan sistemleri oluşturmaya ilgi duyuyorsanız, uygulamalı kursumuza mutlaka göz atın.