Pydantic AI: guida agli agenti Python con output validati

Contenuti verificati sulla documentazione del produttore e sulla licenza del repository il 17 ottobre 2026. I criteri di scelta sono la validazione dell'output, l'accesso ai servizi dell'applicazione, la responsabilità sul workflow e il ripristino dopo un'interruzione: non una classifica delle prestazioni.

Che cos'è Pydantic AI?

Pydantic AI è l'SDK per agenti Python sviluppato dal team di Pydantic. Riunisce un modello, le istruzioni, le funzioni Python richiamabili e un eventuale tipo di output in un Agent, l'oggetto che l'applicazione esegue. Il modello genera le risposte; l'SDK gestisce le interazioni che gli ruotano attorno. La panoramica attuale descrive un SDK più ampio, ma questo è il nucleo necessario per una funzionalità di prodotto.

È come assegnare a un collaboratore imprevedibile il contratto di una funzione. L'applicazione fornisce il contesto e le operazioni consentite, poi richiede un risultato con campi definiti. È utile, per esempio, quando una funzionalità di assistenza deve restituire una categoria e un'azione successiva che il normale codice Python possa elaborare.

Gli agenti di Pydantic AI: un'unità riutilizzabile

Un Agent contiene la configurazione di un compito. Una singola esecuzione è un tentativo di svolgerlo con un prompt e dipendenze fornite a runtime. Da uno script sincrono si può chiamare run_sync(); nel codice asincrono dell'applicazione si usa await agent.run(). Al termine, il risultato espone il valore finale tramite .output. Sono le API di Agent documentate.

La tipizzazione svolge due compiti distinti. Quella statica aiuta l'editor o il type checker a individuare incompatibilità nel codice Python. La validazione dell'output a runtime confronta invece i dati restituiti dal modello con lo schema dichiarato. Nessuna delle due elimina l'ambiguità di una richiesta di assistenza.

I tool di Pydantic AI: funzioni con accesso al contesto applicativo

I tool basati su funzioni permettono al modello di richiedere un'operazione che il codice sa eseguire, come consultare un abbonamento. Per registrare una funzione che accede al contesto si usa @agent.tool; se il contesto dell'esecuzione non serve, si usa @agent.tool_plain. Le annotazioni di tipo descrivono gli argomenti e le docstring aiutano a spiegare il tool al modello. La documentazione sui tool basati su funzioni illustra come da questi elementi si ricavino gli schemi dei tool.

La dependency injection consiste nel passare a ogni esecuzione i servizi di cui ha bisogno. Con deps_type=CustomerContext si dichiara il tipo Python atteso; con deps=customer_context si passa l'istanza effettiva. Il tool riceve RunContext[CustomerContext] e vi accede tramite ctx.deps. Il contesto può contenere un cliente autenticato, una connessione al database o un client API. La guida alle dipendenze precisa che deps_type serve al controllo dei tipi, non alla validazione a runtime dell'oggetto passato come dipendenza.

Per chi sviluppa un SaaS, il vantaggio è concreto: il server può selezionare l'account del cliente prima che il modello richieda una consultazione. L'autorizzazione deve restare nel codice che effettua la ricerca. Passare un client del database attraverso un contesto tipizzato non limita le righe che quel client può leggere.

Output strutturato in Pydantic AI: che cosa viene validato?

output_type definisce il risultato che l'applicazione si aspetta di ricevere. Passando un BaseModel di Pydantic, una classe Python con campi tipizzati, Pydantic AI ricava uno schema e valida i dati generati. La documentazione sull'output prevede anche altri tipi, tra cui dataclass, liste e unioni.

Le tre modalità di output cambiano il modo in cui si chiede al modello di produrre quei dati:

Sono le tre modalità di output documentate dell'SDK, non tre livelli di accuratezza. Occorre scegliere il meccanismo supportato dal modello e poi valutare il risultato sul compito da svolgere.

Un errore di validazione può essere restituito al modello perché riprovi. Il numero di tentativi è limitato e, una volta esauriti quelli previsti per l'output, può essere sollevata l'eccezione UnexpectedModelBehavior. L'applicazione deve prevedere come gestire il fallimento, per esempio chiedendo le informazioni mancanti o passando la richiesta a una persona. Il funzionamento è descritto nella documentazione sui tentativi successivi.

Tutorial Pydantic AI: classificare una richiesta di assistenza con un risultato validato

