Was ist PydanticAI? Ein Leitfaden zum typensicheren Python Agenten-Framework

Wenn Sie schon einmal eine LLM-Funktion bereitgestellt haben und in Produktion plötzlich fehlerhaftes JSON zurückkam, ist PydanticAI genau für diesen Anwendungsfall gebaut. Es ist das Python-Agenten-Framework des Teams hinter Pydantic und stellt typsichere, validierte Ausgaben in den Mittelpunkt. Dieser Leitfaden zeigt, wie Sie PydanticAI einsetzen, welche Konzepte Sie wirklich brauchen und wie es sich gegenüber Frameworks wie LangGraph einordnet.

Teste Apidog noch heute

Was PydanticAI ist

PydanticAI ist ein quelloffenes, anbieterunabhängiges Agenten-Framework für Python. Es wird vom selben Team gepflegt, das auch Pydantic Validation und Pydantic Logfire entwickelt. Das Ziel: Agenten so entwickeln, wie viele Python-Entwickler heute APIs mit FastAPI bauen — mit klaren Typen, Validierung und guter Tooling-Unterstützung.

Praktisch bedeutet das:

1. Sie definieren, was Ihr Agent tun soll.
2. Sie deklarieren, welche Tools er aufrufen darf.
3. Sie beschreiben die erwartete Ausgabe als Pydantic-Modell.
4. PydanticAI ruft das Modell auf, validiert die Antwort und versucht es erneut, wenn die Ausgabe nicht passt.

Installieren können Sie es mit:

pip install pydantic-ai

oder:

uv add pydantic-ai

Das Projekt erreichte am 23. Juni 2026 nach mehreren Beta-Versionen eine stabile v2.0.0-Veröffentlichung. V2 setzt auf ein „Harness-first“-Design, bei dem Tools, Hooks, Anweisungen und Modelleinstellungen als wiederverwendbare Einheiten kombiniert werden.

Warum Typsicherheit bei Agenten wichtig ist

LLMs sind nicht-deterministisch. Dieselbe Eingabe kann unterschiedliche Antwortformen erzeugen. Für ein Chat-Fenster ist das akzeptabel. Für produktiven Code ist es riskant, besonders wenn die Antwort direkt in eine Datenbanktransaktion, einen API-Aufruf oder eine Berechnung fließt.

Typische Fehler sehen so aus:

• Das Modell gibt fast gültiges JSON zurück, aber mit zusätzlichem Text.
• Ein Pflichtfeld fehlt.
• Ein Feld hat den falschen Typ.
• Eine verschachtelte Struktur ist anders als erwartet.
• Ein Tool wird mit ungültigen Argumenten aufgerufen.

Ohne Framework landen Sie schnell bei defensiven Parsern, Regex-Bereinigungen und manuellen Retry-Schleifen.

PydanticAI verschiebt diesen Vertrag ins Framework. Sie definieren ein Pydantic-Modell als Ausgabetyp. Wenn das LLM ungültige Daten zurückgibt, erhält es den Validierungsfehler und soll die Antwort korrigieren. Ihr Code arbeitet danach mit typisierten Objekten statt mit hoffnungsvollen Strings.

Dasselbe gilt für Tool-Argumente: PydanticAI nutzt die Type Hints Ihrer Tool-Funktionen, validiert die Eingaben und führt die Funktion nur aus, wenn die Argumente passen.

Kernkonzepte

PydanticAI hat eine kleine Oberfläche. Für die meisten Implementierungen reichen diese Konzepte.

Agenten

Die Klasse Agent ist der Haupteinstiegspunkt. Sie erstellen einen Agenten mit einem Modellstring und optionalen Anweisungen.

from pydantic_ai import Agent

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='Be concise, reply with one sentence.',
)

result = agent.run_sync('Where does "hello world" come from?')
print(result.output)

Der Modellstring bestimmt den Anbieter und das Modell. Wenn Sie später den Anbieter wechseln, ändern Sie in vielen Fällen nur diese Zeichenkette.

Beispiel:

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

oder:

agent = Agent('anthropic:claude-sonnet-4-6')

Typisierte Ausgaben

Für produktive Agenten sollten Sie selten rohe Textantworten weiterverarbeiten. Definieren Sie stattdessen ein Pydantic-Modell und übergeben Sie es als output_type.

from pydantic import BaseModel
from pydantic_ai import Agent

class SupportTicket(BaseModel):
    category: str
    priority: int
    summary: str

agent = Agent(
    'openai:gpt-4o',
    output_type=SupportTicket,
)

result = agent.run_sync('My payment failed three times today.')

ticket = result.output
print(ticket.category)
print(ticket.priority)
print(ticket.summary)

result.output ist hier kein unstrukturierter String, sondern ein validiertes SupportTicket.

Wenn das Modell zum Beispiel "high" statt einer Zahl für priority zurückgibt oder summary weglässt, schlägt die Validierung fehl und PydanticAI kann das Modell zur Korrektur auffordern.

Tools

Tools erlauben dem Agenten, externe Aktionen auszuführen: APIs aufrufen, Datenbanken abfragen oder Berechnungen durchführen.

