Pydantic AI: Een beginnersgids met praktische voorbeelden

AI-gedreven applicaties bouwen leidt vaak tot ongestructureerde outputs, type-mismatches en problemen met betrouwbaarheid in productie. Traditionele manieren om LLM's te integreren in Python-applicaties missen de structuur en validatie die je in productie nodig hebt. Pydantic AI lost dit op door Pydantics datavalidatie te combineren met een agentframework voor LLM-interacties.

In deze tutorial leer je gestructureerde AI-agents maken die gevalideerde outputs opleveren en typeveiligheid behouden. We behandelen het opzetten van agents met systeemprompts, het bouwen van functionele tools die LLM's tijdens gesprekken kunnen aanroepen, en het implementeren van gestructureerde outputvalidatie. Je ontdekt ook hoe je afhankelijkheden beheert tussen agentcomponenten en hoe je responses kunt streamen voor realtime applicaties. Aan het einde heb je hands-on ervaring met het bouwen van AI-applicaties die complexe workflows aankunnen.

Als je op zoek bent naar een praktische cursus over het bouwen van agentische AI-systemen, raad ik de cursus Building Multi-Agent Systems with LangGraph aan. 

Wat is Pydantic AI?

Pydantic AI is een Python-agentframework dat structuur en typeveiligheid brengt naar LLM-applicaties. In tegenstelling tot basale LLM-integraties die ruwe tekst retourneren, behandelt Pydantic AI AI-interacties als gestructureerde gesprekken met gevalideerde input en output, waardoor het eenvoudiger wordt om betrouwbare applicaties te bouwen.

Belangrijkste features en voordelen:

• Gestructureerde outputvalidatie — Je AI-antwoorden voldoen automatisch aan Pydantic-modellen, wat parsefouten voorkomt en dataconsistentie waarborgt
• Functionele tools — LLM's kunnen je Python-functies aanroepen tijdens gesprekken, met toegang tot echte data en berekeningen
• Typeveiligheid — Volledige typingsupport betekent minder runtimefouten en betere IDE-ondersteuning bij het bouwen van complexe AI-workflows
• Systeemprompts — Definieer duidelijke instructies voor je AI-agents die consistent blijven over alle interacties
• Dependency injection — Deel context, databaseverbindingen en gebruikersvoorkeuren netjes over alle agentcomponenten
• Meerdere uitvoermodi — Draai agents synchroon, asynchroon of stream responses realtime, afhankelijk van je behoeften
• Herbruikbaarheid van agents — Maak agents één keer en hergebruik ze in je hele applicatie, vergelijkbaar met FastAPI-routers

Deze aanpak verandert AI van onvoorspelbare tekstgeneratie in betrouwbare, getypte interacties die natuurlijk passen in bestaande Python-applicaties. In plaats van te worstelen met prompt engineering en outputparsing, kun je je focussen op het bouwen van de functionaliteit die je gebruikers nodig hebben.

Vereisten

Voor je met deze tutorial begint, heb je een paar dingen nodig:

Vereiste kennis:

• Python-basisprincipes : Voel je vertrouwd met classes en functies
• Basis van asynchroon programmeren in Python
• Pydantic-basis : Begrijp modellen, veldvalidatie en typeannotaties
• Bekendheid met LLM's :  Basiskennis van hoe language models werken en wat prompts zijn

Handig maar niet vereist:

• Agentconcepten :  Enige ervaring met AI-agents en tool calling, al behandelen we dit

Installatievereisten:

• Python 3.9 of hoger
• OpenAI- en Anthropic-API-sleutels
• Basisvaardigheden met de terminal/command line voor pakketinstallatie

Als je nieuw bent met Pydantic, hun officiële documentatie behandelt de basis goed. Voor LLM-kennis volstaat elke inleidende gids over ChatGPT of vergelijkbare modellen om mee te kunnen doen.

Aan de slag met Pydantic AI

