Pydantic AI: KI-Agenten in Python mit validierten Ergebnissen

Abgeglichen mit der Dokumentation des Anbieters und der Lizenz im Repository am 17. Oktober 2026. Für die folgende Entscheidung zählen die Validierung von Ausgaben, der Zugriff auf Anwendungsdienste, die Verantwortung für den Workflow und die Wiederaufnahme nach Fehlern. Ein Leistungsvergleich steht dabei nicht im Mittelpunkt.

Was ist Pydantic AI?

Pydantic AI ist das Python-SDK für Agenten vom Pydantic-Team. Es bündelt ein Modell, Anweisungen, aufrufbare Python-Funktionen und einen optionalen Ausgabetyp in einem Agent, den die Anwendung ausführt. Das Modell erzeugt die Antworten; das SDK steuert die Interaktion darum herum. Die aktuelle Übersicht beschreibt ein umfangreicheres SDK. Für eine Produktfunktion ist dies jedoch der entscheidende Kern.

Anschaulich erhält ein unberechenbarer Mitarbeiter damit einen klaren Funktionsvertrag. Die Anwendung liefert den Kontext und die erlaubten Operationen und verlangt anschließend ein Ergebnis mit benannten Feldern. Das hilft etwa einer Supportfunktion, die eine Kategorie und einen nächsten Schritt liefern muss, mit denen gewöhnlicher Python-Code weiterarbeiten kann.

Agenten in Pydantic AI: einmal konfigurieren, mehrfach ausführen

Ein Agent enthält die Konfiguration für eine Aufgabe. Ein Lauf ist ein konkreter Versuch, diese Aufgabe mit einem Prompt und den zur Laufzeit bereitgestellten Abhängigkeiten zu erledigen. In einem synchronen Skript lässt sich run_sync() aufrufen, in asynchronem Anwendungscode await agent.run(). Nach Abschluss stellt das Ergebnis seinen endgültigen Wert über .output bereit. Diese Schnittstellen sind in der Agent-Dokumentation beschrieben.

Die Typisierung erfüllt dabei zwei unterschiedliche Aufgaben. Statische Typisierung hilft dem Editor oder Typprüfer, Unstimmigkeiten im Python-Code zu erkennen. Die Ausgabevalidierung zur Laufzeit prüft dagegen die vom Modell gelieferten Daten anhand des deklarierten Schemas. Eine mehrdeutige Supportanfrage wird durch keines von beidem eindeutig.

Tools in Pydantic AI: Funktionen mit Anwendungskontext

Mit Funktions-Tools kann das Modell eine Aktion anfordern, die der Anwendungscode ausführen kann, etwa ein Abonnement nachschlagen. Eine Funktion, die den Kontext des Laufs benötigt, wird mit @agent.tool registriert. Kommt sie ohne diesen Kontext aus, dient dazu @agent.tool_plain. Type Hints beschreiben die Argumente; Docstrings helfen dabei, dem Modell die Funktion zu erklären. Wie daraus Tool-Schemas entstehen, erläutert die Dokumentation zu Funktions-Tools.

Dependency Injection bedeutet, einem Lauf die Dienste zu übergeben, die er benötigt. deps_type=CustomerContext deklariert den erwarteten Python-Typ, deps=customer_context übergibt die tatsächliche Instanz. Ein Tool erhält RunContext[CustomerContext] und greift über ctx.deps darauf zu. Dieser Kontext kann einen authentifizierten Kunden, eine Datenbankverbindung oder einen API-Client enthalten. Der Leitfaden zu Abhängigkeiten weist ausdrücklich darauf hin, dass deps_type die Typprüfung unterstützt, das übergebene Abhängigkeitsobjekt aber nicht zur Laufzeit validiert.

Für die SaaS-Entwicklung ergibt sich daraus ein konkreter Vorteil: Der Server kann das Kundenkonto festlegen, bevor das Modell eine Abfrage anfordert. Die Berechtigungsprüfung gehört weiterhin in den Code, der die Daten abruft. Ein Datenbank-Client erhält keine eingeschränkten Leserechte, nur weil er über einen typisierten Kontext übergeben wird.

Strukturierte Ausgaben in Pydantic AI: Was wird validiert?