Il primo passo è un oggetto decisionale in sola lettura, prima di autorizzare l'agente a modificare qualcosa. Questo esempio adatta i pattern documentati di Agent, RunContext e output_type a un piccolo compito di classificazione delle richieste di assistenza.

L'attuale guida all'installazione richiede Python 3.11 o successivo. In un ambiente virtuale, installare la libreria:

python -m pip install pydantic-ai

Impostare OPENAI_API_KEY nell'ambiente usando un account che abbia accesso al modello. Salvare il codice seguente in triage.py ed eseguire python triage.py. L'identificativo del modello segue la documentazione attuale di Agent; si può sostituire con un modello supportato e disponibile per il proprio account.

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Customer:
    plan: str

class Triage(BaseModel):
    category: Literal['billing', 'technical']
    priority: Literal['normal', 'urgent']
    summary: str

agent = Agent(
    'openai:gpt-6.1-sol',
    deps_type=Customer,
    output_type=Triage,
    instructions=(
        'Triage the support message. Use customer_plan for context. '
        'Summarize the issue without inventing account facts.'
    ),
)

@agent.tool
def customer_plan(ctx: RunContext[Customer]) -> str:
    """Return the authenticated customer's plan."""
    return ctx.deps.plan

if __name__ == '__main__':
    result = agent.run_sync(
        'I was charged twice for my subscription.',
        deps=Customer(plan='business'),
    )
    print(result.output.model_dump())

Se l'esecuzione va a buon fine, result.output è un oggetto Triage. Categoria e priorità devono rientrare tra le opzioni dichiarate; model_dump() converte l'oggetto in un dizionario. Il tool che legge il contesto, il risultato tipizzato e il rifiuto di una categoria non valida sono stati verificati offline con TestModel. La formulazione generata dal modello e l'accuratezza della classificazione vanno comunque valutate sui propri casi.

Il contesto del cliente è puramente illustrativo. In un prodotto va costruito a partire dalla richiesta autenticata e dai dati dell'account. Occorre anche definire che cosa rende urgente un caso: lo schema elenca le etichette valide, ma non contiene una regola per assegnare l'urgenza. Colmare questa lacuna nelle regole aziendali conta più che aggiungere un altro agente.

Modelli in Pydantic AI: cambiare provider non significa ottenere gli stessi risultati

Pydantic AI riduce il codice di integrazione specifico per ogni provider, ma cambiare modello ne cambia comunque il comportamento. Molte integrazioni usano un identificativo <provider>:<model>. Alcune richiedono un modello o un client esplicito, le credenziali appropriate e componenti aggiuntivi da installare. Le funzionalità disponibili dipendono dal modello e dall'API scelti, come chiarisce l'elenco dei provider.

L'elenco include OpenAI, Anthropic, Google/Gemini, AWS Bedrock, Groq, Mistral, xAI e Ollama. Le altre integrazioni documentate comprendono:

• Servizi di modelli e inferenza: Alibaba Cloud/Qwen, Cerebras, Cohere, Crusoe, DeepSeek, Fireworks AI, Heroku AI, Hugging Face, Meta, Moonshot AI/Kimi, Nebius AI Studio, OVHcloud AI Endpoints, SambaNova, Snowflake Cortex, Together AI e Z.AI.
• Opzioni cloud, gateway e self-hosted: Google Cloud/Vertex AI, Microsoft Azure/Foundry, Pydantic AI Gateway, LiteLLM, OpenRouter, Vercel AI Gateway e vLLM.
• Altre modalità di accesso e integrazioni per modelli decisionali: GitHub Copilot, OpenAI Codex, OpenAI Decisions API, System One API e TypeSafe (Jev).

Questi nomi indicano modi diversi di accedere ai modelli, non insiemi di funzionalità intercambiabili. Un modello locale può usare i tool in modo diverso da un modello di frontiera ospitato da un provider; anche un'API compatibile può imporre vincoli diversi sugli schemi.

Per chi fonda un'impresa, la portabilità offre una via d'uscita e spazio per sperimentare. Per chi la implementa, il criterio di accettazione resta lo stesso: il modello sostitutivo sceglie i tool corretti, rispetta lo schema di output e prende decisioni accettabili sugli stessi casi? Servono queste evidenze prima di cambiare il modello predefinito in produzione.

MCP ed esecuzione durevole: collegare i tool e conservare i progressi

MCP collega l'agente ai server di tool; l'esecuzione durevole permette di proseguire dopo un'interruzione. Risolvono problemi diversi.

