Pydantic AI: व्यावहारिक उदाहरणों के साथ एक शुरुआती मार्गदर्शिका

AI-संचालित एप्लिकेशन बनाते समय अक्सर असंरचित आउटपुट, प्रकार असंगतियाँ, और प्रोडक्शन विश्वसनीयता से जुड़ी समस्याएँ सामने आती हैं। Python एप्लिकेशनों में LLMs को जोड़ने के पारंपरिक तरीके प्रोडक्शन सिस्टम के लिए आवश्यक स्ट्रक्चर और वैलिडेशन से वंचित रहते हैं। Pydantic AI इसे Pydantic के डेटा वैलिडेशन और LLM इंटरैक्शन के लिए एक एजेंट फ्रेमवर्क को मिलाकर हल करता है।

इस ट्यूटोरियल में, आप ऐसे स्ट्रक्चर्ड AI एजेंट बनाना सीखेंगे जो वैलिडेटेड आउटपुट दें और टाइप सेफ्टी बनाए रखें। हम सिस्टम प्रॉम्प्ट्स के साथ एजेंट सेटअप, बातचीत के दौरान LLMs द्वारा कॉल किए जा सकने वाले फ़ंक्शन टूल्स बनाना, और स्ट्रक्चर्ड आउटपुट वैलिडेशन लागू करना कवर करेंगे। आप यह भी जानेंगे कि एजेंट कंपोनेंट्स में डिपेंडेंसीज़ को कैसे मैनेज करें और रीयल-टाइम एप्लिकेशनों के लिए प्रतिक्रियाएँ स्ट्रीम करें। अंत तक, आपके पास जटिल वर्कफ़्लोज़ सँभालने वाले AI एप्लिकेशन बनाने का व्यावहारिक अनुभव होगा।

यदि आप एजेण्टिक AI सिस्टम बनाने पर हैंड्स-ऑन कोर्स ढूँढ रहे हैं, तो मैं Building Multi-Agent Systems with LangGraph कोर्स की सिफारिश करता हूँ। 

Pydantic AI क्या है?

Pydantic AI एक Python एजेंट फ्रेमवर्क है जो LLM एप्लिकेशनों में स्ट्रक्चर और टाइप सेफ्टी लाता है। बेसिक LLM इंटीग्रेशन जो कच्चा टेक्स्ट लौटाते हैं, उनसे अलग, Pydantic AI AI इंटरैक्शनों को वैलिडेटेड इनपुट और आउटपुट के साथ स्ट्रक्चर्ड बातचीत की तरह ट्रीट करता है, जिससे भरोसेमंद एप्लिकेशन बनाना आसान हो जाता है।

मुख्य विशेषताएँ और लाभ:

• स्ट्रक्चर्ड आउटपुट वैलिडेशन — आपकी AI प्रतिक्रियाएँ स्वतः ही Pydantic मॉडलों के अनुरूप होती हैं, जिससे पार्सिंग त्रुटियाँ रुकती हैं और डेटा स्थिरता सुनिश्चित होती है
• फ़ंक्शन टूल्स — LLMs बातचीत के दौरान आपकी Python फ़ंक्शनों को कॉल कर सकते हैं, जिससे उन्हें वास्तविक डेटा और गणनाओं तक पहुँच मिलती है
• टाइप सेफ्टी — पूर्ण टाइपिंग सपोर्ट का अर्थ है कम रनटाइम त्रुटियाँ और जटिल AI वर्कफ़्लोज़ बनाते समय बेहतर IDE सहायता
• सिस्टम प्रॉम्प्ट्स — अपने AI एजेंट्स के लिए स्पष्ट निर्देश परिभाषित करें जो सभी इंटरैक्शनों में सुसंगत रहें
• डिपेंडेंसी इंजेक्शन — एजेंट के सभी कंपोनेंट्स में संदर्भ, डेटाबेस कनेक्शन और उपयोगकर्ता प्राथमिकताएँ साफ़-सुथरे तरीके से साझा करें
• एकाधिक निष्पादन मोड — अपनी आवश्यकता के अनुसार एजेंट्स को समकालिक, असमकालिक रूप से चलाएँ, या रीयल-टाइम में प्रतिक्रियाएँ स्ट्रीम करें
• एजेंट पुन: प्रयोज्यता — एजेंट्स एक बार बनाएँ और उन्हें अपने एप्लिकेशन में बार-बार उपयोग करें, जैसे FastAPI राउटर्स