output_type legt fest, welches Ergebnis die Anwendung erwartet. Wird ein Pydantic-BaseModel übergeben, also eine Python-Klasse mit typisierten Feldern, leitet Pydantic AI daraus ein Schema ab und validiert die erzeugten Daten. Laut Dokumentation zu Ausgaben werden auch andere Typen unterstützt, darunter Dataclasses, Listen und Unions.

Die drei Ausgabemodi unterscheiden sich darin, wie das Modell diese Daten erzeugen soll:

Dies sind die drei dokumentierten Ausgabemodi des SDK. Sie stehen nicht für drei Genauigkeitsstufen. Entscheidend ist, einen vom Modell unterstützten Mechanismus zu wählen und die Ergebnisse anschließend an der eigenen Aufgabe zu prüfen.

Ein Validierungsfehler kann an das Modell zurückgegeben werden, damit es einen weiteren Versuch unternimmt. Die Zahl der Wiederholungen ist begrenzt. Sind die Wiederholungsversuche für die Ausgabe ausgeschöpft, kann UnexpectedModelBehavior ausgelöst werden. Die Anwendung braucht deshalb einen definierten Fehlerpfad, etwa eine Rückfrage nach fehlenden Angaben oder die Übergabe an einen Menschen. Näheres beschreibt die Dokumentation zu Wiederholungsversuchen.

Pydantic AI Tutorial: eine validierte Supportentscheidung zurückgeben

Am Anfang sollte ein Entscheidungsobjekt ohne Schreibzugriff stehen, bevor der Agent Änderungen vornehmen darf. Dieses Beispiel überträgt die dokumentierten Muster für Agent, RunContext und output_type auf eine kleine Aufgabe zur Einordnung von Supportanfragen.

Der aktuelle Installationsleitfaden setzt Python 3.11 oder neuer voraus. In einer virtuellen Umgebung lässt sich die Bibliothek so installieren:

python -m pip install pydantic-ai

Für ein Konto mit Zugriff auf das Modell muss OPENAI_API_KEY in der Umgebung gesetzt sein. Den folgenden Code als triage.py speichern und mit python triage.py ausführen. Die Modellkennung entspricht der aktuellen Agent-Dokumentation. Sie lässt sich durch ein unterstütztes Modell ersetzen, auf das das verwendete Konto Zugriff hat.

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Customer:
    plan: str

class Triage(BaseModel):
    category: Literal['billing', 'technical']
    priority: Literal['normal', 'urgent']
    summary: str

agent = Agent(
    'openai:gpt-6.1-sol',
    deps_type=Customer,
    output_type=Triage,
    instructions=(
        'Triage the support message. Use customer_plan for context. '
        'Summarize the issue without inventing account facts.'
    ),
)

@agent.tool
def customer_plan(ctx: RunContext[Customer]) -> str:
    """Return the authenticated customer's plan."""
    return ctx.deps.plan

if __name__ == '__main__':
    result = agent.run_sync(
        'I was charged twice for my subscription.',
        deps=Customer(plan='business'),
    )
    print(result.output.model_dump())

Nach einem erfolgreichen Lauf ist result.output ein Triage-Objekt. Kategorie und Priorität müssen den deklarierten Auswahlmöglichkeiten entsprechen; model_dump() wandelt das Objekt in ein Dictionary um. Das Kontext-Tool, das typisierte Ergebnis und die Zurückweisung einer ungültigen Kategorie wurden für dieses Beispiel offline mit TestModel geprüft. Die vom Modell erzeugten Formulierungen und die Qualität der Einordnung müssen weiterhin anhand eigener Fälle evaluiert werden.

Der Kundenkontext dient hier der Veranschaulichung. In einem Produkt sollte er aus der authentifizierten Anfrage und den eigenen Kontodaten entstehen. Außerdem braucht es eine Definition dafür, wann ein Fall dringend ist: Das Schema enthält gültige Bezeichnungen, aber keine Regel zur Dringlichkeit. Diese fehlende Geschäftsregel ist wichtiger als ein zusätzlicher Agent.

Modelle in Pydantic AI: Anbieter wechseln, Verhalten neu prüfen

Pydantic AI verringert den anbieterspezifischen Integrationsaufwand. Ein Modellwechsel verändert trotzdem das Verhalten. Viele Anbindungen verwenden eine Kennung nach dem Muster <provider>:<model>. Manche benötigen ein explizit angegebenes Modell oder einen Client, passende Zugangsdaten und zusätzliche Installationspakete. Welche Funktionen verfügbar sind, hängt vom gewählten Modell und der API ab, wie das Anbieterverzeichnis deutlich macht.

