Pydantic AI: De Productiegids (Voorbij Hello World)

Pydantic AI: De Productiegids (Voorbij Hello World)

Ruwe LLM-outputs breken applicaties. U vraagt om JSON en krijgt Markdown. U vraagt om een getal tussen 1 en 10 en krijgt "Zeker! Hier is een getal: zeven." Als u iets echts hebt gebouwd met LLM-API's, heeft u defensieve parseercode geschreven die u doet twijfelen aan uw carrièrekeuzes. Pydantic AI lost dit op -- het is het type-veilige agentframework gebouwd door hetzelfde team achter Pydantic en FastAPI. Zie het als "FastAPI voor AI-agenten": u definieert wat u wilt met Python-type-hints, en het framework behandelt validatie, herhaalpogingen en tool-aanroepen.

Deze Pydantic AI-gids is voor ontwikkelaars die al hun eerste LLM-aanroep hebben gedaan en productiepatronen willen: gestructureerde outputs die niet breken, dependency injection voor testbare agenten, en echte tools voorbij weerAPIs. Aan het einde hebt u werkende agenten met tools, DI, streaming en tests.

Pydantic AI in één Oogopslag

De uitblinkende functies zijn gestructureerde outputs (gevalideerd met Pydantic-modellen), dependency injection (zoals FastAPI's Depends), en TestModel (nep-LLM voor testen zonder API-aanroepen). Als u van LangChain komt en vraagt "is er iets schoners?", is dit het waarschijnlijk.

Installatie en Eerste Agent

# Installeren met OpenAI-ondersteuning (vervang openai door anthropic, google, enz.)
pip install "pydantic-ai[openai]"

# Uw API-sleutel instellen
export OPENAI_API_KEY="sk-..."

Uw eerste agent in 5 regels:

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o", system_prompt="You are a helpful assistant.")

result = agent.run_sync("What's the capital of France?")
print(result.output)  # "Paris"

Dat is het. Agent omhult het model, run_sync stuurt een prompt en geeft een resultaat terug. Het result.output is hier een gewone string, maar dat verandert zo.

Gestructureerde Outputs -- Waarom Pydantic AI Bestaat

Dit is de kernfunctie. In plaats van een string terug te krijgen van de LLM en te hopen dat het geldig JSON is, definieert u een Pydantic-model en de agent geeft een gevalideerd Python-object terug.

Vóór: Ruwe LLM-output

# De oude manier -- hoop op het beste
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Review the movie Inception. Return JSON with title, rating (1-10), summary."}]
)
# response.choices[0].message.content is een string
# Misschien is het JSON. Misschien heeft het Markdown-codefences. Misschien is rating "eight".
# U bent op uzelf aangewezen.

Na: Gestructureerd met Pydantic AI

from pydantic import BaseModel
from pydantic_ai import Agent

class MovieReview(BaseModel):
    title: str
    rating: int  # Gegarandeerd een int, niet "eight"
    summary: str
    recommended: bool

agent = Agent("openai:gpt-4o", result_type=MovieReview)

result = agent.run_sync("Review the movie Inception")
review = result.output  # Dit is een MovieReview-instantie, geen string

print(f"{review.title}: {review.rating}/10")
print(f"Aanbevolen: {review.recommended}")
print(review.summary)

Het verschil is als dag en nacht. result.output is een echt MovieReview-object. Als de LLM rating: "eight" teruggeeft in plaats van rating: 8, vangt Pydantic's validatie dit op. Voor een diepere blik op hoe dit werkt bij verschillende providers, zie onze gids over gestructureerde outputs bij LLM-providers.

Wat Er Gebeurt Als Validatie Mislukt

Hier is het deel dat geen ander tutorial laat zien: wat er gebeurt als de LLM een fout maakt?

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class StrictReview(BaseModel):
    title: str
    rating: int = Field(ge=1, le=10)  # Moet 1-10 zijn
    pros: list[str] = Field(min_length=2)  # Minimaal 2 voordelen

agent = Agent("openai:gpt-4o", result_type=StrictReview)

# Als de LLM rating=15 teruggeeft of slechts 1 voordeel:
# 1. Pydantic-validatie mislukt
# 2. De foutmelding wordt TERUG naar de LLM gestuurd
# 3. De LLM probeert het opnieuw met de gecorrigeerde output
# 4. Dit herhaalt zich tot de herhaalgrens
result = agent.run_sync("Review the movie Inception")