यह तरीका AI को अप्रत्याशित टेक्स्ट जनरेशन से बदलकर विश्वसनीय, टाइप्ड इंटरैक्शनों में बदल देता है जो मौजूदा Python एप्लिकेशनों में स्वाभाविक रूप से फिट बैठते हैं। प्रॉम्प्ट इंजीनियरिंग और आउटपुट पार्सिंग से जूझने के बजाय, आप वह वास्तविक फ़ंक्शनैलिटी बनाने पर ध्यान दे सकते हैं जिसकी आपके उपयोगकर्ताओं को आवश्यकता है।

पूर्वापेक्षाएँ

इस ट्यूटोरियल में आने से पहले, आपको कुछ चीज़ों की आवश्यकता होगी:

आवश्यक ज्ञान:

• Python की बुनियाद : कक्षाओं और फ़ंक्शनों के साथ सहज बनें
• Python में असिंक्रोनस प्रोग्रामिंग की बुनियाद
• Pydantic की बुनियाद : मॉडल्स, फ़ील्ड वैलिडेशन और टाइप अनोटेशन समझें
• LLM की परिचितता :  भाषा मॉडलों के काम करने का बुनियादी ज्ञान और प्रॉम्प्ट क्या होते हैं

सहायक लेकिन अनिवार्य नहीं:

• एजेंट अवधारणाएँ :  AI एजेंट्स और टूल कॉलिंग का कुछ अनुभव, हालाँकि हम इसे कवर करेंगे

सेटअप आवश्यकताएँ:

• Python 3.9 या उससे उच्च
• OpenAI और Anthropic API कुंजियाँ
• पैकेज इंस्टॉलेशन के लिए बेसिक टर्मिनल/कमांड लाइन कौशल

यदि आप Pydantic में नए हैं, तो उनका आधिकारिक दस्तावेज़ बुनियादी बातें अच्छी तरह कवर करते हैं। LLM की बुनियाद के लिए, ChatGPT या समान मॉडलों पर कोई भी शुरुआती गाइड आपको साथ चलने के लिए पर्याप्त पृष्ठभूमि देगा।

Pydantic AI के साथ शुरुआत

इस पूरे ट्यूटोरियल के दौरान, हम एक डेटा विश्लेषण एजेंट बनाएँगे जो विभिन्न क्षेत्रों और उत्पादों में बिक्री प्रदर्शन समझने में मदद करेगा। यह एजेंट सरल रूप से शुरू होगा और जैसे-जैसे हम कस्टम टूल्स, स्ट्रक्चर्ड आउटपुट, और स्ट्रीमिंग क्षमताएँ जोड़ेंगे, यह अधिक परिष्कृत होता जाएगा।

इंस्टॉलेशन और सेटअप

कोड में उतरने से पहले, आइए Pydantic AI इंस्टॉल करें और अपना वातावरण सेटअप करें:

pip install pydantic-ai

आपको OpenAI और Anthropic दोनों की API कुंजी भी चाहिए होगी। इन्हें वातावरण वेरिएबल के रूप में सेट करें:

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

> हम OpenAI और Anthropic दोनों मॉडलों का उपयोग करेंगे क्योंकि Pydantic AI में कुछ फ़ीचर ऐसे हैं जो एक में समर्थित हैं, दूसरे में नहीं।

हमारे डेटा विश्लेषण उदाहरणों के लिए, हम डेटा मैनीपुलेशन हेतु pandas का भी उपयोग करेंगे:

pip install pandas

अपना पहला एजेंट बनाना