Das Verzeichnis umfasst OpenAI, Anthropic, Google/Gemini, AWS Bedrock, Groq, Mistral, xAI und Ollama. Darüber hinaus sind folgende Anbindungen dokumentiert:

• Modell- und Inferenzdienste: Alibaba Cloud/Qwen, Cerebras, Cohere, Crusoe, DeepSeek, Fireworks AI, Heroku AI, Hugging Face, Meta, Moonshot AI/Kimi, Nebius AI Studio, OVHcloud AI Endpoints, SambaNova, Snowflake Cortex, Together AI und Z.AI.
• Cloud-, Gateway- und selbst gehostete Optionen: Google Cloud/Vertex AI, Microsoft Azure/Foundry, Pydantic AI Gateway, LiteLLM, OpenRouter, Vercel AI Gateway und vLLM.
• Weitere Zugänge und Anbindungen für Entscheidungsmodelle: GitHub Copilot, OpenAI Codex, OpenAI Decisions API, System One API und TypeSafe (Jev).

Diese Namen bezeichnen unterschiedliche Zugangswege zu Modellen. Sie versprechen keinen austauschbaren Funktionsumfang. Ein lokales Modell kann Tools anders nutzen als ein gehostetes Spitzenmodell; auch eine kompatible API kann andere Einschränkungen für Schemas vorgeben.

Für Gründer schafft Portabilität eine Ausstiegsmöglichkeit und Spielraum für Experimente. Für die Entwicklung bleibt der Abnahmetest derselbe: Wählt das Ersatzmodell die richtigen Tools, hält es das Ausgabeschema ein und trifft es bei denselben Fällen akzeptable Entscheidungen? Diese Nachweise sollten vorliegen, bevor das Standardmodell im Produktivbetrieb geändert wird.

MCP und dauerhafte Ausführung: Tools anbinden, Fortschritt sichern

MCP verbindet einen Agenten mit Tool-Servern; dauerhafte Ausführung hilft einem Lauf, Unterbrechungen zu überstehen. Die beiden Ansätze lösen unterschiedliche Probleme.

Das Model Context Protocol, kurz MCP, standardisiert, wie Anwendungen KI-Clients Tools und Kontext bereitstellen. Die MCP-Unterstützung von Pydantic AI akzeptiert Server-URLs sowie Clients oder Toolsets als Eingaben. Wo unterstützt, stehen auch native MCP-Optionen der Anbieter zur Verfügung. So lässt sich ein Tool-Server wiederverwenden, statt für jeden Agenten eine neue Integration zu schreiben. Welche Kunden die Operationen dieses Servers nutzen dürfen, entscheidet MCP nicht.

Dauerhafte Ausführung bedeutet, den Fortschritt zu sichern, damit die Arbeit nach einem Fehler, Neustart oder längeren Warten fortgesetzt werden kann. Die aktuelle Dokumentation zur dauerhaften Ausführung nennt 9 Lösungen:

• Gemeinsam mit den Anbieterteams gepflegt: Temporal, DBOS, Prefect, Restate und AWS Lambda.
• Externe SDK-Integrationen: Kitaru, Apache Airflow, Absurd und pgtask.

Für weitere Ausführungsumgebungen gibt es außerdem einen Backend-Builder. Eine dokumentierte Integration ist sinnvoll, wenn ein Agent die Anfrage oder den Prozess überdauern muss, durch den er gestartet wurde. Dass diese Integrationen existieren, macht einen bloßen Agent-Aufruf noch nicht zu einer dauerhaft ausführbaren Bereitstellung.

Ein Supportauftrag könnte etwa eine Erstattungsempfehlung vorbereiten, auf Freigabe warten und sie anschließend umsetzen. Ein gespeicherter Lauf kann die wartende Arbeit erhalten. Für den Zahlungsvorgang braucht es dennoch Idempotenz: Eine wiederholte Anfrage darf keine weitere Erstattung auslösen. Es muss feststehen, wie eine bereits ausgeführte Operation erkannt wird und wie sich ein unklarer Ausgang abgleichen lässt. Diese Verantwortung liegt neben der Ausführungsumgebung weiterhin bei der Anwendung.

