Pydantic AI: guida per principianti con esempi pratici

Creare applicazioni basate su AI spesso porta a output non strutturati, incongruenze di tipo e problemi di affidabilità in produzione. Gli approcci tradizionali per integrare gli LLM nelle applicazioni Python mancano della struttura e della validazione necessarie per i sistemi di produzione. Pydantic AI risolve il problema combinando la validazione dei dati di Pydantic con un framework per agenti dedicato alle interazioni con LLM.

In questo tutorial imparerai a creare agenti AI strutturati che producono output convalidati e mantengono la sicurezza dei tipi. Vedremo come impostare agenti con system prompt, costruire function tool che gli LLM possono chiamare durante le conversazioni e implementare la validazione di output strutturati. Scoprirai anche come gestire le dipendenze tra i componenti degli agenti e come trasmettere le risposte in streaming per applicazioni in tempo reale. Alla fine, avrai un'esperienza pratica nella creazione di applicazioni AI che gestiscono workflow complessi.

Se cerchi un corso pratico per costruire sistemi di AI agentica, ti consiglio il corso Building Multi-Agent Systems with LangGraph. 

Che cos'è Pydantic AI?

Pydantic AI è un framework per agenti in Python che porta struttura e sicurezza dei tipi nelle applicazioni LLM. A differenza delle integrazioni di base che restituiscono testo grezzo, Pydantic AI tratta le interazioni con l'AI come conversazioni strutturate con input e output convalidati, rendendo più semplice creare applicazioni affidabili.

Caratteristiche e vantaggi principali:

• Validazione degli output strutturati — Le risposte dell'AI si conformano automaticamente ai modelli Pydantic, prevenendo errori di parsing e garantendo la coerenza dei dati
• Function tool — Gli LLM possono chiamare le tue funzioni Python durante le conversazioni, accedendo a dati reali e computazioni
• Sicurezza dei tipi — Il supporto completo al typing riduce gli errori a runtime e migliora l'assistenza dell'IDE nei workflow AI complessi
• System prompt — Definisci istruzioni chiare per i tuoi agenti AI che restano coerenti in tutte le interazioni
• Dependency injection — Condividi contesto, connessioni al database e preferenze utente in modo pulito tra tutti i componenti dell'agente
• Modalità di esecuzione multiple — Esegui gli agenti in modo sincrono, asincrono o in streaming in tempo reale in base alle esigenze
• Riutilizzabilità degli agenti — Crea gli agenti una volta e riusali in tutta l'applicazione, in modo simile ai router di FastAPI

Questo approccio trasforma l'AI dalla generazione di testo imprevedibile a interazioni tipizzate e affidabili che si integrano naturalmente nelle applicazioni Python esistenti. Invece di lottare con il prompt engineering e il parsing degli output, puoi concentrarti nel costruire la funzionalità di cui gli utenti hanno davvero bisogno.

Prerequisiti

Prima di iniziare questo tutorial, ti serviranno alcune cose:

Conoscenze richieste:

• Fondamenti di Python: Prendere confidenza con classi e funzioni
• Basi della programmazione asincrona in Python
• Nozioni base di Pydantic: comprendere modelli, validazione dei campi e annotazioni di tipo
• Familiarità con gli LLM:  Conoscenza di base di come funzionano i modelli linguistici e cosa sono i prompt

Utile ma non obbligatorio:

• Concetti di agenti:  un po' di esposizione a agenti AI e chiamata di tool, anche se lo vedremo qui

Requisiti di setup:

• Python 3.9 o superiore
• API key di OpenAI e Anthropic
• Competenze di base con terminale/riga di comando per l'installazione dei pacchetti

Se sei nuovo a Pydantic, la loro documentazione ufficiale copre bene le basi. Per i fondamenti sugli LLM, qualsiasi guida introduttiva a ChatGPT o modelli simili ti darà il contesto necessario per seguire.