सबसे सरल संभव एजेंट से शुरू करें — जो बिक्री डेटा के बारे में बुनियादी प्रश्नों का उत्तर दे सके। Pydantic AI में, एक एजेंट LLM इंटरैक्शनों के लिए आपका मुख्य इंटरफ़ेस होता है (निम्न कोड को Python स्क्रिप्ट में चलाएँ):

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)

आउटपुट:

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.

यह एक ऐसा एजेंट बनाता है जो अपने रोल को एक सेल्स एनालिस्ट के रूप में समझता है और प्रासंगिक सलाह दे सकता है। system_prompt LLM को उस तरह की प्रतिक्रियाओं के बारे में संदर्भ देता है जो आप चाहते हैं, जबकि run_sync() एजेंट को निष्पादित करता है और परिणाम लौटाता है।

यहाँ, run_sync() फ़ंक्शन केवल Python स्क्रिप्ट्स में काम करता है। Jupyter Notebook में एजेंट चलाने के लिए, आप निम्न सिंटैक्स का उपयोग कर सकते हैं:

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

LLM और उसकी सेटिंग्स बदलना

Pydantic AI कई LLM प्रदाताओं का समर्थन करता है और आपको मॉडल व्यवहार कस्टमाइज़ करने देता है। अलग-अलग विकल्पों के साथ इस तरह प्रयोग करें:

# 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.")

प्रत्येक मॉडल आपके डेटा विश्लेषण वर्कफ़्लो में अलग-अलग क्षमताएँ लाता है। Claude मॉडल विस्तृत तर्क और जटिल विश्लेषण में उत्कृष्ट हैं, जो तब आदर्श होते हैं जब आपको अपने बिक्री डेटा से गहन इनसाइट्स चाहिए। GPT-4o-mini तेज़ प्रतिक्रियाएँ और कम लागत प्रदान करता है, जो त्वरित प्रश्नों या बड़े पैमाने पर क्वेरी प्रोसेसिंग के लिए उपयुक्त है।

विभिन्न मॉडलों का चयन करने से आगे, आप मॉडल सेटिंग्स का उपयोग करके उनके व्यवहार को फाइन-ट्यून कर सकते हैं:

# 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   })

वे मॉडल सेटिंग्स जिन्हें आप कस्टमाइज़ कर सकते हैं:

• temperature — रचनात्मकता नियंत्रित करता है (0.0 = केंद्रित, 1.0 = रचनात्मक)
• max_tokens — प्रतिक्रिया की लंबाई सीमित करता है
• top_p — रैंडमनेस नियंत्रित करने के लिए temperature का विकल्प

डेटा विश्लेषण कार्यों के लिए, कम temperature मान (0.1–0.3) आम तौर पर बेहतर काम करते हैं क्योंकि आपको रचनात्मक व्याख्या के बजाय सुसंगत, तथ्यात्मक प्रतिक्रियाएँ चाहिए। max_tokens सेट करने से प्रतिक्रिया लंबाई नियंत्रित करने में मदद मिलती है, जो तब उपयोगी है जब आपको संक्षिप्त सारांश चाहिए या API लागत संबंधी चिंताएँ हों।

एजेंट्स में टूल्स का उपयोग

अब तक, हमारा सेल्स एनालिसिस एजेंट केवल उन जानकारियों के साथ काम कर सकता है जो हम अपने प्रॉम्प्ट्स में देते हैं। लेकिन वास्तविक डेटा विश्लेषण अक्सर बाहरी जानकारी तक पहुँच, गणनाएँ चलाने, या व्यावसायिक सिस्टम से जुड़ने की माँग करता है। यही जगह टूल्स की है — वे आपके एजेंट को बातचीत के दौरान कार्रवाई करने और जानकारी जुटाने की क्षमता देते हैं।

बिल्ट-इन टूल्स

बिल्ट-इन टूल्स LLM प्रदाताओं द्वारा दिए गए तैयार-उपयोग फ़ंक्शन होते हैं। Pydantic AI वेब सर्च और कोड निष्पादन टूल्स का समर्थन करता है जो सीधे प्रदाता के इंफ्रास्ट्रक्चर पर चलते हैं।