Il Model Context Protocol, o MCP, standardizza il modo in cui le applicazioni espongono tool e contesto ai client AI. Il supporto MCP di Pydantic AI accetta URL di server, client o toolset e, dove disponibili, opzioni MCP native del provider. Consente di riutilizzare un server di tool senza scrivere una nuova integrazione per ogni agente. Non decide quali clienti siano autorizzati a eseguire le operazioni di quel server.

Per esecuzione durevole si intende la conservazione dei progressi, così da poter riprendere il lavoro dopo un errore, un riavvio o una lunga attesa. L'attuale documentazione sull'esecuzione durevole indica 9 soluzioni:

• Mantenute insieme ai team dei rispettivi fornitori: Temporal, DBOS, Prefect, Restate e AWS Lambda.
• Integrazioni SDK esterne: Kitaru, Apache Airflow, Absurd e pgtask.

È disponibile anche uno strumento per costruire backend per altri motori. Quando un agente deve continuare a lavorare oltre la durata della richiesta o del processo che lo ha avviato, conviene scegliere un'integrazione documentata. La disponibilità di queste integrazioni non rende durevole, da sola, una semplice invocazione di Agent.

Si pensi a un'attività di assistenza che prepara una proposta di rimborso, attende l'approvazione e poi la applica. Salvare l'esecuzione permette di conservare il lavoro in attesa, ma l'operazione di pagamento deve comunque essere idempotente: ripetere la richiesta non deve generare un altro rimborso. Occorre stabilire come riconoscere un'operazione già eseguita e come verificare e riconciliare un esito incerto. È una responsabilità dell'applicazione che si affianca al lavoro del motore.

Pydantic AI Evals: valutare la decisione, oltre alla struttura dell'oggetto

Pydantic Evals verifica se l'agente ha svolto il compito in modo accettabile, andando oltre la possibilità di analizzarne l'output. È un pacchetto di valutazione separato, configurato tramite codice, che non richiede Pydantic AI. Si definiscono casi e valutatori, si esegue il compito su quei casi e si esamina un report. La documentazione descrive la valutazione sia degli output finali sia delle sequenze di chiamate ai tool, cioè delle azioni compiute durante un'esecuzione.

Per l'esempio di classificazione, servono casi che coprano un doppio addebito, un accesso non riuscito, l'assenza del contesto dell'account e un messaggio che chieda all'assistente di ignorare le proprie istruzioni. Vanno verificati la categoria, la decisione di passare il caso a un livello di assistenza superiore e l'effettiva consultazione dell'account quando richiesta. Vanno inclusi anche casi in cui la risposta accettabile è fare una domanda.

Per chi gestisce il sistema, una traccia spiega una singola esecuzione; una valutazione misura il comportamento su più casi. Pydantic AI usa OpenTelemetry, uno standard per la telemetria applicativa, e supporta altri backend di osservabilità tramite la propria strumentazione. Quando un caso fallisce, occorre esaminare la richiesta al modello e le chiamate ai tool, poi conservare quel caso nell'insieme di valutazione.

Il servizio opzionale Pydantic Logfire offre il tracciamento di agenti, modelli e tool. Secondo la pagina dei prezzi, il piano Personal è gratuito e Team parte da $49/mese, con consumi aggiuntivi e posti utente fatturati separatamente.

Quando scegliere Pydantic AI rispetto a un altro framework

L'astrazione giusta è quella che corrisponde alla parte difficile della funzionalità. Chi sviluppa in Python e dispone già di modelli di dominio e servizi dovrebbe valutare Pydantic AI quando il problema principale è integrare input, tool e output tipizzati. Un fondatore con competenze tecniche dovrebbe chiedersi quale scelta porti al sistema più essenziale che l'azienda sappia comprendere e mantenere.

Pydantic AI o LangGraph?

LangGraph è un punto di partenza più adatto quando si vuole progettare in modo esplicito il workflow attorno all'agente. La sua documentazione mette al centro gli agenti con stato e di lunga durata, l'esecuzione durevole e l'intervento umano. Si pensi a un'applicazione con passaggi obbligatori: raccogliere evidenze, ottenere l'approvazione, eseguire un'azione autorizzata e riconciliarne l'esito.

Pydantic AI è interessante quando l'agente tipizzato è un componente di un processo già controllato dall'applicazione. Può anche partecipare a workflow durevoli, quindi la persistenza da sola non basta a decidere. La domanda è se si vuole modellare il processo aziendale attorno all'agente oppure configurare soprattutto il comportamento dell'agente stesso. Con LangGraph, l'onere è progettare il workflow e gestirne lo stato; con Pydantic AI, il limite è che la comodità del contratto dell'agente non sostituisce la progettazione dell'intero processo.