Primi passi con Pydantic AI

In tutto il tutorial costruiremo un agente di analisi dei dati che ci aiuta a comprendere le performance di vendita tra diverse regioni e prodotti. Questo agente inizierà in modo semplice e diventerà più sofisticato man mano che aggiungiamo funzionalità come tool personalizzati, output strutturati e capacità di streaming.

Installazione e setup

Prima di passare al codice, installiamo Pydantic AI e configuriamo l'ambiente:

pip install pydantic-ai

Ti serviranno anche una API key di OpenAI e una API key di Anthropic. Impostale come variabili d'ambiente:

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

> Useremo sia i modelli di OpenAI che di Anthropic perché alcune funzionalità di Pydantic AI sono supportate in uno ma non nell'altro.

Per i nostri esempi di analisi dei dati useremo anche pandas per la manipolazione dei dati:

pip install pandas

Creare il tuo primo agente

Partiamo dall'agente più semplice possibile — uno che può rispondere a domande di base sui dati di vendita. In Pydantic AI, un agente è la tua principale interfaccia per le interazioni con gli LLM (esegui il codice seguente in uno script 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)

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.

Questo crea un agente che comprende il suo ruolo di analista delle vendite e può fornire consigli pertinenti. Il system_prompt dà all'LLM il contesto sul tipo di risposte desiderate, mentre run_sync() esegue l'agente e restituisce un risultato.

Qui, la funzione run_sync() funziona solo negli script Python. Per eseguire gli agenti in un Jupyter Notebook, puoi usare la seguente sintassi:

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

Cambiare l'LLM e le sue impostazioni

Pydantic AI supporta diversi provider di LLM e ti permette di personalizzare il comportamento del modello. Ecco come sperimentare con opzioni diverse:

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

Ogni modello porta capacità diverse nel tuo workflow di analisi dei dati. I modelli Claude eccellono nel ragionamento dettagliato e nelle analisi complesse, ideali quando ti servono insight approfonditi dai dati di vendita. GPT-4o-mini offre risposte più rapide e costi inferiori, perfetto per domande veloci o quando elabori grandi volumi di query.

Oltre a scegliere modelli diversi, puoi regolarne il comportamento tramite le impostazioni del modello:

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

Impostazioni del modello che puoi personalizzare:

• temperature — Controlla la creatività (0,0 = focalizzato, 1,0 = creativo)
• max_tokens — Limita la lunghezza della risposta
• top_p — Alternativa a temperature per controllare la casualità

Per i compiti di analisi dei dati, valori di temperature più bassi (0,1–0,3) funzionano in genere meglio, dato che vuoi risposte coerenti e fattuali piuttosto che interpretazioni creative. Impostare max_tokens aiuta a controllare la lunghezza della risposta, utile quando servono riassunti concisi o hai vincoli di costo API.

Uso dei tool negli agenti

Finora il nostro agente di analisi delle vendite può lavorare solo con le informazioni che forniamo nei prompt. Ma l'analisi dei dati reale spesso richiede l'accesso a informazioni esterne, l'esecuzione di calcoli o la connessione a sistemi aziendali. Qui entrano in gioco i tool — danno al tuo agente la capacità di agire e raccogliere informazioni durante le conversazioni.

Tool integrati

I tool integrati sono funzioni pronte all'uso fornite dai provider di LLM. Pydantic AI supporta tool di ricerca web ed esecuzione di codice che girano direttamente sull'infrastruttura del provider.

Iniziamo con la ricerca web, perfetta per ottenere informazioni di mercato aggiornate:

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

Questo cambia la tua analisi dei dati da lavoro su informazioni datate a includere dati di mercato in tempo reale. Invece di analizzare i dati da solo, il tuo agente può ora confrontare la performance della tua azienda con i trend attuali del settore.

Ora aggiungiamo l'esecuzione di codice per analisi matematiche ed elaborazione dei dati:

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)