आइए वेब सर्च से शुरू करें, जो वर्तमान बाज़ार जानकारी पाने के लिए उपयुक्त है:

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:…

यह आपके डेटा विश्लेषण को पुरानी जानकारी के साथ काम करने से बदलकर रीयल-टाइम बाज़ार डेटा शामिल करने वाला बना देता है। अकेले डेटा का विश्लेषण करने के बजाय, आपका एजेंट अब आपकी कंपनी के प्रदर्शन की तुलना वर्तमान उद्योग रुझानों से कर सकता है।

अब आइए गणितीय विश्लेषण और डेटा प्रोसेसिंग के लिए कोड निष्पादन जोड़ते हैं:

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)

कोड निष्पादन साधारण टेक्स्ट प्रतिक्रियाओं से आगे बढ़कर वास्तविक कम्प्यूटेशनल विश्लेषण तक पहुँचता है। आपका एजेंट अब जटिल गणनाएँ कर सकता है, विज़ुअलाइज़ेशन बना सकता है, और ऐसा डेटा प्रोसेस कर सकता है जो अकेली बातचीत से संभव नहीं होता। परिणाम ऑब्जेक्ट में एजेंट का विश्लेषण और कोड निष्पादन के दौरान बनी कोई भी फ़ाइल शामिल होती है, जिन्हें आप आगे उपयोग के लिए डाउनलोड कर सकते हैं।

कस्टम टूल्स लिखना

यद्यपि बिल्ट-इन टूल्स उपयोगी हैं, आपको अक्सर ऐसे कस्टम टूल्स की आवश्यकता होगी जो आपके विशेष व्यावसायिक सिस्टम के साथ काम करें। कस्टम टूल्स वे Python फ़ंक्शन हैं जिन्हें आपका एजेंट बातचीत के दौरान कॉल कर सकता है।

आइए ऐसे टूल्स बनाएँ जो सामान्य बिक्री मीट्रिक्स की गणना करें:

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.

ये कस्टम टूल्स उन विशिष्ट बिक्री गणनाओं को संभालते हैं जिनका आपका व्यवसाय नियमित रूप से उपयोग करता है। कन्वर्ज़न रेट टूल मार्केटिंग प्रदर्शन को मापने में मदद करता है, जबकि औसत ऑर्डर मूल्य टूल ग्राहक व्यय पैटर्न को ट्रैक करता है। कस्टम टूल्स आपके एजेंट को आपकी विशेष व्यावसायिक लॉजिक और सिस्टम से जोड़ते हैं।

डिपेंडेंसी इंजेक्शन और एरर हैंडलिंग सहित अधिक उन्नत टूल पैटर्न के लिए, पूर्ण टूल्स दस्तावेज़ देखें।

स्ट्रक्चर्ड आउटपुट का उपयोग

अब तक हमारे एजेंट सादा टेक्स्ट प्रतिक्रियाएँ दे रहे थे, जो अन्वेषण के लिए तो ठीक हैं पर प्रोडक्शन एप्लिकेशनों में समस्याएँ पैदा करती हैं। जब आपको एजेंट प्रतिक्रियाओं को प्रोग्रामेटिकली प्रोसेस करना हो, विशिष्ट डेटा बिंदु पार्स करने हों, या AI आउटपुट को अन्य सिस्टम्स से इंटीग्रेट करना हो, तो गारंटीड स्ट्रक्चर चाहिए।

मान लें आप बिक्री डेटा का विश्लेषण करना चाहते हैं और हमेशा विशिष्ट मीट्रिक्स वापस पाना चाहते हैं। सादे टेक्स्ट के साथ, AI हर बार अलग फ़ॉर्मैट लौटा सकता है। स्ट्रक्चर्ड आउटपुट के साथ, आप ठीक-ठीक परिभाषित करते हैं कि आपको क्या चाहिए:

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 पैरामीटर पर। यह एजेंट को बताता है कि उसे ठीक उन्हीं चार फ़ील्ड्स वाला SalesInsight ऑब्जेक्ट लौटाना है। न अधिक, न कम। परिणाम result.output के रूप में आता है, जो स्वतः वैलिडेटेड और टाइप्ड होता है।