Sie registrieren ein Tool mit @agent.tool. PydanticAI liest die Type Hints und den Docstring der Funktion und erzeugt daraus ein Schema für das Modell.

from pydantic_ai import Agent, RunContext

agent = Agent('openai:gpt-4o', deps_type=str)

@agent.tool
async def get_user_balance(ctx: RunContext[str], account_id: str) -> float:
    """Gibt den aktuellen Kontostand eines Kontos zurück."""
    return await lookup_balance(ctx.deps, account_id)

Wichtig für die Implementierung:

• Der Docstring beschreibt dem Modell, wofür das Tool da ist.
• Die Type Hints definieren die erlaubten Argumente.
• RunContext gibt Zugriff auf injizierte Abhängigkeiten.
• Die Funktion wird erst ausgeführt, wenn die Argumente validiert wurden.

Abhängigkeiten

In echten Anwendungen braucht ein Agent Kontext: Datenbankverbindungen, HTTP-Clients, API-Schlüssel oder den aktuellen Benutzer.

PydanticAI nutzt dafür Dependency Injection. Sie definieren einen deps_type und übergeben beim Lauf die konkrete Abhängigkeit.

Beispiel mit einem hypothetischen HTTP-Client:

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    api_base_url: str
    token: str

agent = Agent(
    'openai:gpt-4o',
    deps_type=Deps,
)

@agent.tool
async def get_order_status(ctx: RunContext[Deps], order_id: str) -> str:
    """Gibt den Status einer Bestellung zurück."""
    # Beispiel: hier würden Sie Ihren echten HTTP-Client verwenden
    return await fetch_order_status(
        base_url=ctx.deps.api_base_url,
        token=ctx.deps.token,
        order_id=order_id,
    )

Beim Testen können Sie die echten Abhängigkeiten durch Fakes ersetzen, ohne die Tool-Logik umzuschreiben.

Anbieterunabhängigkeit und Streaming

PydanticAI unterstützt verschiedene Anbieter, darunter OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral und Perplexity. Dazu kommen Cloud-Optionen wie Azure AI Foundry und Amazon Bedrock sowie selbst gehostete Modelle.

Der Wechsel erfolgt normalerweise über den Modellstring:

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

zu:

agent = Agent('anthropic:claude-sonnet-4-6')

PydanticAI unterstützt außerdem Streaming strukturierter Ausgaben. Dabei wird Validierung angewendet, sobald Daten eintreffen. Das ist nützlich, wenn Sie Teilergebnisse anzeigen möchten, ohne komplett auf Typgarantien zu verzichten.

Da das Team auch Pydantic Logfire entwickelt, ist Beobachtbarkeit ein wichtiger Teil des Ökosystems: Tracing, Debugging und Kostenverfolgung pro Lauf.

Vergleich mit anderen Python-Agenten-Frameworks

Es gibt kein universell bestes Framework. Die Wahl hängt davon ab, welchen Teil Ihrer Agentenarchitektur Sie optimieren möchten.

Framework	Kernstärke	Ideal, wenn Sie Folgendes wünschen
PydanticAI	Typsichere, validierte Ausgaben und Tool-Argumente	Produktionszuverlässigkeit und sauberer typisierter Datenfluss
LangGraph	Explizite zustandsbehaftete Graphen und Kontrollfluss	Langlebige, verzweigte, mehrstufige Workflows
Google ADK	Multi-Agenten-Orchestrierung in Googles Ökosystem	Tiefe Gemini- und Vertex AI-Integration
OpenAI Agents SDK	Enge OpenAI-Integration mit Übergaben	Ein OpenAI-zentrierter Stack und schnelle Einrichtung

PydanticAI ist besonders stark, wenn Ihr Agent strukturierte Daten an andere Systeme weitergibt. Die Garantie, dass die Ausgabe einem Pydantic-Modell entspricht, reduziert eine ganze Klasse typischer Laufzeitfehler.

LangGraph eignet sich besser, wenn Sie komplexe Zustandsmaschinen, explizite Knoten und verzweigte Abläufe brauchen. Das OpenAI Agents SDK passt gut, wenn Ihr Stack ohnehin stark auf OpenAI ausgerichtet ist und Sie Funktionen wie Agentenübergaben oder MCP-Server-Unterstützung nutzen möchten.

Sie können diese Ansätze auch kombinieren. PydanticAI kann zum Beispiel als typisierte Ausgabeschicht innerhalb einer größeren Orchestrierung eingesetzt werden.

Wann Sie PydanticAI verwenden sollten

Verwenden Sie PydanticAI, wenn:

• die Ausgabe Ihres Agenten in Code weiterverarbeitet wird,
• die Antwortstruktur zuverlässig sein muss,
• Sie Pydantic bereits in Ihrer Codebasis nutzen,
• Ihre IDE und Ihr Type Checker den Agenten verstehen sollen,
• Sie Anbieter wechseln möchten, ohne die gesamte Agentenlogik umzubauen,
• Observability über Logfire für Sie relevant ist.

Suchen Sie eher nach einem Graphen-Framework, wenn Sie eine komplexe, langlebige Orchestrierung mit vielen Zuständen, Knoten und Verzweigungen implementieren müssen.