L'esecuzione di codice va oltre le semplici risposte testuali per arrivare all'analisi computazionale reale. Il tuo agente può ora eseguire calcoli complessi, creare visualizzazioni ed elaborare dati impossibili da gestire solo tramite conversazione. L'oggetto result contiene sia l'analisi dell'agente sia eventuali file generati durante l'esecuzione del codice, che puoi scaricare per un uso successivo.

Scrivere tool personalizzati

Sebbene i tool integrati siano utili, spesso avrai bisogno di tool personalizzati che funzionino con i tuoi sistemi aziendali specifici. I tool personalizzati sono funzioni Python che il tuo agente può chiamare durante le conversazioni.

Creiamo dei tool che calcolano metriche di vendita comuni:

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.

Questi tool personalizzati gestiscono calcoli specifici di vendita che la tua azienda usa regolarmente. Il tool per il tasso di conversione aiuta a misurare la performance del marketing, mentre quello per il valore medio dell'ordine traccia i pattern di spesa dei clienti. I tool personalizzati collegano il tuo agente alla tua logica e ai tuoi sistemi aziendali specifici.

Per pattern di tool più avanzati, inclusi dependency injection e gestione degli errori, consulta la documentazione completa sui tool.

Uso degli output strutturati

Finora i nostri agenti hanno restituito risposte in testo semplice, che vanno bene per l'esplorazione ma creano problemi nelle applicazioni in produzione. Quando devi elaborare le risposte dell'agente in modo programmatico, estrarre punti dati specifici o integrare gli output dell'AI con altri sistemi, serve una struttura garantita.

Poniamo che tu voglia analizzare dati di vendita e ottenere sempre specifiche metriche. Con il testo semplice, l'AI potrebbe restituire formati diversi ogni volta. Con gli output strutturati, definisci esattamente cosa vuoi:

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.

Nota il parametro output_type=SalesInsight. Indica all'agente che deve restituire un oggetto SalesInsight con esattamente quei quattro campi. Né più né meno. Il risultato arriva come result.output, automaticamente validato e tipizzato.

Gli output strutturati funzionano convertendo il tuo modello Pydantic in uno schema JSON che l'LLM segue. L'AI non può deviare dalla tua struttura — se prova a restituire qualcos'altro, Pydantic AI le chiederà di riprovare.

Per scenari di analisi più complessi, puoi annidare modelli e usare liste:

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+

Questo approccio trasforma l'AI dalla generazione di testo imprevedibile all'elaborazione affidabile dei dati. Puoi salvare ogni metrica regionale in un database, innescare avvisi in base alle valutazioni delle performance o generare automaticamente dashboard per i dirigenti. Niente regex, niente gestione di formati di risposta diversi — solo dati puliti e convalidati ogni volta.

Il parametro output_type accetta qualsiasi modello Pydantic, dataclass Python, TypedDict o anche tipi semplici come int o list[str]. Per i workflow di analisi dei dati, questo significa poter costruire pipeline affidabili in cui l'analisi AI fluisce direttamente nei sistemi aziendali esistenti.

Messaggi e cronologia chat negli agenti Pydantic

Quando lavori con agenti di analisi dei dati, spesso servono conversazioni che si estendono in più interazioni. Magari inizi chiedendo i trend di vendita, poi vuoi approfondire regioni specifiche o confrontare periodi diversi. Messaggi e cronologia chat ti permettono di mantenere il contesto in queste conversazioni.

Accedere alla cronologia dei messaggi

Ogni volta che esegui un agente, Pydantic AI tiene traccia dell'intera conversazione. Puoi accedere a questa cronologia per capire cosa è successo o continuare la conversazione in seguito:

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

Il metodo all_messages() ti restituisce tutto: system prompt, domande dell'utente e risposte dell'agente. Il metodo new_messages() restituisce solo quanto accaduto nell'esecuzione corrente. È utile quando costruisci conversazioni più lunghe e vuoi tenere traccia di ciò che è cambiato.