स्ट्रक्चर्ड आउटपुट आपके Pydantic मॉडल को JSON स्कीमा में बदलकर काम करते हैं, जिसका LLM पालन करता है। AI आपके स्ट्रक्चर से विचलित नहीं हो सकता — यदि वह कुछ और लौटाने की कोशिश करता है, तो Pydantic AI उसे फिर से प्रयास करने को कहेगा।

और अधिक जटिल विश्लेषण परिदृश्यों के लिए, आप मॉडलों को नेस्ट कर सकते हैं और सूचियों का उपयोग कर सकते हैं:

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+

यह तरीका AI को अप्रत्याशित टेक्स्ट जनरेशन से विश्वसनीय डेटा प्रोसेसिंग में बदल देता है। आप प्रत्येक क्षेत्रीय मेट्रिक को डेटाबेस में स्टोर कर सकते हैं, परफॉर्मेंस रेटिंग के आधार पर अलर्ट ट्रिगर कर सकते हैं, या स्वतः एग्जिक्यूटिव डैशबोर्ड बना सकते हैं। न regex पार्सिंग, न अलग-अलग प्रतिक्रिया फ़ॉर्मैट सँभालना — हर बार साफ़, वैलिडेटेड डेटा।

output_type पैरामीटर किसी भी Pydantic मॉडल, Python dataclass, TypedDict, या साधारण प्रकारों जैसे int या list[str] को स्वीकार करता है। डेटा विश्लेषण वर्कफ़्लोज़ के लिए, इसका अर्थ है कि आप विश्वसनीय पाइपलाइंस बना सकते हैं जहाँ AI विश्लेषण सीधे आपके मौजूदा व्यावसायिक सिस्टम्स में फ़ीड होता है।

Pydantic एजेंट्स में संदेश और चैट इतिहास

डेटा विश्लेषण एजेंट्स के साथ काम करते समय, आपको अक्सर कई इंटरैक्शनों में फैली बातचीत की आवश्यकता होती है। हो सकता है आप बिक्री रुझानों से शुरुआत करें, फिर विशिष्ट क्षेत्रों में गहराई से जाना चाहें, या अलग-अलग समयावधियों की तुलना करना चाहें। संदेश और चैट इतिहास आपको इन वार्तालापों में संदर्भ बनाए रखने देते हैं।

संदेश इतिहास तक पहुँच

हर बार जब आप कोई एजेंट चलाते हैं, Pydantic AI पूरी बातचीत का ट्रैक रखता है। आप इस इतिहास तक पहुँच सकते हैं ताकि समझ सकें क्या हुआ या बाद में बातचीत जारी रख सकें:

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() मेथड आपको सब कुछ देता है - सिस्टम प्रॉम्प्ट्स, उपयोगकर्ता प्रश्न, और एजेंट प्रतिक्रियाएँ। new_messages() मेथड केवल वर्तमान रन में क्या हुआ, यह लौटाता है। यह तब उपयोगी है जब आप लंबी बातचीत बना रहे हों और जानना चाहें कि क्या बदला।

संदेश इतिहास के साथ बातचीत जारी रखना

पिछली बातचीत पर आगे निर्माण करने के लिए, अपने अगले एजेंट रन में संदेश इतिहास पास करें। इससे एजेंट को याद रहता है कि आपने पहले क्या चर्चा की थी:

# 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)

प्रत्येक नया रन पिछले संदर्भ पर आधारित होता है। एजेंट न सिर्फ आपके प्रश्नों को याद रखता है, बल्कि अपनी पिछली प्रतिक्रियाएँ भी, जिससे एक सुसंगत विश्लेषणात्मक बातचीत बनती है।

संदेशों को JSON में सहेजना और लोड करना

दीर्घकालिक स्टोरेज या अलग-अलग सिस्टम्स के बीच बातचीत साझा करने के लिए, आप संदेश इतिहास को JSON में सीरियलाइज़ कर सकते हैं:

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() मेथड बातचीत को JSON बाइट्स के रूप में लौटाता है, जो डेटाबेस में सहेजने, APIs के जरिए भेजने, या विश्लेषण सत्रों को आर्काइव करने के लिए उपयुक्त है। यदि आप सिर्फ बातचीत के नवीनतम भाग को सहेजना चाहते हैं, तो new_messages_json() भी उपलब्ध है।

