Pydantic AI: Der Produktionsleitfaden (Über Hello World hinaus)

Pydantic AI: Der Produktionsleitfaden (Über Hello World hinaus)

Rohe LLM-Ausgaben brechen Apps. Sie bitten um JSON und bekommen Markdown. Sie bitten um eine Zahl zwischen 1 und 10 und bekommen "Sicher! Hier ist eine Zahl: sieben." Wenn Sie etwas Echtes mit LLM-APIs gebaut haben, haben Sie defensiven Parsing-Code geschrieben, der Sie an Ihrer Berufswahl zweifeln lässt. Pydantic AI löst das -- es ist das typsichere Agent-Framework, gebaut vom selben Team hinter Pydantic und FastAPI. Stellen Sie es sich als "FastAPI für KI-Agenten" vor: Sie definieren, was Sie wollen, mit Python-Typ-Hinweisen, und das Framework übernimmt Validierung, Wiederholungsversuche und Tool-Aufrufe.

Dieser Pydantic AI Leitfaden richtet sich an Entwickler, die bereits ihren ersten LLM-Aufruf gemacht haben und Produktionsmuster suchen: strukturierte Ausgaben, die nicht brechen, Dependency Injection für testbare Agenten und reale Tools jenseits von Wetter-APIs. Am Ende haben Sie funktionierende Agenten mit Tools, DI, Streaming und Tests.

Pydantic AI auf einen Blick

Die herausragenden Features sind strukturierte Ausgaben (mit Pydantic-Modellen validiert), Dependency Injection (wie FastAPIs Depends) und TestModel (Mock-LLM für Tests ohne API-Aufrufe). Wenn Sie von LangChain kommen und fragen "gibt es etwas Saubereres?", ist dies wahrscheinlich die Antwort.

Installation und Erster Agent

# Mit OpenAI-Unterstützung installieren (openai durch anthropic, google usw. ersetzen)
pip install "pydantic-ai[openai]"

# API-Schlüssel setzen
export OPENAI_API_KEY="sk-..."

Ihr erster Agent in 5 Zeilen:

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"

Das war's. Agent umhüllt das Modell, run_sync sendet einen Prompt und gibt ein Ergebnis zurück. Das result.output ist hier ein einfacher String, aber das ändert sich gleich.

Strukturierte Ausgaben -- Warum Pydantic AI existiert

Das ist das Kernfeature. Anstatt einen String vom LLM zurückzubekommen und zu hoffen, dass er gültiges JSON ist, definieren Sie ein Pydantic-Modell und der Agent gibt ein validiertes Python-Objekt zurück.

Vorher: Rohe LLM-Ausgabe

# Der alte Weg -- auf das Beste hoffen
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 ist ein String
# Vielleicht ist es JSON. Vielleicht hat es Markdown-Code-Fences. Vielleicht ist rating "eight".
# Sie sind auf sich allein gestellt.

Nachher: Strukturiert mit Pydantic AI

from pydantic import BaseModel
from pydantic_ai import Agent

class MovieReview(BaseModel):
    title: str
    rating: int  # Garantiert ein int, nicht "eight"
    summary: str
    recommended: bool

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

result = agent.run_sync("Review the movie Inception")
review = result.output  # Dies ist eine MovieReview-Instanz, kein String

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

Der Unterschied ist wie Tag und Nacht. result.output ist ein echtes MovieReview-Objekt. Wenn das LLM rating: "eight" statt rating: 8 zurückgibt, fängt Pydantics Validierung das ab. Für einen tieferen Einblick in die Funktionsweise über verschiedene Anbieter hinweg, lesen Sie unseren Leitfaden zu strukturierten Ausgaben über LLM-Anbieter hinweg.

Was passiert, wenn die Validierung fehlschlägt

Hier ist der Teil, den kein anderes Tutorial zeigt: Was passiert, wenn das LLM einen Fehler macht?

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class StrictReview(BaseModel):
    title: str
    rating: int = Field(ge=1, le=10)  # Muss 1-10 sein
    pros: list[str] = Field(min_length=2)  # Mindestens 2 Vorteile

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