Deze herhaal-met-feedback-lus is Pydantic AI's killer-feature. De LLM leert van zijn eigen validatiefouten. U schrijft geen herhaalpogingslogica -- het framework regelt het.

Oordeel: Gestructureerde outputs zijn de beste reden om Pydantic AI te gebruiken boven ruwe API-aanroepen. Als u LLM JSON met de hand parseert, stop dan.

Tools en Functie-aanroepen

Tools laten uw agent Python-functies aanroepen om echte gegevens te krijgen. In plaats van dat de LLM feiten hallucineert, kan het uw database raadplegen, uw documenten doorzoeken of een API aanroepen.

Een Tool Registreren

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o")

@agent.tool
async def search_docs(query: str) -> str:
    """Search the documentation for relevant articles."""
    # Uw eigen zoeklogica hier
    results = await doc_search_engine.search(query, limit=5)
    return "\n".join(r.title + ": " + r.snippet for r in results)

De @agent.tool-decorator registreert de functie. Pydantic AI leest de type-hints en docstring van de functie om de LLM te vertellen wat de tool doet, welke argumenten hij accepteert en wat hij teruggeeft. Geen handmatig schema schrijven -- uw type-hints ZIJN het schema. Voor achtergrond over hoe LLM-functie-aanroepen onder de motorkap werken hebben we een speciale gids.

RunContext: Gegevens Doorgeven aan Tools

Hier wijkt Pydantic AI af van andere frameworks. RunContext laat u runtime-gegevens (databaseverbindingen, gebruikersinformatie, API-clients) doorgeven aan uw tools zonder globale state.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class SupportDeps:
    customer_id: str
    db_connection: DatabaseConnection

agent = Agent("openai:gpt-4o", deps_type=SupportDeps)

@agent.tool
async def get_order_history(ctx: RunContext[SupportDeps], limit: int = 5) -> str:
    """Fetch recent orders for the current customer."""
    orders = await ctx.deps.db_connection.query(
        "SELECT * FROM orders WHERE customer_id = $1 ORDER BY date DESC LIMIT $2",
        ctx.deps.customer_id, limit
    )
    return format_orders(orders)

De ctx.deps geeft de tool toegang tot wat u op runtime hebt doorgegeven. De tool importeert geen globale databaseverbinding -- hij ontvangt er een. Dit is dependency injection, en dit is wat uw agenten testbaar maakt.

Een Echt-Wereld Tool Voorbeeld

@agent.tool
async def run_sql_query(ctx: RunContext[SupportDeps], sql: str) -> str:
    """Run a read-only SQL query against the analytics database.
    Only SELECT queries are allowed."""
    if not sql.strip().upper().startswith("SELECT"):
        return "Error: only SELECT queries are allowed"
    results = await ctx.deps.db_connection.fetch(sql)
    return json.dumps(results, default=str)

Oordeel: Tool-aanroepen in Pydantic AI zijn schoner dan in elk ander framework dankzij type-hints die het zware werk doen. U schrijft normale Python-functies met type-annotaties. Het framework figureert de rest uit.

Dependency Injection -- De Feature die LangChain Had Willen Hebben

Als u FastAPI's Depends hebt gebruikt, begrijpt u Pydantic AI's DI-systeem al. Zo niet, hier is de korte versie: in plaats van dat uw agent naar buiten grijpt om te krijgen wat hij nodig heeft (globale databaseverbindingen, API-clients, configuratie), geeft u hem alles op runtime.

Afhankelijkheden Definiëren

from dataclasses import dataclass
from pydantic_ai import Agent

@dataclass
class AppDeps:
    db: AsyncDatabasePool
    search_client: SearchAPIClient
    current_user: User

agent = Agent(
    "openai:gpt-4o",
    deps_type=AppDeps,
    system_prompt="You are a customer support agent."
)

Afhankelijkheden Gebruiken in Tools

@agent.tool
async def lookup_account(ctx: RunContext[AppDeps]) -> str:
    """Look up the current user's account details."""
    account = await ctx.deps.db.fetchrow(
        "SELECT * FROM accounts WHERE user_id = $1",
        ctx.deps.current_user.id
    )
    return json.dumps(account, default=str)

# Uitvoeren met echte afhankelijkheden
result = await agent.run(
    "What's my account status?",
    deps=AppDeps(db=real_db, search_client=real_search, current_user=user)
)