यह तरीका आपको स्थायी विश्लेषणात्मक वर्कफ़्लो बनाने देता है। आप प्रत्येक क्लाइंट का विश्लेषण सत्र सहेज सकते हैं, कई दिनों में फैली जटिल डेटा जाँचों को फिर से शुरू कर सकते हैं, या एक ही विश्लेषण पर काम कर रहे अलग-अलग टीम सदस्यों के बीच बातचीत का संदर्भ साझा कर सकते हैं।

छवियों और दस्तावेज़ों के साथ काम करना

वास्तविक डेटा विश्लेषण केवल टेक्स्ट और संख्याओं तक सीमित नहीं होता। आपको रिपोर्टों की चार्ट का विश्लेषण करना, PDFs से डेटा निकालना, या ग्राफ़ और विज़ुअलाइज़ेशन की व्याख्या करनी पड़ सकती है। Pydantic AI छवि और दस्तावेज़ इनपुट का समर्थन करता है, जिससे आपके एजेंट इन समृद्ध डेटा स्रोतों के साथ सीधे काम कर सकते हैं।

URLs से छवियों का विश्लेषण

जब आपके पास ऑनलाइन होस्ट की गई चार्ट, ग्राफ़ या विज़ुअलाइज़ेशन हों, तो आप अपने एजेंट को सीधे उनकी ओर इंगित कर सकते हैं:

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)

एजेंट चार्ट के प्रकार पहचान सकता है, अक्षों से मान पढ़ सकता है, रुझान देख सकता है, और वही व्यावसायिक इनसाइट्स दे सकता है जो एक मानव विश्लेषक इसी विज़ुअलाइज़ेशन को देखकर देगा।

लोकल छवियों के साथ काम करना

स्थानीय रूप से संग्रहीत छवियों — जैसे आपके BI टूल्स के स्क्रीनशॉट या Excel से एक्सपोर्ट किए गए चार्ट — के लिए BinaryContent का उपयोग करें:

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)

यह तरीका स्वचालित रिपोर्टिंग वर्कफ़्लोज़ के लिए शानदार है। आप प्रोग्रामेटिक रूप से अपने डैशबोर्ड्स के स्क्रीनशॉट ले सकते हैं, फिर AI से विज़ुअल्स के साथ लिखित विश्लेषण प्रदान करा सकते हैं।

URLs से दस्तावेज़ों का विश्लेषण

कई व्यावसायिक दस्तावेज़ URLs के माध्यम से साझा किए जाते हैं — कंपनी इंट्रानेट पर रिपोर्ट्स, क्लाउड स्टोरेज में PDFs, या आपके विश्लेषण को सूचित करने वाले सार्वजनिक शोध पत्र:

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)

एजेंट पूरे दस्तावेज़ को पढ़ सकता है, प्रासंगिक डेटा बिंदु निकाल सकता है, और ऐसे सारांश दे सकता है जिनमें मनुष्यों को कहीं अधिक समय लगता।

स्थानीय दस्तावेज़ों का प्रोसेसिंग

अपने लोकल सिस्टम पर मौजूद दस्तावेज़ों — जैसे एक्सपोर्टेड रिपोर्ट्स, कॉन्ट्रैक्ट्स, या आंतरिक प्रस्तुतियाँ — के लिए BinaryContent का उपयोग करें:

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)

यह शक्तिशाली स्वचालन संभावनाएँ खोलता है। आप ढेरों रिपोर्ट्स प्रोसेस कर सकते हैं, इनवॉइस से डेटा निकाल सकते हैं, या कॉन्ट्रैक्ट शर्तों का विश्लेषण कर सकते हैं — वे सभी कार्य जो सामान्यतः मैन्युअल समीक्षा माँगते हैं।

महत्वपूर्ण नोट्स:

अलग-अलग मॉडल विभिन्न फ़ाइल फ़ॉर्मैट्स का समर्थन करते हैं। अधिकांश सामान्य छवि फ़ॉर्मैट (PNG, JPEG) और PDFs को सँभालते हैं, लेकिन विवरण के लिए अपने मॉडल के दस्तावेज़ देखें। कुछ मॉडल जैसे Google का Vertex AI सीधे क्लाउड स्टोरेज URLs तक पहुँच सकते हैं, जबकि अन्य पहले सामग्री डाउनलोड करते हैं।

डेटा विश्लेषण वर्कफ़्लोज़ के लिए, यह मल्टीमॉडल क्षमता आपके विज़ुअल रिपोर्ट्स और AI-संचालित इनसाइट्स के बीच की खाई को पाटती है, जिससे रोज़मर्रा के व्यावसायिक दस्तावेज़ों के विश्लेषण का स्वचालन संभव होता है।

Pydantic AI में स्ट्रीमिंग सक्षम करना

जटिल डेटा विश्लेषण कार्यों पर काम करते समय, आप पूर्ण प्रतिक्रिया का इंतज़ार करने के बजाय परिणामों को बनते समय देखना चाहते हैं। स्ट्रीमिंग उपयोगकर्ताओं को रीयल-टाइम में विश्लेषण unfolding देखने देती है, जो बिक्री प्रदर्शन पर विस्तृत प्रश्न पूछते समय मूल्यवान है।

Pydantic AI run_stream() मेथड के माध्यम से बिल्ट-इन स्ट्रीमिंग प्रदान करता है। यह इस प्रकार काम करता है:

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())

स्ट्रीमिंग सिंटैक्स को समझना:

async with LLM के साथ एक कनेक्शन बनाता है जो टेक्स्ट चंक्स प्राप्त करते समय खुला रहता है। इसे फ़ोन कॉल खोलने जैसा समझें — आपको कनेक्शन स्थापित करना, बातचीत करना, फिर ठीक से हैंगअप करना होता है।

async for लूप प्रत्येक टेक्स्ट चंक को आते ही प्रोसेस करता है। ध्यान दें कि stream_text() हर बार पूरा टेक्स्ट फिर से बनाता है — इसलिए आपको "Hello", फिर "Hello world", फिर "Hello world, how" मिलता है। यह आपको पूरा संदर्भ देता है लेकिन प्रदर्शन उद्देश्यों के लिए दोहरावपूर्ण हो सकता है।

क्यों async और asyncio साथ काम करते हैं:

जब आप LLM से कोई प्रश्न पूछते हैं, तो प्रतिक्रिया जनरेट करने में समय लगता है — आमतौर पर 3–10 सेकंड। इस दौरान, मॉडल हर 50–200 मिलीसेकंड में छोटे टेक्स्ट हिस्से भेजता है।

बिना async के, आपका प्रोग्राम प्रत्येक हिस्से की प्रतीक्षा करते हुए पूरी तरह जमे रहता। async के साथ, Python का इवेंट लूप (वह सिस्टम जो इन प्रतीक्षा अवधियों को मैनेज करता है) कार्यों के बीच स्विच कर सकता है। इसका मतलब है कि आपका प्रोग्राम प्रतिक्रियाशील बना रहता है और एक साथ कई बातचीत भी चला सकता है।

asyncio.run() वही है जो इस पूरे प्रोसेस को शुरू करता है — यह इवेंट लूप बनाता है जो सब कुछ समन्वित करता है। जब आप asyncio.run(demo_streaming()) कॉल करते हैं, तो यह वह वातावरण सेट करता है जहाँ आपकी async फ़ंक्शन LLM प्रतिक्रियाओं की प्रतीक्षा करते हुए आवश्यकतानुसार रुक और फिर से चल सकते हैं।

अब आइए एक पुन: प्रयोज्य फ़ंक्शन बनाएँ जो बेहतर स्ट्रीमिंग अनुभव के लिए केवल नए टेक्स्ट डेल्टास दिखाए:

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?"))