In deze tutorial bouwen we een data-analyseagent die ons helpt de verkoopprestaties per regio en product te begrijpen. Deze agent begint eenvoudig en wordt geavanceerder naarmate we functies toevoegen zoals custom tools, gestructureerde outputs en streaming.

Installatie en setup

Voordat we in de code duiken, installeren we Pydantic AI en richten we onze omgeving in:

pip install pydantic-ai

Je hebt ook zowel een OpenAI als een Anthropic-API-sleutel nodig. Stel ze in als omgevingsvariabelen:

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

> We gebruiken zowel OpenAI- als Anthropic-modellen omdat sommige features in Pydantic AI in de ene wel en in de andere niet worden ondersteund.

Voor onze data-analysevoorbeelden gebruiken we ook pandas voor datamanipulatie:

pip install pandas

Je eerste agent maken

Laten we beginnen met de simpelst mogelijke agent — eentje die basisvragen over verkoopdata kan beantwoorden. In Pydantic AI is een agent je hoofdinterface voor LLM-interacties (voer de volgende code uit in een Python-script):

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)

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.

Dit maakt een agent die zijn rol als sales-analist begrijpt en relevant advies kan geven. De system_prompt geeft de LLM context over wat voor soort antwoorden je wilt, terwijl run_sync() de agent uitvoert en een resultaat retourneert.

Hier werkt de functie run_sync() alleen in Python-scripts. Om agents in een Jupyter Notebook te draaien, kun je de volgende syntax gebruiken:

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

Het LLM en zijn instellingen wijzigen

Pydantic AI ondersteunt meerdere LLM-providers en laat je het modelgedrag aanpassen. Zo kun je met verschillende opties experimenteren:

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

Elk model brengt andere mogelijkheden mee voor je data-analyseworkflow. Claude-modellen blinken uit in gedetailleerde redenering en complexe analyses, ideaal wanneer je grondige inzichten uit je verkoopdata nodig hebt. GPT-4o-mini biedt snellere responses en lagere kosten, perfect voor snelle vragen of bij het verwerken van grote aantallen queries.

Naast het kiezen van verschillende modellen kun je hun gedrag fijnafstemmen met modelinstellingen:

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

Modelinstellingen die je kunt aanpassen:

• temperature — Bepaalt creativiteit (0,0 = gefocust, 1,0 = creatief)
• max_tokens — Beperkt de lengte van het antwoord
• top_p — Alternatief voor temperature om willekeur te sturen

Voor data-analytische taken werken lagere temperature-waarden (0,1–0,3) meestal beter, omdat je consistente, feitelijke antwoorden wilt in plaats van creatieve interpretaties. Het instellen van max_tokens helpt de lengte van het antwoord te beheersen, handig voor beknopte samenvattingen of wanneer je API-kosten wilt beperken.

Tools gebruiken in agents

Tot nu toe kan onze sales-analyseagent alleen werken met de informatie die we in onze prompts geven. Maar echte data-analyse vereist vaak toegang tot externe informatie, berekeningen uitvoeren of koppelen aan bedrijfsystemen. Hier komen tools in beeld — ze geven je agent de mogelijkheid om acties te ondernemen en informatie te verzamelen tijdens gesprekken.

Ingebouwde tools

Ingebouwde tools zijn kant-en-klare functies van LLM-providers. Pydantic AI ondersteunt websearch en code-executietools die rechtstreeks op de infrastructuur van de provider draaien.

Laten we beginnen met websearch, perfect om actuele marktinformatie op te halen:

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

Dit verandert je data-analyse van werken met oude informatie naar het meenemen van realtime marktdata. In plaats van alleen data te analyseren, kan je agent nu de prestaties van je bedrijf vergelijken met actuele markttrends.

Laten we nu code-executie toevoegen voor wiskundige analyse en dataverwerking:

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)

Code-executie gaat verder dan simpele tekstantwoorden naar daadwerkelijke computationele analyse. Je agent kan nu complexe berekeningen uitvoeren, visualisaties maken en data verwerken die via gesprek alleen niet mogelijk zijn. Het resultaatobject bevat zowel de analyse van de agent als eventuele bestanden die tijdens de code-executie zijn gegenereerd, die je kunt downloaden voor verder gebruik.