Pydantic AI Evals: die Entscheidung hinter dem Objekt prüfen

Pydantic Evals prüft, ob der Agent seine Aufgabe akzeptabel erledigt hat, über die bloße Verarbeitbarkeit seiner Ausgabe hinaus. Es ist ein eigenständiges, codebasiertes Evaluationspaket und setzt Pydantic AI nicht voraus. Dazu werden Fälle und Evaluatoren definiert, die Aufgabe anhand dieser Fälle ausgeführt und anschließend die Ergebnisse im Bericht geprüft. Die Dokumentation behandelt sowohl die Bewertung der endgültigen Ausgaben als auch der Abfolge von Tool-Aufrufen, also der Aktionen während eines Laufs.

Für das Triage-Beispiel bieten sich Fälle mit doppelter Abbuchung, fehlgeschlagener Anmeldung, fehlendem Kontokontext und einer Nachricht an, die den Assistenten zum Ignorieren seiner Anweisungen auffordert. Geprüft werden sollten die Kategorie, die Eskalationsentscheidung und die Frage, ob die erforderliche Kontoabfrage stattgefunden hat. Dazu gehören auch Fälle, in denen eine Rückfrage die akzeptable Antwort ist.

Im Betrieb erklärt ein Trace einen einzelnen Lauf; eine Evaluation misst das Verhalten über mehrere Fälle hinweg. Pydantic AI verwendet OpenTelemetry, einen Standard für Anwendungstelemetrie, und unterstützt über seine Instrumentierung weitere Observability-Backends. Schlägt ein Fall fehl, helfen der Blick auf die Modellanfrage und die Tool-Aufrufe. Anschließend sollte der Fall im Evaluationsdatensatz verbleiben.

Optional bietet Pydantic Logfire Tracing für Agenten, Modelle und Tools. Der Tarif Personal ist kostenlos, Team beginnt laut Preisseite bei $49/Monat. Zusätzliche Nutzung und weitere Nutzerplätze werden separat berechnet.

Wann ist Pydantic AI das passende Agenten-Framework?

Die Abstraktion sollte zu dem Teil der Funktion passen, der tatsächlich schwierig ist. Für Python-Entwickler mit bestehenden Domänenmodellen und Diensten gehört Pydantic AI in die engere Auswahl, wenn vor allem typisierte Eingaben, Tools und Ausgaben integriert werden müssen. Technische Gründer sollten prüfen, welche Wahl das kleinste betriebliche System ergibt, das das Unternehmen erklären und warten kann.

Pydantic AI oder LangGraph?

LangGraph ist der stärkere Ausgangspunkt, wenn der umgebende Workflow ausdrücklich modelliert werden soll. Die Dokumentation stellt langlebige, zustandsbehaftete Agenten, dauerhafte Ausführung und menschliches Eingreifen in den Mittelpunkt. Ein Beispiel wäre eine Anwendung mit verbindlichen Stationen: Belege sammeln, eine Freigabe einholen, eine autorisierte Aktion ausführen und das Ergebnis abgleichen.

Pydantic AI ist attraktiv, wenn ein typisierter Agent als Baustein in einem Prozess arbeitet, den die Anwendung bereits steuert. Es kann ebenfalls Teil dauerhaft ausführbarer Workflows sein; Persistenz allein entscheidet die Wahl daher nicht. Maßgeblich ist, ob der Geschäftsprozess um den Agenten herum modelliert oder vor allem das Verhalten des Agenten selbst konfiguriert werden soll. Bei LangGraph bleiben Workflow-Entwurf und Zustandsverwaltung in eigener Verantwortung. Die Grenze von Pydantic AI liegt darin, dass sein praktischer Agentenvertrag nicht zugleich den gesamten Prozess entwirft.

Pydantic AI oder LangChain?

LangChain ist sinnvoll, wenn die vorhandenen Modell- und Tool-Integrationen sowie die Agentenarchitektur bereits zur Anwendung passen. Die Agenten von LangChain bauen laut LangChain-Übersicht auf LangGraph auf. Wer die höher abstrahierte Agenten-API wählt, behält also diese Laufzeitbasis.