# Wenn das LLM rating=15 zurückgibt oder nur 1 Vorteil:
# 1. Pydantic-Validierung schlägt fehl
# 2. Die Fehlermeldung wird ZURÜCK an das LLM gesendet
# 3. Das LLM versucht es erneut mit der korrigierten Ausgabe
# 4. Dies wiederholt sich bis zum Wiederholungslimit
result = agent.run_sync("Review the movie Inception")

Diese Wiederholung-mit-Feedback-Schleife ist Pydantic AIs Killer-Feature. Das LLM lernt aus seinen eigenen Validierungsfehlern. Sie schreiben keine Wiederholungslogik -- das Framework übernimmt das.

Fazit: Strukturierte Ausgaben sind der einzig beste Grund, Pydantic AI statt roher API-Aufrufe zu verwenden. Wenn Sie LLM-JSON manuell parsen, hören Sie auf.

Tools und Funktionsaufrufe

Tools lassen Ihren Agenten Python-Funktionen aufrufen, um echte Daten zu bekommen. Anstatt dass das LLM Fakten halluziniert, kann es Ihre Datenbank abfragen, Ihre Dokumente durchsuchen oder eine API aufrufen.

Ein Tool registrieren

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."""
    # Ihre eigentliche Suchlogik hier
    results = await doc_search_engine.search(query, limit=5)
    return "\n".join(r.title + ": " + r.snippet for r in results)

Der @agent.tool-Dekorator registriert die Funktion. Pydantic AI liest die Typ-Hinweise und den Docstring der Funktion, um dem LLM zu sagen, was das Tool tut, welche Argumente es nimmt und was es zurückgibt. Kein manuelles Schema-Schreiben -- Ihre Typ-Hinweise SIND das Schema. Für Hintergrundinformationen zu wie LLM-Funktionsaufrufe unter der Haube funktionieren haben wir einen eigenen Leitfaden.

RunContext: Daten an Tools übergeben

Hier weicht Pydantic AI von anderen Frameworks ab. RunContext lässt Sie Laufzeitdaten (Datenbankverbindungen, Benutzerinformationen, API-Clients) an Ihre Tools weitergeben, ohne globalen 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)

ctx.deps gibt dem Tool Zugang zu dem, was Sie zur Laufzeit übergeben haben. Das Tool importiert keine globale Datenbankverbindung -- es empfängt eine. Das ist Dependency Injection, und das macht Ihre Agenten testbar.

Ein praxisnahes Tool-Beispiel

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

Fazit: Tool-Aufrufe in Pydantic AI sind sauberer als in jedem anderen Framework dank Typ-Hinweisen, die die Hauptarbeit erledigen. Sie schreiben normale Python-Funktionen mit Typ-Annotationen. Das Framework erledigt den Rest.

Dependency Injection -- Das Feature, das LangChain gerne hätte

Wenn Sie FastAPIs Depends verwendet haben, verstehen Sie Pydantic AIs DI-System bereits. Falls nicht, hier ist die Kurzversion: Anstatt dass Ihr Agent das greift, was er braucht (globale Datenbankverbindungen, API-Clients, Konfiguration), geben Sie ihm alles zur Laufzeit.

Abhängigkeiten definieren

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

Abhängigkeiten in Tools verwenden

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

# Mit echten Abhängigkeiten ausführen
result = await agent.run(
    "What's my account status?",
    deps=AppDeps(db=real_db, search_client=real_search, current_user=user)
)

Warum DI Ihre Agenten testbar macht

Das ist die eigentliche Belohnung. In LangChain würden Sie Kontext durch Chain-Kwargs oder Closures übergeben -- es gibt kein Standardmuster. In Pydantic AI ist das Austauschen echter Abhängigkeiten durch Test-Doubles trivial:

# In Ihrer Testdatei
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

Kein Monkey-Patching. Kein Mocking globaler Imports. Sie übergeben einfach andere Deps.

Fazit: Dependency Injection ist der Grund, warum erfahrene Python-Entwickler Pydantic AI bevorzugen. Es ist der FastAPI-Einfluss, der sich zeigt.

Modell-Anbieter -- OpenAI, Anthropic, Gemini, Ollama

Pydantic AI ist modell-agnostisch. Anbieter wechseln ist eine einzeilige Änderung:

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

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

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

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

Alles andere -- Tools, strukturierte Ausgaben, DI -- bleibt identisch. Ihre Geschäftslogik ändert sich nicht, wenn Sie Modelle wechseln.

Fazit: Modell-agnostisches Design bedeutet, dass Sie nie bei einem Anbieter gefangen sind. Beginnen Sie mit OpenAI für Komfort, benchmarken Sie mit Anthropic und verwenden Sie Ollama für lokale Entwicklung.

Streaming-Antworten

Für Chat-UIs und Echtzeit-Anwendungen ist Streaming unerlässlich. Pydantic AI unterstützt es bei gleichzeitiger Aufrechterhaltung der Typsicherheit:

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 ist ein teilweise validiertes AnalysisResult
            print(f"Streaming: {partial}")

        # Das Endergebnis ist vollständig validiert
        result = await stream.get_output()
        print(f"Final: {result.summary} ({result.confidence:.0%} confident)")

Dies funktioniert hervorragend mit FastAPIs StreamingResponse -- gleiches Ökosystem, gleiche Muster. Die Pydantic AI Agenten-Dokumentation behandelt erweiterte Streaming-Optionen einschließlich Text-only-Streaming mit stream_text().

Pydantic AI vs. LangGraph vs. OpenAI Agents SDK

Sie sind hier, also fragen Sie wahrscheinlich: "Soll ich Pydantic AI oder LangGraph verwenden?" Ehrliche Antwort: Sie lösen verschiedene Probleme, und Sie könnten beide verwenden.

Feature-Vergleichstabelle

Wann welches verwenden

Wählen Sie Pydantic AI, wenn Sie sauberen, typsicheren Agenten-Code möchten. Es ist ideal für Single-Agent-Aufgaben mit Tools (Kundensupport-Bots, Datenextraktion, Code-Review-Agenten) und Situationen, in denen Testbarkeit wichtig ist. Wenn Ihr Team bereits FastAPI und Pydantic verwendet, ist die Lernkurve fast flach.

Wählen Sie LangGraph, wenn Sie komplexe mehrstufige Workflows mit bedingtem Verzweigen, menschlicher Genehmigung und anspruchsvollem State-Management benötigen. LangGraph zeichnet sich bei der Orchestrierung mehrerer Schritte aus, nicht bei der Qualität einzelner Agenten. Für einen tiefen Einblick siehe unseren vollständigen LangGraph vs. CrewAI vs. OpenAI Agents SDK Vergleich.

Wählen Sie OpenAI Agents SDK, wenn Sie zu 100% bei OpenAI sind, das einfachstmögliche Setup möchten und keine Multi-Anbieter-Unterstützung oder DI benötigen.

Das Kombinationsmuster

Was erfahrene Teams tatsächlich tun: Pydantic AI für einzelne Agenten verwenden (sauberer Code, testbar, typisierte Ausgaben) und LangGraph für die Orchestrierung zwischen Agenten (Routing, Zustandsmaschinen, bedingte Logik). Sie konkurrieren nicht -- sie sind komplementäre Schichten.

# Pydantic AI Agent -- sauber, testbar, typsicher
support_agent = Agent("openai:gpt-4o", result_type=SupportResponse, deps_type=SupportDeps)

# LangGraph Graph -- orchestriert, wann welcher Agent aufgerufen wird
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)

Fazit: Wählen Sie Pydantic AI für sauberen, testbaren Agenten-Code. Wählen Sie LangGraph für komplexe mehrstufige Workflows. Sie schließen sich nicht gegenseitig aus.

Agenten mit TestModel testen

Das ist der Abschnitt, der einen Einsteiger-Leitfaden von einem Produktionsleitfaden unterscheidet. Jede echte Codebasis braucht Tests, und das Testen von Agenten ist notorisch schwierig -- LLM-Aufrufe sind langsam, teuer und nicht-deterministisch. Pydantic AI liefert eine Lösung: 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: das echte Modell durch TestModel ersetzen
def test_support_agent():
    with agent.override(model=TestModel()):
        result = agent.run_sync("I need help with billing")
        # TestModel gibt gültige strukturierte Daten zurück, die Ihrem result_type entsprechen
        assert isinstance(result.output, SupportResponse)
        assert isinstance(result.output.confidence, float)
        assert isinstance(result.output.escalate, bool)

TestModel generiert gültige Daten, die Ihrem result_type entsprechen, ohne API-Aufrufe zu machen. Null Kosten, deterministisch, schnell. Die Pydantic AI Testing-Dokumentation behandelt erweiterte Muster wie FunctionModel für benutzerdefinierte Antworten und capture_run_messages zur Inspektion von Tool-Aufrufen.

Tools und DI zusammen testen

def test_order_lookup_tool():
    # Mock-Abhängigkeiten
    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)

Keine API-Aufrufe. Keine flakigen Tests. Keine Kosten. Führen Sie das in CI/CD neben dem Rest Ihrer Testsuite aus.

Das ist die #1-Inhaltslücke auf dem gesamten SERP. Kein anderer Pydantic AI-Leitfaden behandelt das Testen. Wenn Sie Agenten für die Produktion bauen, ist das das, was Sie brauchen.

Observability -- Logfire-Integration in 5 Minuten

Produktions-Agenten brauchen KI-Observability. Sie wollen jeden LLM-Aufruf, jede Tool-Invokation, Latenz, Token-Anzahl und Kosten sehen. Pydantic AI integriert nativ mit Logfire, der Observability-Plattform des Pydantic-Teams (basiert auf OpenTelemetry).

import logfire
from pydantic_ai import Agent

logfire.configure()  # Verwendet LOGFIRE_TOKEN-Umgebungsvariable
logfire.instrument_pydantic_ai()

agent = Agent("openai:gpt-4o", result_type=MovieReview)
# Jeder Lauf wird jetzt automatisch traced
result = agent.run_sync("Review Inception")

Drei Zeilen. Sie erhalten vollständige Traces mit: gesendeter Prompt, Modellantwort, Tool-Aufrufe (falls vorhanden), Validierungserfolge/-fehler, Wiederholungsversuche, Latenz und geschätzte Kosten. Wenn Logfire nicht Ihr Ding ist, ist Langfuse eine solide Open-Source-Alternative mit Unterstützung für Context Engineering zur Verfolgung der Entwicklung Ihrer Prompts.

FAQ

Was ist Pydantic AI und wie unterscheidet es sich von LangChain?

Pydantic AI ist ein typsicheres Agent-Framework, bei dem Python-Typ-Hinweise Validierung, Tool-Schemas und Dependency Injection antreiben. LangChain ist ein größeres Framework, das sich auf das Verketten von LLM-Aufrufen konzentriert. Der wesentliche Unterschied: Pydantic AI validiert Ausgaben auf Framework-Ebene und bietet eingebaute Dependency Injection für Testbarkeit -- LangChain tut beides standardmäßig nicht.

Wie baue ich einen typsicheren KI-Agenten mit Pydantic AI?

Definieren Sie ein Pydantic-BaseModel für Ihre Ausgabe, übergeben Sie es als result_type an Agent und rufen Sie run_sync() oder run() auf. Der Agent gibt eine validierte Instanz Ihres Modells zurück, keinen rohen String. Schauen Sie sich den Abschnitt "Strukturierte Ausgaben" für vollständige Beispiele an.

Soll ich Pydantic AI oder LangGraph für Produktions-Agenten verwenden?

Verwenden Sie Pydantic AI für einzelne Agenten, bei denen Typsicherheit, Testbarkeit und sauberer Code wichtig sind. Verwenden Sie LangGraph für die Orchestrierung komplexer mehrstufiger Workflows mit bedingtem Routing. Viele Teams verwenden beides -- Pydantic AI-Agenten innerhalb einer LangGraph-Orchestrierungsschicht.

Wie handhabt Pydantic AI Tool-Aufrufe und Dependency Injection?

Dekorieren Sie eine Funktion mit @agent.tool und Pydantic AI liest ihre Typ-Hinweise, um das Tool-Schema zu generieren. Für DI setzen Sie deps_type auf dem Agent und akzeptieren RunContext[IhreAbhängigkeiten] in Tools. Laufzeit-Abhängigkeiten (DB-Verbindungen, API-Clients) fließen ohne globalen State durch.

Wie füge ich Streaming zu einem Pydantic AI-Agenten hinzu?

Verwenden Sie agent.run_stream() statt agent.run(). Es gibt einen asynchronen Kontextmanager zurück, der partielle Ergebnisse über stream_structured() oder stream_text() liefert. Das Endergebnis ist immer noch vollständig gegen Ihren result_type validiert.

Ist Pydantic AI 2026 produktionsbereit?

Ja. Version 1.0 wurde im September 2025 veröffentlicht mit einer API-Stabilitätszusage. Es wird vom Pydantic-Team (die meistgeladene Python-Bibliothek für Datenvalidierung) unterstützt und ist derzeit bei v1.74.0 mit regelmäßigen Updates.

Kann ich Pydantic AI mit Ollama und lokalen Modellen verwenden?

Ja. Verwenden Sie Agent("ollama:llama3.1") und stellen Sie sicher, dass Ollama lokal läuft. Installieren Sie das Ollama-Provider-Extra: pip install "pydantic-ai[ollama]". Strukturierte Ausgaben und Tools funktionieren genauso wie mit Cloud-Anbietern.

Wie teste ich Pydantic AI-Agenten?

Verwenden Sie TestModel -- ein Mock-Modell, das gültige strukturierte Daten generiert, die Ihrem result_type entsprechen, ohne API-Aufrufe. Umhüllen Sie Ihren Test mit agent.override(model=TestModel()) und führen Sie Assertions auf der Ausgabe durch. Schauen Sie sich den Testing-Abschnitt für vollständige pytest-Beispiele an.

Funktioniert Pydantic AI mit FastAPI?

Perfekt. Sie teilen dieselbe Dependency-Injection-Philosophie und werden vom selben Team gebaut. Sie können Pydantic AI-Agenten in FastAPI-Endpunkten verwenden, Abhängigkeitstypen zwischen ihnen teilen und Agenten-Antworten durch StreamingResponse streamen.

Was ist der Unterschied zwischen Pydantic AI und dem OpenAI Agents SDK?

Pydantic AI ist modell-agnostisch (funktioniert mit OpenAI, Anthropic, Gemini, Ollama usw.), hat Dependency Injection, TestModel für Tests und Pydantic-Validierung. Das OpenAI Agents SDK ist einfacher, aber auf OpenAI-Modelle beschränkt und hat weder DI noch eingebautes Testing. Wählen Sie Pydantic AI für Flexibilität; wählen Sie OpenAI Agents SDK für das einfachstmögliche Nur-OpenAI-Setup.

Wichtigste Erkenntnisse und Nächste Schritte

Beginnen Sie mit einem kleinen Agenten mit strukturierten Ausgaben. Fügen Sie ein Tool hinzu. Fügen Sie Abhängigkeiten hinzu. Schreiben Sie einen Test mit TestModel. Das ist der Produktionspfad -- und Sie haben jetzt alles, was Sie brauchen, um ihn zu gehen.

Die offiziellen Pydantic AI-Dokumentation und das GitHub-Repository sind hervorragend für tiefere Einblicke. Das Framework entwickelt sich schnell, also setzen Sie ein Lesezeichen auf das Changelog.

Quellen

• Pydantic AI -- Offizielle Dokumentation
• Pydantic AI Abhängigkeiten-Dokumentation
• Pydantic AI Testing-Dokumentation
• Pydantic AI v1 Versionsankündigung
• Logfire KI-Observability
• pydantic/pydantic-ai -- GitHub-Repository