Eigen tools schrijven

Hoewel ingebouwde tools nuttig zijn, heb je vaak eigen tools nodig die werken met jouw specifieke bedrijfsystemen. Custom tools zijn Python-functies die je agent tijdens gesprekken kan aanroepen.

Laten we tools maken die veelvoorkomende verkoopstatistieken berekenen:

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.

Deze custom tools verzorgen specifieke verkoopberekeningen die jouw bedrijf regelmatig gebruikt. De conversieratetool helpt de marketingprestaties meten, terwijl de tool voor de gemiddelde orderwaarde het bestedingspatroon van klanten volgt. Custom tools verbinden je agent met je specifieke bedrijfslogica en -systemen.

Voor geavanceerdere toolpatronen, inclusief dependency injection en foutafhandeling, bekijk de complete documentatie over tools.

Gestructureerde outputs gebruiken

Tot nu toe hebben onze agents platte tekst geretourneerd, wat goed werkt voor verkennend werk maar problemen oplevert in productieapplicaties. Wanneer je agentantwoorden programmatisch moet verwerken, specifieke datapoints wilt parsen of AI-outputs met andere systemen moet integreren, heb je gegarandeerde structuur nodig.

Stel, je wilt verkoopdata analyseren en altijd specifieke metrics terugkrijgen. Met platte tekst kan de AI elke keer een ander formaat geven. Met gestructureerde outputs definieer je precies wat je wilt:

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.

Let op de parameter output_type=SalesInsight. Dit vertelt de agent dat hij een SalesInsight-object moet retourneren met precies die vier velden. Niet meer en niet minder. Het resultaat komt terug als result.output dat automatisch wordt gevalideerd en getypt.

Gestructureerde outputs werken door je Pydantic-model om te zetten in een JSON-schema dat de LLM volgt. De AI kan niet afwijken van je structuur — als het iets anders probeert terug te geven, vraagt Pydantic AI om het opnieuw te proberen.

Voor complexere analyses kun je modellen nesten en lijsten gebruiken:

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+

Deze aanpak verandert AI van onvoorspelbare tekstgeneratie in betrouwbare dataverwerking. Je kunt elke regionale metric in een database opslaan, alerts triggeren op basis van prestatiebeoordelingen of automatisch managementdashboards genereren. Geen regex-parsing, geen verschillende antwoordformaten afhandelen — gewoon elke keer schone, gevalideerde data.

De parameter output_type accepteert elk Pydantic-model, een Python-dataclass, TypedDict of zelfs eenvoudige types zoals int of list[str]. Voor data-analyseworkflows betekent dit dat je betrouwbare pipelines kunt bouwen waarbij AI-analyses direct in je bestaande bedrijfsystemen doorstromen.

Berichten en chathistorie in Pydantic-agents

Bij data-analyseagents heb je vaak gesprekken die meerdere interacties beslaan. Misschien begin je met verkooptrends, wil je daarna dieper inzoomen op specifieke regio's, of periodes vergelijken. Berichten en chathistorie laten je context behouden over deze gesprekken heen.

Toegang tot berichtenhistorie

Elke keer dat je een agent runt, houdt Pydantic AI de volledige conversatie bij. Je kunt deze geschiedenis opvragen om te begrijpen wat er gebeurde of later verder te gaan met het gesprek:

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

De methode all_messages() geeft je alles - systeemprompts, gebruikersvragen en agentantwoorden. De methode new_messages() retourneert alleen wat er in de huidige run is gebeurd. Dit is handig bij langere gesprekken wanneer je wilt bijhouden wat er veranderd is.

Gesprekken voortzetten met berichtenhistorie

Om voort te bouwen op eerdere gesprekken, geef je de berichtenhistorie mee aan je volgende agentrun. Zo kan de agent onthouden wat je eerder besprak:

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