APIs hinter dem Agenten testen und mocken

Ein PydanticAI-Agent ist nur so zuverlässig wie die APIs, von denen er abhängt. Neben dem LLM-Anbieter rufen viele Agenten eigene REST-Endpunkte oder Drittanbieter-Tools auf. Genau dort entstehen häufig Probleme: instabile Antworten, unerwartete Kosten, Ratenbegrenzungen oder veränderte Response-Strukturen.

PydanticAI validiert die Modellausgabe. Es kann aber nicht garantieren, dass die Upstream-API Ihres Tools tatsächlich die Daten zurückgibt, die Ihr Tool erwartet.

Hier hilft Apidog. Apidog ist keine Alternative zu PydanticAI und orchestriert keine Agenten. Es ist eine API-Plattform, mit der Sie die HTTP-Schnittstellen testen und mocken können, auf denen Ihr Agent aufsetzt.

Praktische Einsatzfälle:

• LLM- oder Tool-Endpunkte mocken: Zeigen Sie während der Entwicklung auf eine Mock-API, die deterministische Antworten liefert. So sparen Sie Tokens und vermeiden Ratenlimits während lokaler Tests.
• Response-Strukturen prüfen: Bevor Sie einen REST-Endpunkt in eine @agent.tool-Funktion einbauen, validieren Sie mit API-Assertions, ob die tatsächliche Antwort zur erwarteten Struktur passt.
• Umgebungen trennen: Verwalten Sie Basis-URLs, Tokens und Anbieter-Schlüssel getrennt für lokal, Staging und CI.
• LLM-Endpunkte direkt testen: Wenn Sie einen Anbieter per HTTP ansprechen, können Sie die ChatGPT-API mit Apidog testen, bevor Ihr Agent davon abhängt.

Ein sinnvoller Workflow sieht so aus:

1. Tool-API in Apidog dokumentieren.
2. Erwartete Antworten mit Assertions prüfen.
3. Mock-Endpunkt für lokale Agententests erstellen.
4. Tool-Funktion in PydanticAI implementieren.
5. Agentenlauf gegen Mock und danach gegen Staging testen.

Wenn Sie es ausprobieren möchten, laden Sie Apidog herunter und mocken Sie zuerst einen Ihrer Tool-Endpunkte.

Häufig gestellte Fragen

Ist PydanticAI kostenlos und quelloffen?

Ja. PydanticAI ist quelloffen und kann über PyPI installiert werden:

pip install pydantic-ai

oder:

uv add pydantic-ai

Sie zahlen weiterhin für die LLM-Anbieter, die Sie verwenden. Um Kosten während der Entwicklung zu reduzieren, können Sie API-Antworten mocken, statt bei jedem Testlauf das Live-Modell aufzurufen.

Mit welchen Modellen funktioniert PydanticAI?

PydanticAI ist anbieterunabhängig. Die Dokumentation nennt unter anderem OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral und Perplexity. Dazu kommen Azure AI Foundry, Amazon Bedrock und selbst gehostete Modelle.

Sie wählen das Modell über den String im Agent-Konstruktor:

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

oder:

agent = Agent('anthropic:claude-sonnet-4-6')

Worin unterscheidet sich PydanticAI von LangChain oder LangGraph?

PydanticAI fokussiert sich auf Typsicherheit: validierte strukturierte Ausgaben und validierte Tool-Argumente auf Basis von Pydantic-Modellen.

LangGraph fokussiert sich stärker auf explizite, zustandsbehaftete Graphen für mehrstufige und verzweigte Workflows.

Kurz gesagt:

• PydanticAI: Wenn korrekte Datenformen und typisierter Datenfluss Priorität haben.
• LangGraph: Wenn Sie eine komplexe Zustandsmaschine mit expliziter Kontrolle brauchen.

Muss ich Pydantic kennen, um PydanticAI zu verwenden?

Es hilft, ist aber keine harte Voraussetzung. Die Grundlagen sind einfach: Sie definieren Datenformen als Klassen, die von BaseModel erben. PydanticAI verwendet diese Modelle für Ausgaben und Tool-Schemas.

Wenn Sie schon Python für API-Tests genutzt oder mit FastAPI gearbeitet haben, wird sich das Modell vertraut anfühlen.

Fazit

PydanticAI macht Agentenentwicklung konkreter und robuster: Sie deklarieren Typen, validieren Ausgaben und schützen Ihre Tool-Funktionen vor ungültigen Argumenten. Das reduziert typische Produktionsfehler, die entstehen, wenn LLM-Antworten ungeprüft in Code weiterlaufen.

Wählen Sie PydanticAI, wenn Zuverlässigkeit, typisierte Ausgaben und saubere Validierung wichtiger sind als eine umfangreiche Graphen-Orchestrierung.

Unabhängig vom Framework sollten Sie die APIs unter Ihrem Agenten testen. Mocken Sie LLM- und Tool-Endpunkte, prüfen Sie Antwortformen und verwalten Sie Umgebungen sauber in Apidog, damit Ihr Agent auf einer verifizierten Grundlage läuft.