Proseguire le conversazioni con la cronologia

Per costruire sulla conversazione precedente, passa la cronologia dei messaggi alla prossima esecuzione dell'agente. In questo modo l'agente ricorda cosa avete discusso prima:

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

Ogni nuova esecuzione si basa sul contesto precedente. L'agente ricorda non solo le tue domande, ma anche le sue risposte precedenti, creando una conversazione analitica coerente.

Salvare e caricare i messaggi in JSON

Per l'archiviazione a lungo termine o la condivisione di conversazioni tra sistemi, puoi serializzare la cronologia dei messaggi in 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")

Il metodo all_messages_json() restituisce la conversazione come byte JSON, perfetti per salvarli in database, inviarli tramite API o archiviare sessioni di analisi. Esiste anche new_messages_json() se vuoi salvare solo l'ultima parte della conversazione.

Questo approccio ti permette di costruire workflow analitici persistenti. Potresti salvare la sessione di analisi di ogni cliente, riprendere indagini dati complesse su più giorni o condividere il contesto della conversazione tra membri del team che lavorano sulla stessa analisi.

Lavorare con immagini e documenti

L'analisi dei dati reale coinvolge spesso più di testo e numeri. Potresti dover analizzare grafici di report, estrarre dati da PDF o interpretare grafici e visualizzazioni. Pydantic AI supporta input di immagini e documenti, consentendo ai tuoi agenti di lavorare direttamente con queste fonti di dati ricche.

Analizzare immagini da URL

Quando hai grafici o visualizzazioni ospitati online, puoi puntare il tuo agente direttamente a essi:

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)

L'agente può identificare i tipi di grafico, leggere i valori dagli assi, individuare trend e fornire insight di business proprio come farebbe un analista umano osservando la stessa visualizzazione.

Lavorare con immagini locali

Per le immagini archiviate in locale — come screenshot dei tuoi strumenti BI o grafici esportati da Excel — usa 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)

Questo approccio è ottimo per workflow di reportistica automatizzata. Potresti fare screenshot dei dashboard in modo programmatico e poi far generare all'AI un'analisi scritta a corredo delle visualizzazioni.

Analizzare documenti da URL

Molti documenti aziendali sono condivisi tramite URL — report su intranet aziendali, PDF in cloud storage o articoli di ricerca pubblici che informano la tua analisi:

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)

L'agente può leggere interi documenti, estrarre punti dati rilevanti e fornire sintesi che ai umani richiederebbero molto più tempo per compilare.

Elaborare documenti locali

Per documenti sul tuo sistema locale — come report esportati, contratti o presentazioni interne — usa 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)

Questo apre potenti possibilità di automazione. Potresti processare pile di report, estrarre dati dalle fatture o analizzare i termini dei contratti — tutte attività che normalmente richiedono revisione manuale.

Note importanti:

Modelli diversi supportano formati di file diversi. La maggior parte gestisce i formati immagine comuni (PNG, JPEG) e i PDF, ma controlla la documentazione del tuo modello per i dettagli. Alcuni modelli come Vertex AI di Google possono accedere direttamente a URL di cloud storage, mentre altri scaricano prima il contenuto.

Per i workflow di analisi dei dati, questa capacità multimodale colma il divario tra i tuoi report visivi e gli insight generati dall'AI, rendendo possibile automatizzare l'analisi dell'intera gamma di documenti aziendali con cui lavori ogni giorno.

Abilitare lo streaming in Pydantic AI

Quando affronti compiti complessi di analisi dei dati, vuoi vedere i risultati man mano che vengono generati, invece di attendere la risposta completa. Lo streaming permette agli utenti di osservare l'analisi in tempo reale, utile quando poni domande dettagliate sulla performance di vendita.

Pydantic AI offre lo streaming integrato tramite il metodo run_stream(). Ecco come funziona:

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