Elke nieuwe run bouwt voort op de voorgaande context. De agent onthoudt niet alleen je vragen, maar ook zijn eigen eerdere antwoorden, wat zorgt voor een consistent analytisch gesprek.

Berichten opslaan en laden naar JSON

Voor langdurige opslag of het delen van gesprekken tussen systemen kun je de berichtenhistorie serialiseren naar 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")

De methode all_messages_json() retourneert de conversatie als JSON-bytes, ideaal om op te slaan in databases, te versturen via API's of analysetrajecten te archiveren. Er is ook new_messages_json() als je alleen het laatste deel van het gesprek wilt opslaan.

Met deze aanpak kun je persistente analytische workflows bouwen. Je zou de analyssesie van elke klant kunnen opslaan, complexe dataonderzoeken over meerdere dagen hervatten, of conversatiecontext delen tussen teamleden die aan dezelfde analyse werken.

Werken met afbeeldingen en documenten

Echte data-analyse gaat vaak verder dan alleen tekst en cijfers. Je moet misschien grafieken uit rapporten analyseren, data uit pdf's halen of grafieken en visualisaties interpreteren. Pydantic AI ondersteunt input van afbeeldingen en documenten, zodat je agents direct met deze rijke databronnen kunnen werken.

Afbeeldingen analyseren via URL's

Wanneer je grafieken of visualisaties online gehost zijn, kun je je agent er direct naartoe wijzen:

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)

De agent kan grafiektypen identificeren, waarden van assen aflezen, trends spotten en bedrijfsinzichten geven zoals een menselijke analist dat zou doen bij dezelfde visualisatie.

Werken met lokale afbeeldingen

Voor lokaal opgeslagen afbeeldingen — zoals screenshots uit je BI-tools of grafieken uit Excel — gebruik je 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)

Deze aanpak werkt uitstekend voor geautomatiseerde rapportageworkflows. Je kunt je dashboards programmatisch screenshotten en de AI vervolgens geschreven analyses laten leveren ter begeleiding van de visuals.

Documenten analyseren via URL's

Veel bedrijfsdocumenten worden via URL's gedeeld — rapporten op intranetten, pdf's in cloudopslag of publieke onderzoeksrapporten die je analyse informeren:

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)

De agent kan volledige documenten doorlezen, relevante datapoints extraheren en samenvattingen geven die mensen veel langer zouden kosten om samen te stellen.

Lokale documenten verwerken

Voor documentbestanden op je lokale systeem — zoals geëxporteerde rapporten, contracten of interne presentaties — gebruik je 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)

Dit opent krachtige automatiseringsmogelijkheden. Je kunt stapels rapporten verwerken, data uit facturen halen of contractvoorwaarden analyseren — taken die normaal handmatige review vereisen.

Belangrijke opmerkingen:

Verschillende modellen ondersteunen verschillende bestandsformaten. De meeste kunnen gangbare afbeeldingsformaten (PNG, JPEG) en pdf's aan, maar check de documentatie van je model voor details. Sommige modellen zoals Google's Vertex AI kunnen cloudopslag-URL's direct benaderen, terwijl andere de content eerst downloaden.

Voor data-analyseworkflows overbrugt deze multimodale capaciteit de kloof tussen je visuele rapporten en AI-gedreven inzichten, waardoor het mogelijk wordt de volledige reeks bedrijfsdocumenten die je dagelijks gebruikt automatisch te analyseren.

Streaming inschakelen in Pydantic AI

Bij complexe data-analysetaken wil je resultaten zien terwijl ze worden gegenereerd, in plaats van te wachten op het volledige antwoord. Streaming laat gebruikers de analyse realtime volgen, wat waardevol is bij gedetailleerde vragen over verkoopprestaties.

Pydantic AI biedt ingebouwde streaming via de methode run_stream(). Zo werkt het:

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

De streamingsyntax begrijpen:

De async with opent een verbinding met de LLM die open blijft terwijl tekstfragmenten binnenkomen. Zie het als een telefoongesprek openen - je moet de verbinding tot stand brengen, je gesprek voeren en daarna netjes ophangen.

De async for-lus verwerkt elk tekstfragment zodra het arriveert. Let op dat stream_text() de complete tekst telkens opnieuw opbouwt - je krijgt dus "Hallo", daarna "Hallo wereld", dan "Hallo wereld, hoe". Dit geeft je de volledige context maar kan voor weergave repetitief zijn.

Waarom async en asyncio samen werken:

Wanneer je een LLM een vraag stelt, kost het tijd om het antwoord te genereren — meestal 3–10 seconden. In die tijd stuurt het model elke 50–200 milliseconden kleine stukjes tekst terug.

Zonder async zou je programma volledig bevroren zijn terwijl het op elk stukje wacht. Met async kan de event loop van Python (het systeem dat deze wachttijden beheert) tussen taken schakelen. Zo blijft je programma responsief en kun je zelfs meerdere gesprekken tegelijk draaien.

asyncio.run() is wat dit alles start - het creëert de event loop die alles coördineert. Wanneer je asyncio.run(demo_streaming()) aanroept, zet het de omgeving op waarin je async-functies kunnen pauzeren en hervatten wanneer nodig tijdens het wachten op LLM-responses.

Laten we nu een herbruikbare functie maken die alleen de nieuwe tekstdelta's toont voor een betere streamingervaring:

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

Uiteenrafelen van de streamingfunctie:

De functie stream_agent_response() creëert een natuurlijkere streamingervaring door alleen nieuwe tekst te tonen zodra die binnenkomt. Zo werkt het:

1. Eventhandler instellen: De interne functie event_handler() luistert naar specifieke events tijdens de verwerking door de agent. Ze filtert op PartDeltaEvent met TextPartDelta - dat zijn nieuwe stukjes tekst die worden gegenereerd.
2. Deltacontent: In plaats van elke keer de volledig opnieuw opgebouwde tekst te krijgen, geeft event.delta.content_delta alleen de nieuwe woorden of tekens. Dit creëert een typemachine-effect waarbij je het antwoord woord voor woord ziet verschijnen.
3. Agentuitvoering: We gebruiken agent.run() met de parameter event_stream_handler. Dit vertelt de agent om onze custom handler aan te roepen voor elk streamingevent, waardoor we fijnmazige controle krijgen over wat er wordt weergegeven.
4. Realtime output: De print(event.delta.content_delta, end="", flush=True) toont elk nieuw stukje direct zonder regeleinden toe te voegen, wat zorgt voor vloeiende tekst.

Deze aanpak geeft je het natuurlijke gevoel dat je de AI de analyse in realtime ziet doordenken, in plaats van te wachten op een compleet antwoord of herhaaldelijk opnieuw opgebouwde tekst te zien. We gebruiken deze functie in de komende secties om streamingresponses te tonen doorheen onze data-analysevoorbeelden.

Conclusie

In deze tutorial heb je een volledig begrip van Pydantic AI opgebouwd via praktische data-analysevoorbeelden. Je hebt geleerd hoe je agents maakt met systeemprompts, zowel ingebouwde als eigen tools toevoegt, outputs structureert met Pydantic-modellen en responses streamt voor realtime feedback. Deze componenten samen creëren AI-systemen die meer functioneren als analytische partners dan als simpele chatbots.

De toepassingen reiken veel verder dan de sales-analysevoorbeelden die we hebben behandeld. Je kunt nu AI-agents bouwen die jouw specifieke databronnen lezen, je bedrijfsregels volgen en resultaten teruggeven in formats die werken met je bestaande systemen. Of je nu rapportage automatiseert, klantfeedback analyseert of financiële data verwerkt, Pydantic AI geeft je de structuur en betrouwbaarheid die nodig zijn voor productieapplicaties.

Als je interesse hebt in het bouwen van multi-agent-systemen met LangGraph, bekijk dan zeker onze hands-on cursus.