स्ट्रीमिंग फ़ंक्शन का विश्लेषण:

stream_agent_response() फ़ंक्शन केवल नया टेक्स्ट आते ही दिखाकर अधिक स्वाभाविक स्ट्रीमिंग अनुभव बनाता है। यह इस प्रकार काम करता है:

1. इवेंट हैंडलर सेटअप: अंदर का event_handler() फ़ंक्शन एजेंट की प्रोसेसिंग के दौरान विशिष्ट इवेंट्स सुनता है। यह TextPartDelta वाले PartDeltaEvent को फ़िल्टर करता है — ये नए जनरेट हुए टेक्स्ट के हिस्से दर्शाते हैं।
2. डेल्टा कंटेंट: हर बार पूरा टेक्स्ट पाने के बजाय, event.delta.content_delta हमें केवल नए शब्द या अक्षर देता है। इससे टाइपराइटर जैसा प्रभाव बनता है जहाँ आप उत्तर को शब्द दर शब्द लिखते हुए देखते हैं।
3. एजेंट निष्पादन: हम agent.run() को event_stream_handler पैरामीटर के साथ उपयोग करते हैं। यह एजेंट को हर स्ट्रीमिंग इवेंट के लिए हमारे कस्टम हैंडलर को कॉल करने के लिए कहता है, जिससे हमें दिखाए जाने वाली चीज़ों पर सूक्ष्म नियंत्रण मिलता है।
4. रीयल-टाइम आउटपुट: print(event.delta.content_delta, end="", flush=True) प्रत्येक नए हिस्से को बिना लाइन ब्रेक जोड़े तुरंत दिखाता है, जिससे टेक्स्ट सहज रूप से बहता है।

यह तरीका आपको रीयल-टाइम में AI को विश्लेषण करते हुए देखने का स्वाभाविक अनुभव देता है, बजाय इसके कि आप पूरी प्रतिक्रिया का इंतज़ार करें या बार-बार रीजनरेटेड टेक्स्ट देखें। हम आने वाले सेक्शनों में अपने डेटा विश्लेषण उदाहरणों में स्ट्रीमिंग प्रतिक्रियाएँ दिखाने के लिए इस फ़ंक्शन का उपयोग करेंगे।

निष्कर्ष

इस ट्यूटोरियल के दौरान, आपने व्यावहारिक डेटा विश्लेषण उदाहरणों के माध्यम से Pydantic AI की पूरी समझ बनाई। आपने सिस्टम प्रॉम्प्ट्स के साथ एजेंट बनाना, बिल्ट-इन और कस्टम टूल्स जोड़ना, Pydantic मॉडलों के साथ आउटपुट को स्ट्रक्चर करना, और रीयल-टाइम फीडबैक के लिए प्रतिक्रियाएँ स्ट्रीम करना सीखा। ये घटक मिलकर ऐसे AI सिस्टम बनाते हैं जो साधारण चैटबॉट्स की बजाय विश्लेषणात्मक साझेदार की तरह काम करते हैं।

यह अनुप्रयोग उन बिक्री विश्लेषण उदाहरणों से कहीं आगे जाते हैं जिन्हें हमने कवर किया है। अब आप ऐसे AI एजेंट बना सकते हैं जो आपके विशिष्ट डेटा स्रोत पढ़ें, आपके व्यवसाय नियमों का पालन करें, और ऐसे फ़ॉर्मैट में परिणाम लौटाएँ जो आपके मौजूदा सिस्टम्स के साथ काम करें। चाहे आप रिपोर्ट जनरेशन का स्वचालन कर रहे हों, ग्राहक फीडबैक का विश्लेषण कर रहे हों, या वित्तीय डेटा प्रोसेस कर रहे हों, Pydantic AI आपको प्रोडक्शन एप्लिकेशनों के लिए आवश्यक स्ट्रक्चर और विश्वसनीयता देता है।

यदि आप LangGraph के साथ मल्टी-एजेंट सिस्टम्स बनाना में रुचि रखते हैं, तो हमारा हैंड्स-ऑन कोर्स अवश्य देखें।