Waarom DI Uw Agenten Testbaar Maakt

Dit is de echte beloning. In LangChain zou u context doorgeven via chain-kwargs of closures -- er is geen standaardpatroon. In Pydantic AI is het vervangen van echte afhankelijkheden door testdubbels triviaal:

# In uw testbestand
from pydantic_ai import Agent
from your_app import agent, AppDeps

async def test_account_lookup():
    mock_deps = AppDeps(
        db=MockDatabase({"user_123": {"status": "active", "plan": "pro"}}),
        search_client=MockSearch(),
        current_user=User(id="user_123")
    )
    result = await agent.run("What's my account status?", deps=mock_deps)
    assert "active" in result.output
    assert "pro" in result.output

Geen monkey-patching. Geen mocking van globale imports. U geeft gewoon andere deps door.

Oordeel: Dependency injection is waarom ervaren Python-ontwikkelaars Pydantic AI verkiezen. Het is de FastAPI-invloed die zich toont.

Modelproviders -- OpenAI, Anthropic, Gemini, Ollama

Pydantic AI is model-agnostisch. Van provider wisselen is een wijziging van één regel:

# OpenAI
agent = Agent("openai:gpt-4o")

# Anthropic
agent = Agent("anthropic:claude-sonnet-4-20250514")

# Google Gemini
agent = Agent("google-gla:gemini-2.0-flash")

# Lokale Ollama
agent = Agent("ollama:llama3.1")

Alles het andere -- tools, gestructureerde outputs, DI -- blijft identiek. Uw bedrijfslogica verandert niet wanneer u van model wisselt.

Oordeel: Model-agnostisch ontwerp betekent dat u nooit vastzit bij één provider. Begin met OpenAI voor gemak, benchmark met Anthropic en gebruik Ollama voor lokale ontwikkeling.

Streaming Antwoorden

Voor chat-UI's en realtime-applicaties is streaming essentieel. Pydantic AI ondersteunt het terwijl type-veiligheid behouden blijft:

from pydantic_ai import Agent
from pydantic import BaseModel

class AnalysisResult(BaseModel):
    summary: str
    sentiment: str
    confidence: float

agent = Agent("openai:gpt-4o", result_type=AnalysisResult)

async def stream_analysis(text: str):
    async with agent.run_stream(f"Analyze this text: {text}") as stream:
        async for partial in stream.stream_structured():
            # partial is een gedeeltelijk gevalideerd AnalysisResult
            print(f"Streaming: {partial}")

        # Het eindresultaat is volledig gevalideerd
        result = await stream.get_output()
        print(f"Eindresultaat: {result.summary} ({result.confidence:.0%} zeker)")

Dit werkt prachtig met FastAPI's StreamingResponse -- hetzelfde ecosysteem, dezelfde patronen. De Pydantic AI agenten-documentatie behandelt geavanceerde streaming-opties inclusief tekst-alleen streaming met stream_text().

Pydantic AI vs. LangGraph vs. OpenAI Agents SDK

U bent hier, dus vraagt u zich waarschijnlijk af: "moet ik Pydantic AI of LangGraph gebruiken?" Eerlijk antwoord: ze lossen verschillende problemen op, en u kunt beiden gebruiken.

Functievergelijkingstabel

Wanneer Welke te Gebruiken

Kies Pydantic AI wanneer u schone, type-veilige agentcode wilt. Het is ideaal voor enkelvoudige agenttaken met tools (klantenservicebots, data-extractie, code-reviewagenten) en situaties waar testbaarheid belangrijk is. Als uw team al FastAPI en Pydantic gebruikt, is de leercurve bijna vlak.

Kies LangGraph wanneer u complexe meerstaps-workflows nodig heeft met voorwaardelijke vertakking, menselijke goedkeuring in de lus en geavanceerd toestandsbeheer. LangGraph blinkt uit in het orkestreren van meerdere stappen, niet in de kwaliteit van individuele agenten. Voor een diepgaand overzicht, zie onze volledige LangGraph vs. CrewAI vs. OpenAI Agents SDK vergelijking.

Kies OpenAI Agents SDK wanneer u voor 100% op OpenAI zit, de eenvoudigst mogelijke opstelling wilt en geen multi-provider ondersteuning of DI nodig heeft.