Pydantic AI passt zu einem Python-Dienst, wenn seine Verträge für Abhängigkeiten und Ausgaben der bestehenden Arbeitsweise im Code entsprechen. Eine funktionierende LangChain-Funktion sollte bleiben, solange sich keine konkrete Komplexität benennen lässt, die eine Migration beseitigt. Auch die Abstraktion von LangChain muss verstanden werden, wenn Verhalten die Agenten- und Workflow-Ebene durchläuft. Ein Bibliothekswechsel verlagert diese Arbeit lediglich. Den Zusammenhang vertieft der Artikel LangChain vs LangGraph.

OpenAI Agents SDK oder direkte API-Aufrufe?

Das OpenAI Agents SDK passt zu einer von der Anwendung gesteuerten Agentenschleife mit Tools, Übergaben und Tracing. Das SDK läuft in der eigenen Anwendung und unterstützt strukturierte Ausgaben. Seine Anbieterschnittstellen ermöglichen auch Modelle anderer Anbieter als OpenAI. Typisierte Ausgaben und freie Anbieterwahl sind daher keine Alleinstellungsmerkmale von Pydantic AI.

Dieses SDK bietet sich an, wenn sein Agenten- und Übergabemodell zu der OpenAI-Integration passt, die dauerhaft gepflegt werden soll. Pydantic AI ist die passendere Wahl, wenn sein Python-Abhängigkeitsmodell und seine Anbieterkonfiguration besser zur Anwendung passen. Bei beiden bleiben Bereitstellung, Tool-Berechtigungen und die Korrektheit der Anwendung in eigener Verantwortung.

Direkte API-Aufrufe genügen, wenn die Aufgabe aus einer Modellanfrage mit wenig deterministischem Code darum herum besteht. Direkte APIs können bereits durch Schemas eingeschränkte Ausgaben liefern. Eine Belegextraktion braucht nicht allein deshalb ein Agenten-Framework, weil ihr Ergebnis ein Pydantic-Objekt ist. Die Grenze ist erreicht, wenn Tool-Schleifen, Wiederholungen nach Validierungsfehlern und Instrumentierung für mehrere Funktionen immer wieder neu gebaut werden.

Bei einer breiteren Auswahl hilft der vorhandene Leitfaden zu KI-Agenten-Frameworks. Geht es noch um die Entscheidung zwischen ausdrücklicher Workflow-Steuerung und spezialisierten Agentenrollen, führt LangGraph vs CrewAI weiter.

Was bei typisierten Agenten zu viel versprochen wird

Überzogen ist die Vorstellung, ein typisierter Agent sei automatisch ein korrekt arbeitendes Produktivsystem. Mehrere Grenzen kann die Bibliothek nicht aufheben:

• Typsicherheit garantiert keine sachliche Richtigkeit. Eine formal korrekte Antwort kann die Anfrage falsch verstehen. Es muss feststehen, was anhand maßgeblicher Datensätze überprüft wird.
• Modellportabilität bedeutet keine gleichbleibende Qualität. Eine neue Anbieterkonfiguration braucht dieselbe aufgabenbezogene Evaluation wie ein neuer Prompt.
• Dauerhafte Ausführung ergibt noch keine fertige Bereitstellung. Ausführungsumgebung, Speicher und Wiederherstellung müssen passend zur Funktion ausgewählt und betrieben werden.
• Ein Wiederholungsversuch verursacht zusätzliche Arbeit. Eine weitere Modellanfrage erhöht Latenz und Nutzung. Die Anwendung braucht einen ausdrücklich festgelegten Ausgang für ausgeschöpfte Wiederholungsversuche.

Der Einstieg lohnt sich jetzt, wenn die nächste Python-Funktion ohnehin Tools und strukturierte Entscheidungen benötigt. Mit einer Framework-Migration lässt sich warten, wenn das vorhandene System funktioniert und der versprochene Nutzen nur aus aufgeräumterem Demo-Code besteht. Für eine einfache Extraktionsfunktion mit ausreichender Validierung und Fehlerbehandlung ändert sich dagegen wenig.

Häufige Fragen zu Pydantic AI

Was sich in der nächsten Woche umsetzen lässt

Eine kleine Funktion ohne Schreibzugriff braucht klare Abnahmekriterien, bevor sie mehr Autonomie erhält. In einem Supportprodukt bietet sich das Triage-Objekt aus dem Beispiel als Einstieg an. Die abschließende Aktion am Kundenkonto bleibt dabei im gewöhnlichen Anwendungscode.

Praktische Hinweise zum Entwickeln von KI-Funktionen gibt es im Newsletter.