PydanticAI

1. Überblick über das Konzept und das systemische Problem

Die erste Welle von Bibliotheken für die Arbeit mit Sprachmodellen entstand in einer Ära des schnellen Prototypings: Sie verließen sich auf verschachtelte dynamische Klassen, untypisierte Dictionaries, unsichtbare Prompts und komplexe Vererbungshierarchien. In der Produktions-Backend-Entwicklung führte dies zu katastrophalen Schwierigkeiten:

1. Fehlende Autovervollständigung und Refactoring-Fähigkeit: Die IDE versteht nicht, welche Felder ein Agent zurückgibt, und die Umbenennung einer einzigen Eigenschaft bricht den Code zur Laufzeit ohne Vorwarnung.
2. Schwierigkeiten bei der Testbarkeit: Es ist unmöglich, die Agentenlogik von externen Diensten zu isolieren oder die Datenbank durch einen Test-Mock zu ersetzen, da eine ordentliche Dependency Injection fehlt.
3. Unzuverlässige Fehlerbehandlung bei der Strukturvalidierung: Modelle überspringen häufig Pflichtfelder oder verwechseln Typen (z. B. String statt Number), was zum Absturz der API führt.

PydanticAI von Samuel Colvin (dem Autor von Pydantic) bringt die Entwicklung von Agenten wieder in den Bereich der klassischen, sauberen Software-Ingenieurskunst: Es handelt sich um ein typsicheres, minimalistisches und schnelles Framework, das auf dem Standard Pydantic v2 basiert.

2. Architektonische Taxonomie und mentales Modell

Die Architektur von PydanticAI stützt sich auf vier konzeptionelle Säulen:

• 1. Parametrisierter Agent (Agent[Deps, ResultType]): Der Agent wird explizit mit zwei Parametern typisiert: dem Typ der kontextuellen Abhängigkeiten (Deps), die er für seine Arbeit benötigt, und dem Typ des Endergebnisses (ResultType). Wenn das Ergebnis ein Pydantic-Modell ist, garantiert der Agent, dass er eine validierte Instanz der Klasse zurückgibt.
• 2. Ausführungs-Kontext und DI (RunContext[Deps]): Der Mechanismus der Dependency Injection. Jedes Tool und jeder dynamische Prompt erhält Zugriff auf ctx.deps, wo aktive Datenbankverbindungen, Konfigurationen oder Benutzerberechtigungsdaten gespeichert sind.
• 3. Typisierte Tools (@agent.tool): Python-Funktionen, deren Argumente automatisch in JSON Schema für die LLM übersetzt werden. Beschreibungen der Argumente werden aus Type Hints und Docstrings extrahiert.
• 4. Dynamische System-Prompts (@agent.system_prompt): Asynchrone Funktionen, die die Systemanweisung „on the fly“ basierend auf den übergebenen Abhängigkeiten generieren (z. B. durch Einsetzen des aktuellen Kontostands des Benutzers oder der Zeitzone).

3. Technischer Pipeline und interne Mechanik

Der Lebenszyklus der Anfrageausführung in PydanticAI:

1. Instantiation & Context Binding (Kontextaufbau): Bei Aufruf von agent.run(prompt, deps=my_deps) initialisiert das Framework den RunContext und löst alle Funktionen auf, die mit dem Decorator @agent.system_prompt markiert sind.
2. Schema Generation & Model Inference (Modellaufruf): Die Typen der Tool-Argumente und der finale ResultType werden über die Pydantic Core Engine (geschrieben in Rust, was Mikrosekunden-Geschwindigkeit gewährleistet) in strenge JSON-Schemas konvertiert.
3. Tool Invocation with Self-Correction (Validierung und Korrektur): Wenn das Modell einen Tool-Aufruf zurückgibt, werden die Eingabeargumente durch den Pydantic-Validator geleitet. Schlägt die Validierung fehl (z. B. wurde eine negative Zahl übergeben, wo PositiveInt erwartet wird), wirft PydanticAI keine Exception, sondern sendet dem Modell automatisch eine Nachricht: „Validierungsfehler im Feld X: Erwartet wurde ein Wert > 0. Bitte versuchen Sie es erneut.“
4. Structured Output Serialization & Streaming (Ergebnisrückgabe): Die finale Antwort wird in ein Ziel-Python-Objekt deserialisiert. Die Methode run_stream() wird unterstützt, um teilweise geformte Objektfelder in Echtzeit an den Client zu streamen.

4. Praktische Engineering-Szenarien in der Produktion

01. Native Agenten innerhalb von FastAPI

Gemeinsame Nutzung von Modellen: Dieselbe InvoiceExtractionResponse-Schema wird als Ausgabeschema von PydanticAI, als response_model im FastAPI-Endpoint und zur automatischen Generierung des clientseitigen TypeScript-Typs über OpenAPI verwendet.

02. Sichere Arbeit mit Datenbanktransaktionen

Über den RunContext wird die transaktionale Sitzung AsyncSession von SQLAlchemy in die Tools injiziert. Der Agent kann Prüfungen durchführen und Daten schreiben. Tritt im finalen Schritt ein Fehler auf, rollt der externe Context Manager die Transaktion zurück und verhindert so das Speichern halbgarer Daten.

03. Streaming strukturierter Interfaces (Generative UI)

Der Agent generiert ein dynamisches Dashboard. Dank der Unterstützung der Stream-Validierung in PydanticAI kann das Frontend Diagramme und Karten renderen, noch bevor das Modell die vollständige JSON-Dokumentation abgeschlossen hat.

5. Fallstricke, typische Fehler und Sicherheit

• Fehlende Feldbeschreibungen (Field(description=...)): Das Modell bildet den Aufruf ausschließlich basierend auf Namen und Beschreibungen der Felder. Wenn ein Feld mehrdeutig benannt ist (z. B. status: int) und keine Beschreibung vorhanden ist, halluziniert das Modell regelmäßig falsche Werte.
• Erschöpfung der Korrekturversuche (Max Retries Exceeded): Wenn das Schema zu komplex ist, kann das Modell das Limit retries=3 ausschöpfen, während es versucht, die Antwort an den Validator anzupassen, was zum Scheitern der Anfrage führt. Vereinfachen Sie Schemata oder zerlegen Sie sie in Teilaufgaben.
• Leckage des Ressourcenlebenszyklus in Deps: Stellen Sie sicher, dass Objekte, die Sie in deps übergeben (Verbindungspools, HTTP-Clients), nach Abschluss der Agentenarbeit korrekt geschlossen werden (über async with).