Het Combinatiepatroon

Wat ervaren teams eigenlijk doen: Pydantic AI gebruiken voor individuele agenten (schone code, testbaar, getypeerde outputs) en LangGraph voor orkestratie tussen agenten (routing, toestandsmachines, voorwaardelijke logica). Ze concurreren niet -- ze zijn complementaire lagen.

# Pydantic AI agent -- schoon, testbaar, type-veilig
support_agent = Agent("openai:gpt-4o", result_type=SupportResponse, deps_type=SupportDeps)

# LangGraph grafiek -- orkestreert wanneer welke agent aan te roepen
graph = StateGraph(SupportState)
graph.add_node("classify", classify_intent)
graph.add_node("support", lambda state: support_agent.run_sync(state["query"]))
graph.add_node("escalate", escalate_to_human)

Oordeel: Kies Pydantic AI voor schone, testbare agentcode. Kies LangGraph voor complexe meerstaps-workflows. Ze sluiten elkaar niet uit.

Uw Agenten Testen met TestModel

Dit is de sectie die een beginnersgids onderscheidt van een productiegids. Elke echte codebase heeft tests nodig, en agenten testen is notoir moeilijk -- LLM-aanroepen zijn traag, duur en niet-deterministisch. Pydantic AI levert een oplossing: TestModel.

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic import BaseModel

class SupportResponse(BaseModel):
    answer: str
    confidence: float
    escalate: bool

agent = Agent("openai:gpt-4o", result_type=SupportResponse)

# In tests: het echte model vervangen door TestModel
def test_support_agent():
    with agent.override(model=TestModel()):
        result = agent.run_sync("I need help with billing")
        # TestModel geeft geldige gestructureerde data terug die overeenkomt met uw result_type
        assert isinstance(result.output, SupportResponse)
        assert isinstance(result.output.confidence, float)
        assert isinstance(result.output.escalate, bool)

TestModel genereert geldige gegevens die overeenkomen met uw result_type zonder API-aanroepen te doen. Nul kosten, deterministisch, snel. De Pydantic AI testdocumentatie behandelt geavanceerde patronen zoals FunctionModel voor aangepaste antwoorden en capture_run_messages voor het inspecteren van tool-aanroepen.

Tools en DI Samen Testen

def test_order_lookup_tool():
    # Nep-afhankelijkheden
    mock_deps = SupportDeps(
        customer_id="test-123",
        db_connection=MockDB(orders=[{"id": "ord-1", "status": "shipped"}])
    )

    with agent.override(model=TestModel()):
        result = agent.run_sync(
            "Where is my order?",
            deps=mock_deps
        )
        assert isinstance(result.output, SupportResponse)

Geen API-aanroepen. Geen wankele tests. Geen kosten. Voer dit uit in CI/CD naast de rest van uw testsuite.

Dit is de #1 inhoudslacune op het gehele SERP. Geen andere Pydantic AI-gids behandelt testen. Als u agenten bouwt voor productie, is dit wat u nodig heeft.

Observability -- Logfire-integratie in 5 Minuten

Productieagenten hebben AI-observability nodig. U wilt elke LLM-aanroep, tool-aanroep, latentie, aantal tokens en kosten zien. Pydantic AI integreert ingebouwd met Logfire, het observabiliteitsplatform van het Pydantic-team (gebouwd op OpenTelemetry).

import logfire
from pydantic_ai import Agent

logfire.configure()  # Gebruikt LOGFIRE_TOKEN-omgevingsvariabele
logfire.instrument_pydantic_ai()

agent = Agent("openai:gpt-4o", result_type=MovieReview)
# Elke run wordt nu automatisch getraceerd
result = agent.run_sync("Review Inception")

Drie regels. U krijgt volledige traces met: verzonden prompt, modelantwoord, tool-aanroepen (indien aanwezig), validatiepassen/-fouten, herhaalpogingen, latentie en geschatte kosten. Als Logfire niet uw ding is, is Langfuse een solide open-source alternatief met context engineering ondersteuning voor het traceren van de ontwikkeling van uw prompts.

FAQ

Wat is Pydantic AI en hoe verschilt het van LangChain?

Pydantic AI is een type-veilig agentframework waarbij Python type-hints validatie, toolschema's en dependency injection aansturen. LangChain is een groter framework gericht op het koppelen van LLM-aanroepen. Het belangrijkste verschil: Pydantic AI valideert outputs op frameworkniveau en biedt ingebouwde dependency injection voor testbaarheid -- LangChain doet dit geen van beide standaard.

