Wenn Sie jemals eine LLM-Funktion bereitgestellt und zugesehen haben, wie sie in der Produktion fehlerhaftes JSON zurückgibt, ist PydanticAI für Sie gemacht. Es ist das Python-Agenten-Framework des Teams hinter Pydantic, und es stellt typsichere, validierte Ausgaben in den Mittelpunkt der Agentenentwicklung. Dieser Leitfaden erklärt, was PydanticAI ist, warum Typsicherheit für Agenten wichtig ist, welche Kernkonzepte Sie tatsächlich verwenden werden und wie es sich im Vergleich zu anderen Python-Frameworks wie LangGraph schlägt.
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, wodurch es eine starke Validierungsgrundlage und ein klares Designziel erbt: das „FastAPI-Gefühl“ in die Agentenentwicklung zu bringen.
Einfach ausgedrückt: Sie beschreiben, was Ihr Agent tun soll, welche Tools er aufrufen kann und welche Form seine Ausgabe haben muss. PydanticAI übernimmt die Modellaufrufe, validiert alles anhand Ihrer Pydantic-Modelle und versucht es erneut, wenn das Modell etwas zurückgibt, das nicht passt.
Das Projekt erreichte am 23. Juni 2026 nach einer Reihe von Beta-Versionen eine stabile v2.0.0-Veröffentlichung. V2 setzt auf ein „Harness-first“-Design, bei dem die Tools, Hooks, Anweisungen und Modelleinstellungen eines Agenten als wiederverwendbare Einheiten zusammengesetzt werden. Sie können es mit pip install pydantic-ai oder uv add pydantic-ai installieren.
Warum Typsicherheit für Agenten wichtig ist
LLMs sind nicht-deterministisch. Stellen Sie dieselbe Frage zweimal, und Sie können zwei verschiedene Antwortformen erhalten. Das ist für ein Chat-Fenster in Ordnung, aber es bricht in dem Moment, in dem Sie die Modellausgabe in echten Code einbinden: eine Datenbanktransaktion, einen API-Aufruf, eine Rechnungsberechnung.
Die meisten Agentenfehler stammen aus dieser Lücke. Das Modell gibt „meistens“ gültiges JSON zurück, Ihr Parser funktioniert beim Testen, aber eine Produktionsantwort lässt ein Feld fallen oder verpackt die Antwort in Prosa, und Ihre Pipeline schlägt fehl. Sie enden damit, defensive Parser, Regex-Bereinigungen und Wiederholungsschleifen manuell zu schreiben.
PydanticAI schließt diese Lücke, indem es den Ausgabevertrag zu einem Teil des Frameworks macht. Sie definieren ein Pydantic-Modell, übergeben es als Ausgabetyp, und das Framework garantiert, dass der zurückgegebene Wert diesem Modell entspricht. Wenn das Modell etwas Ungültiges zurückgibt, sendet PydanticAI den Validierungsfehler an das LLM zurück und fordert es auf, es erneut zu versuchen. Ihr nachgeschalteter Code erhält typisierte Objekte, keine hoffnungsvollen Zeichenketten.
Dieselbe Idee gilt auch für Tool-Argumente. Wenn das Modell eines Ihrer Tools aufruft, validiert PydanticAI die Argumente anhand der Typ-Hints Ihrer Funktion, bevor die Funktion ausgeführt wird. Ungültige Argumente erreichen niemals Ihre Geschäftslogik.
Kernkonzepte
PydanticAI hält seine Oberfläche klein. Fünf Ideen decken das meiste ab, was Sie bauen werden.
Agenten
Die Agent-Klasse ist der Haupteinstiegspunkt. Sie erstellen einen Agenten mit einer Modellkennung und optionalen Anweisungen. Die Klasse ist generisch über zwei Typparameter: den Abhängigkeitstyp und den Ausgabetyp, was Ihrem Editor und Typprüfer echte Einblicke in Ihren Agenten gibt.
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)
Dieser Modellstring ist alles, was Sie ändern müssen, um Anbieter zu wechseln, was Ihren Code portabel hält.
Typisierte Ausgaben
Übergeben Sie ein Pydantic-Modell als output_type, und das Ergebnis des Agenten wird dagegen validiert. Sie erhalten ein typisiertes Objekt zurück, und Ihre IDE kennt jedes Feld. Hier ist eine Skizze für strukturierte Ausgaben:
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.')
print(result.output.priority) # ein int, validiert, keine Schätzung
Wenn das Modell eine Priorität als Text zurückgibt oder die Zusammenfassung weglässt, schlägt die Validierung fehl und das Framework fordert erneut eine Eingabe an. Sie müssen die Rohantwort niemals selbst parsen.
Tools
Tools ermöglichen es dem Modell, nach außen zu greifen: eine Datenbank abfragen, eine REST-API aufrufen, eine Berechnung durchführen. Sie registrieren ein Tool mit dem `@agent.tool`-Decorator. PydanticAI liest die Typ-Hints und den Docstring der Funktion, um das Schema zu erstellen, das das Modell sieht, und validiert dann jeden Aufruf dagegen.
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."""
# ctx.deps enthält Ihre injizierte Abhängigkeit
return await lookup_balance(ctx.deps, account_id)
Das Modell entscheidet, wann das Tool aufgerufen wird. Ihre Funktion wird nur mit Argumenten ausgeführt, die die Validierung bereits bestanden haben.
Abhängigkeiten
Echte Agenten benötigen Kontext: eine Datenbankverbindung, einen HTTP-Client, den aktuellen Benutzer, einen API-Schlüssel. PydanticAI handhabt dies mit Dependency Injection. Sie deklarieren einen `deps_type` für den Agenten und lesen ihn dann über `RunContext` innerhalb von Tools und dynamischen Anweisungen aus. Die gesamte Kette bleibt typsicher, und das Testen wird einfacher, da Sie echte Abhängigkeiten durch Fakes ersetzen können.
Modellunabhängige Anbieter und Streaming
PydanticAI unterstützt eine lange Liste von Anbietern: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, plus Cloud-Optionen wie Azure AI Foundry und Amazon Bedrock sowie selbst gehostete Modelle. Der Wechsel erfolgt in der Regel durch eine einzeilige Änderung des Modellstrings.
Es streamt auch strukturierte Ausgaben, wobei die Validierung angewendet wird, sobald Daten eintreffen, sodass Sie Teilergebnisse rendern können, ohne die Typgarantien aufzugeben. Und da das Team auch Pydantic Logfire entwickelt, ist die Beobachtbarkeit integriert: Tracing, Debugging und Kostenverfolgung für jeden Lauf.
Wie sich PydanticAI mit anderen Python-Agenten-Frameworks vergleicht
Es gibt kein einziges „bestes“ Framework. Sie sind für unterschiedliche Dinge optimiert. Hier ist eine ehrliche Einschätzung, wo PydanticAI passt.
| 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 |
Der Vorteil von PydanticAI ist die Validierungsschicht. Wenn Ihr Agent typisierte Daten in andere Systeme einspeist, beseitigt die Garantie, dass die Ausgabe einem Pydantic-Modell entspricht, eine ganze Klasse von Laufzeitfehlern. LangGraph bietet Ihnen eine feinere Kontrolle über Zustandsmaschinen und komplexe Abläufe. Das OpenAI Agents SDK ist eine natürliche Wahl, wenn Sie bereits OpenAI nutzen und Funktionen wie Agentenübergaben und MCP-Server-Unterstützung wünschen.
Sie können sie auch mischen. PydanticAI funktioniert gut als typisierte Ausgabeschicht innerhalb einer größeren Orchestrierung.
Wann PydanticAI verwendet werden sollte
Greifen Sie zu PydanticAI, wenn:
- Die Ausgabe Ihres Agenten in Code geht, nicht nur in ein Chat-Fenster, und die Form korrekt sein muss.
- Sie möchten, dass Ihr Typprüfer und Ihre IDE Ihren Agenten vollständig verstehen.
- Sie Pydantic bereits in Ihrer Codebasis verwenden, sodass sich die Modelldefinitionen nativ anfühlen.
- Sie Anbieterflexibilität benötigen und Ihren Agenten nicht umschreiben möchten, um Modelle zu wechseln.
- Beobachtbarkeit wichtig ist und Logfires integriertes Tracing ansprechend ist.
Suchen Sie woanders, wenn Sie eine umfangreiche graphenbasierte Orchestrierung mit komplexen Verzweigungen benötigen, bei der ein Zustandsmaschinen-Framework Ihnen mehr direkte Kontrolle bietet.
Testen und Mocken der APIs hinter Ihrem Agenten
Ein PydanticAI-Agent ist nur so zuverlässig wie die APIs, von denen er abhängt. Jeder Lauf ruft einen LLM-Anbieter auf, und die meisten nützlichen Agenten rufen auch Ihre eigenen REST-Endpunkte oder Drittanbieter-Tools auf. Dort schleichen sich unzuverlässiges Verhalten, unerwartete Kosten und Formunregelmäßigkeiten ein. PydanticAI validiert die Ausgabe des Modells, kann aber nicht validieren, ob die Upstream-Tool-API, die Sie aufrufen, das zurückgibt, was Sie erwarten.
Hier kommt Apidog ins Spiel, und das ist eine andere Aufgabe als die des Frameworks. Apidog ist eine API-Plattform, auf der Sie die zugrundeliegenden APIs, mit denen Ihr Agent kommuniziert, testen und mocken können.
Einige konkrete Anwendungsfälle:
- Mocken Sie den LLM oder einen Tool-Endpunkt. Zeigen Sie während der Entwicklung ein Tool auf eine Mock-API, die deterministische Antworten zurückgibt. So verbrennen Sie bei jedem Testlauf keine Tokens mehr und umgehen die Ratenbegrenzungen des Anbieters während der Iteration.
- Antwortformen überprüfen. Bevor Sie einen REST-Endpunkt in eine `@agent.tool`-Funktion einbinden, verwenden Sie API-Assertions, um zu bestätigen, dass die tatsächliche Antwort der Struktur entspricht, die Ihr Tool erwartet. Fangen Sie ein fehlendes Feld auf der API-Ebene ab, nicht tief innerhalb eines Agentenlaufs.
- Schlüssel pro Umgebung verwalten. Halten Sie Anbieter-Schlüssel und Basis-URLs in separaten Apidog-Umgebungen, damit lokale, Staging- und CI-Läufe die richtigen Ziele ohne Codeänderungen erreichen.
- Den LLM-Endpunkt direkt verifizieren. Wenn Sie einen Anbieter über HTTP aufrufen, können Sie die ChatGPT-API mit Apidog testen, um Authentifizierung, Streaming und Tool-Aufrufe zu bestätigen, bevor Ihr Agent davon abhängt.
Apidog erstellt oder orchestriert keine Agenten und ist keine Alternative zu PydanticAI. Es ist die Werkbank, auf der Sie die API-Oberfläche, auf der Ihr Agent läuft, testen und mocken. 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 Sie installieren es von PyPI mit pip install pydantic-ai oder uv add pydantic-ai. Sie zahlen weiterhin für jeden LLM-Anbieter, den Sie verwenden, da das Framework diese APIs in Ihrem Namen aufruft. Um die Anbieterkosten während der Entwicklung niedrig zu halten, können Sie die API-Antworten mocken während des Testens, anstatt bei jedem Lauf das Live-Modell zu kontaktieren.
Mit welchen Modellen funktioniert PydanticAI?
Es ist anbieterunabhängig. Die Dokumentation listet OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral und Perplexity auf, zusätzlich zu Cloud-Optionen wie Azure AI Foundry und Amazon Bedrock und selbst gehosteten Modellen. Sie wählen ein Modell aus, indem Sie einen String wie 'anthropic:claude-sonnet-4-6' oder 'openai:gpt-4o' an den Agent-Konstruktor übergeben, und der Wechsel ist normalerweise eine einzeilige Änderung.
Worin unterscheidet sich PydanticAI von LangChain oder LangGraph?
PydanticAI konzentriert sich auf Typsicherheit: validierte strukturierte Ausgaben und validierte Tool-Argumente, die durch Pydantic-Modelle unterstützt werden. LangGraph konzentriert sich auf explizite zustandsbehaftete Graphen für mehrstufige, verzweigte Workflows. Wenn Ihre Priorität garantierte Ausgabestrukturen und ein sauberer typisierter Datenfluss sind, passt PydanticAI gut. Wenn Sie eine feingranulare Kontrolle über eine komplexe Zustandsmaschine benötigen, bietet Ihnen ein Graphen-Framework direktere Hebel.
Muss ich Pydantic kennen, um es zu verwenden?
Es hilft, aber die Grundlagen sind schnell zu erlernen. Sie definieren Datenformen als Klassen, die von BaseModel erben, und PydanticAI verwendet diese für Ausgaben und Tool-Schemas. Wenn Sie Python für API-Tests verwendet oder mit FastAPI gearbeitet haben, wird sich das mentale Modell vertraut anfühlen.
Fazit
PydanticAI bringt etwas Praktisches in die Agentenentwicklung: eine Garantie, dass die Ausgabe und die Tool-Aufrufe Ihres Modells den von Ihnen deklarierten Typen entsprechen. Das beseitigt eine echte Fehlerquelle in der Produktion und hält Ihren Datenfluss sauber. Wählen Sie es, wenn Zuverlässigkeit und typisierte Ausgaben wichtiger sind als eine aufwändige Graphen-Orchestrierung.
Welches Framework Sie auch wählen, die APIs unter Ihrem Agenten müssen immer noch getestet werden. Mocken Sie Ihre LLM- und Tool-Endpunkte, überprüfen Sie deren Antwortformen und verwalten Sie Schlüssel pro Umgebung in Apidog, damit Ihr Agent auf einer von Ihnen tatsächlich verifizierten Grundlage läuft.