Pydantic AI o LangChain?

LangChain ha senso quando le sue integrazioni con modelli e tool e la sua architettura per agenti si adattano già all'applicazione. Gli agenti di LangChain sono costruiti su LangGraph, come spiega la panoramica di LangChain. Scegliere la sua API per agenti di livello più alto non significa quindi rinunciare a quella base di runtime.

Pydantic AI è indicato per un servizio Python in cui i contratti delle dipendenze e dell'output rispecchiano il modo in cui si scrive già il codice. Se una funzionalità basata su LangChain funziona, conviene mantenerla, a meno di poter indicare una fonte concreta di complessità che la migrazione eliminerebbe. Quando il comportamento attraversa i livelli dell'agente e del workflow, occorre comunque comprendere l'astrazione di LangChain: cambiare libreria sposta semplicemente quel lavoro altrove. Il rapporto tra i due strumenti è approfondito in LangChain e LangGraph a confronto.

OpenAI Agents SDK o chiamate API dirette?

OpenAI Agents SDK è adatto a un ciclo di esecuzione dell'agente gestito dall'applicazione, con tool, passaggi di consegne e tracciamento. L'SDK viene eseguito nell'applicazione e supporta output strutturati; le sue interfacce per i provider consentono anche l'uso di modelli non OpenAI. Presentare gli output tipizzati o la scelta del provider come esclusive di Pydantic AI sarebbe quindi scorretto.

Conviene scegliere quell'SDK quando il suo modello di agenti e passaggi di consegne si integra bene con l'architettura OpenAI che si intende mantenere. Pydantic AI è preferibile quando il suo sistema di dipendenze Python e la configurazione dei provider sono più adatti all'applicazione. In entrambi i casi, deployment, autorizzazioni dei tool e correttezza applicativa restano responsabilità di chi sviluppa.

Le chiamate API dirette bastano quando il compito è una richiesta al modello accompagnata da poco codice deterministico. Le API dirette possono già restituire output vincolati da uno schema. Un estrattore di dati dalle ricevute non richiede un framework per agenti solo perché il risultato è un oggetto Pydantic. Il limite emerge quando, in più funzionalità, si ricostruiscono ripetutamente i cicli di chiamata ai tool, i nuovi tentativi dopo errori di validazione e la strumentazione.

Per un confronto più ampio, si può consultare la guida ai framework per agenti AI. Se il dubbio riguarda il controllo esplicito del workflow oppure l'assegnazione di ruoli specialistici agli agenti, il passo successivo è LangGraph e CrewAI a confronto.

Agenti tipizzati: quali promesse sono esagerate?

La promessa eccessiva è che un agente tipizzato sia automaticamente un sistema corretto e pronto per la produzione. La libreria non può eliminare alcuni limiti:

• La sicurezza dei tipi non garantisce l'accuratezza dei fatti. Una risposta ben formata può fraintendere la richiesta dell'utente. Occorre decidere che cosa verificare su fonti autorevoli.
• La portabilità tra modelli non garantisce la stessa qualità. Una nuova configurazione del provider richiede la stessa valutazione sul compito prevista per un nuovo prompt.
• L'esecuzione durevole non rende automatico il deployment. Vanno scelti e gestiti il motore, l'archiviazione e il percorso di ripristino necessari alla funzionalità.
• Ogni nuovo tentativo comporta altro lavoro. Una richiesta aggiuntiva al modello aumenta latenza e consumi. L'applicazione deve prevedere un esito esplicito quando i tentativi si esauriscono.

Vale la pena procedere se la prossima funzionalità Python ha già bisogno di tool e decisioni strutturate. Meglio rimandare una migrazione di framework se il sistema esistente funziona e l'unico vantaggio proposto è una demo con codice più elegante. Per una semplice chiamata di estrazione con validazione e gestione degli errori adeguate, cambia poco.

Domande frequenti su Pydantic AI

Che cosa portare in produzione la prossima settimana

Prima di aumentare l'autonomia, definire criteri di accettazione chiari per una piccola funzionalità in sola lettura. Per un prodotto di assistenza, si può partire dall'oggetto di classificazione dell'esempio e lasciare l'azione finale sull'account al normale codice applicativo.

Per consigli pratici sullo sviluppo di funzionalità AI, iscriviti alla newsletter.