Hoe bouw ik een type-veilige AI-agent met Pydantic AI?

Definieer een Pydantic BaseModel voor uw output, geef het door als result_type aan Agent en roep run_sync() of run() aan. De agent geeft een gevalideerde instantie van uw model terug, niet een ruwe string. Zie de sectie Gestructureerde Outputs voor volledige voorbeelden.

Moet ik Pydantic AI of LangGraph gebruiken voor productieagenten?

Gebruik Pydantic AI voor individuele agenten waar type-veiligheid, testbaarheid en schone code belangrijk zijn. Gebruik LangGraph voor het orkestreren van complexe meerstaps-workflows met voorwaardelijke routing. Veel teams gebruiken beide -- Pydantic AI-agenten binnen een LangGraph-orchestratielaag.

Hoe behandelt Pydantic AI tool-aanroepen en dependency injection?

Versier een functie met @agent.tool en Pydantic AI leest de type-hints om het toolschema te genereren. Voor DI, stel deps_type in op de Agent en accepteer RunContext[UwDeps] in tools. Runtime-afhankelijkheden (DB-verbindingen, API-clients) stromen door zonder globale state.

Hoe voeg ik streaming toe aan een Pydantic AI-agent?

Gebruik agent.run_stream() in plaats van agent.run(). Het geeft een asynce contextbeheerder terug die gedeeltelijke resultaten levert via stream_structured() of stream_text(). Het eindresultaat is nog steeds volledig gevalideerd tegen uw result_type.

Is Pydantic AI productieklaar in 2026?

Ja. Versie 1.0 werd uitgebracht in september 2025 met een API-stabiliteitstoezegging. Het wordt ondersteund door het Pydantic-team (de meestgedownloade Python-bibliotheek voor datavalidatie) en is momenteel op v1.74.0 met regelmatige updates.

Kan ik Pydantic AI gebruiken met Ollama en lokale modellen?

Ja. Gebruik Agent("ollama:llama3.1") en zorg ervoor dat Ollama lokaal draait. Installeer de ollama provider-extra: pip install "pydantic-ai[ollama]". Gestructureerde outputs en tools werken hetzelfde als bij cloudproviders.

Hoe test ik Pydantic AI-agenten?

Gebruik TestModel -- een nepmodel dat geldige gestructureerde data genereert die overeenkomt met uw result_type zonder API-aanroepen. Omhul uw test met agent.override(model=TestModel()) en voer assertions uit op de output. Zie de sectie Testen voor volledige pytest-voorbeelden.

Werkt Pydantic AI met FastAPI?

Uitstekend. Ze delen dezelfde dependency injection-filosofie en zijn gebouwd door hetzelfde team. U kunt Pydantic AI-agenten gebruiken in FastAPI-endpoints, afhankelijkheidstypen tussen hen delen en agentantwoorden streamen via StreamingResponse.

Wat is het verschil tussen Pydantic AI en de OpenAI Agents SDK?

Pydantic AI is model-agnostisch (werkt met OpenAI, Anthropic, Gemini, Ollama, enz.), heeft dependency injection, TestModel voor testen en Pydantic-validatie. De OpenAI Agents SDK is eenvoudiger maar beperkt tot OpenAI-modellen en mist DI en ingebouwd testen. Kies Pydantic AI voor flexibiliteit; kies OpenAI Agents SDK voor de eenvoudigst mogelijke alleen-OpenAI-opstelling.

Belangrijkste Inzichten en Volgende Stappen

Begin met een kleine agent met gestructureerde outputs. Voeg een tool toe. Voeg afhankelijkheden toe. Schrijf een test met TestModel. Dat is het productiepad -- en u heeft nu alles wat u nodig heeft om het te bewandelen.

De officiële Pydantic AI-documentatie en het GitHub-repository zijn uitstekend voor dieper inzicht. Het framework beweegt snel, dus zet het changelog als bladwijzer.

Bronnen

• Pydantic AI -- Officiële documentatie
• Pydantic AI Dependencies-documentatie
• Pydantic AI Testing-documentatie
• Pydantic AI v1 Release-aankondiging
• Logfire AI Observability
• pydantic/pydantic-ai -- GitHub-repository