Capire la sintassi dello streaming:

L'async with crea una connessione con l'LLM che resta aperta mentre ricevi i blocchi di testo. Pensala come una telefonata: devi stabilire la connessione, avere la conversazione e poi chiudere correttamente.

Il ciclo async for elabora ogni blocco di testo appena arriva. Nota che stream_text() rigenera il testo completo ogni volta: quindi ottieni "Ciao", poi "Ciao mondo", poi "Ciao mondo, come". Questo ti dà il contesto completo ma può essere ripetitivo per la visualizzazione.

Perché async e asyncio funzionano insieme:

Quando fai una domanda a un LLM, serve tempo per generare la risposta — di solito 3–10 secondi. In questo periodo, il modello invia piccoli pezzi di testo ogni 50–200 millisecondi.

Senza async, il tuo programma resterebbe completamente bloccato in attesa di ogni pezzo. Con async, l'event loop di Python (il sistema che gestisce questi tempi di attesa) può passare tra i task. Ciò significa che il programma resta reattivo e può persino eseguire più conversazioni contemporaneamente.

asyncio.run() è ciò che avvia l'intero processo: crea l'event loop che coordina tutto. Quando chiami asyncio.run(demo_streaming()), imposta l'ambiente in cui le funzioni async possono mettersi in pausa e riprendere secondo necessità mentre attendono le risposte dell'LLM.

Ora creiamo una funzione riutilizzabile che mostri solo i delta di testo nuovi per un'esperienza di streaming migliore:

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

Scomposizione della funzione di streaming:

La funzione stream_agent_response() crea un'esperienza di streaming più naturale mostrando solo il nuovo testo in arrivo. Ecco come funziona:

1. Configurazione dell'event handler: la funzione interna event_handler() ascolta eventi specifici durante l'elaborazione dell'agente. Filtra per PartDeltaEvent con TextPartDelta: rappresentano nuovi pezzi di testo generati.
2. Contenuto delta: invece di ottenere il testo rigenerato completo ogni volta, event.delta.content_delta fornisce solo le parole o i caratteri nuovi. Questo crea un effetto macchina da scrivere in cui vedi la risposta scriversi parola per parola.
3. Esecuzione dell'agente: usiamo agent.run() con il parametro event_stream_handler. Questo dice all'agente di chiamare il nostro handler personalizzato per ogni evento di streaming, dandoci un controllo granulare su cosa viene mostrato.
4. Output in tempo reale: print(event.delta.content_delta, end="", flush=True) mostra subito ogni nuovo pezzo senza andare a capo, creando un testo fluido e continuo.

Questo approccio ti dà la sensazione naturale di osservare l'AI che ragiona sull'analisi in tempo reale, invece di aspettare una risposta completa o vedere testo rigenerato in modo ripetitivo. Useremo questa funzione nelle sezioni successive per mostrare risposte in streaming nei nostri esempi di analisi dei dati.

Conclusione

In questo tutorial hai costruito una comprensione completa di Pydantic AI attraverso esempi pratici di analisi dei dati. Hai imparato a creare agenti con system prompt, aggiungere tool integrati e personalizzati, strutturare gli output con modelli Pydantic e trasmettere le risposte in streaming per un feedback in tempo reale. Questi componenti si combinano per creare sistemi di AI che si comportano più come partner analitici che semplici chatbot.

Le applicazioni vanno ben oltre gli esempi di analisi delle vendite trattati. Ora puoi creare agenti AI che leggono le tue specifiche fonti dati, seguono le tue regole di business e restituiscono risultati in formati compatibili con i tuoi sistemi esistenti. Che tu stia automatizzando la generazione di report, analizzando il feedback dei clienti o elaborando dati finanziari, Pydantic AI ti offre la struttura e l'affidabilità necessarie per applicazioni di produzione.

Se ti interessa creare sistemi multi-agente con LangGraph, dai un'occhiata al nostro corso pratico.