Pydantic AI 2.0 Grundlagen: KI-Anwendungen mit Type-Safety

Pydantic AI 2.0 ist ein Framework für die Entwicklung von KI-Anwendungen mit Type-Safety und Validierung. Es ermöglicht strukturierte Ausgaben von Large Language Models (LLMs) und integriert sich nahtlos mit Pydantic-Modellen.

Was ist Pydantic AI?

Pydantic AI ist eine Python-Bibliothek, die auf Pydantic aufbaut und speziell für die Arbeit mit LLMs entwickelt wurde. Sie bietet:

Type-Safe KI-Ausgaben: KI-Antworten werden automatisch in Pydantic-Modelle konvertiert
Validierung: Eingaben und Ausgaben werden gegen Schemas validiert
Multi-Provider Support: OpenAI, Anthropic, Groq, lokale Modelle (Ollama, vLLM)
Streaming: Echtzeit-Streaming von strukturierten Daten
Tool-Calling: Integrierte Unterstützung für Function Calling

Warum Pydantic AI nutzen?

Typischer Nutzer

Pydantic AI ist ideal für folgende Zielgruppen:

Python-Entwickler, die bereits Pydantic nutzen und Type-Safety schätzen
Backend-Entwickler, die strukturierte KI-Ausgaben in APIs integrieren wollen
Data Engineers, die KI-gestützte Datenextraktion und -validierung benötigen
Entwickler von KI-Anwendungen, die zuverlässige, validierte Ausgaben benötigen

Typischer Nutznießer

Wer profitiert von Pydantic AI in einem Projekt?

Endbenutzer: Erhalten konsistente, validierte Daten statt unstrukturierter Text-Antworten
Entwickler: Sparen Zeit bei der Validierung und Fehlerbehandlung
Systeme: Integration ist einfacher, da Ausgaben bereits typisiert sind
QA-Teams: Weniger Tests nötig, da Validierung automatisch erfolgt

Projektüberlegungen: Wann Pydantic AI nutzen?

Bevor du Pydantic AI in dein Projekt integrierst, stelle dir folgende Fragen:

1. Benötigst du strukturierte Ausgaben?

✅ Ja: Pydantic AI ist perfekt für dich, wenn du KI-Antworten in spezifischen Formaten brauchst (JSON, Objekte, Enums)
❌ Nein: Wenn du nur freien Text brauchst, ist Pydantic AI möglicherweise overkill

2. Nutzt du bereits Python und Pydantic?

✅ Ja: Pydantic AI integriert sich nahtlos in dein bestehendes Ökosystem
❌ Nein: Wenn du nicht Python nutzt, ist Pydantic AI nicht geeignet (Python-spezifisch)

3. Wie wichtig ist Type-Safety für dein Projekt?

✅ Sehr wichtig: Pydantic AI bietet compile-time und runtime Validierung
⚠️ Mittelig: Pydantic AI kann helfen, aber Alternativen wie LangChain könnten ausreichend sein
❌ Unwichtig: Wenn du keine strikte Typisierung brauchst, sind einfachere Alternativen besser

4. Planst du Multi-Provider Support?

✅ Ja: Pydantic AI macht es einfach, zwischen OpenAI, Anthropic, Groq und lokalen Modellen zu wechseln
❌ Nein: Wenn du nur einen Provider nutzt, ist dies kein Entscheidungskriterium

5. Wie komplex ist deine KI-Integration?

✅ Einfach bis mittel: Pydantic AI ist ideal für strukturierte Ausgaben und Tool-Calling
⚠️ Sehr komplex: Für komplexe Multi-Agent-Systeme könnte LangChain oder LangGraph besser geeignet sein

Entscheidungsmatrix

Anforderung	Pydantic AI	LangChain	Direkte API
Strukturierte Ausgaben	✅ Optimal	⚠️ Möglich	❌ Manuell
Type-Safety	✅ Native	⚠️ Eingeschränkt	❌ Keine
Einfachheit	✅ Hoch	⚠️ Mittel	⚠️ Mittel
Multi-Agent	⚠️ Eingeschränkt	✅ Stark	❌ Nein
Provider-Agnostisch	✅ Ja	✅ Ja	❌ Nein
Lernkurve	🟢 Niedrig	🟡 Mittel	🟡 Mittel

Wann Pydantic AI NICHT nutzen solltest

Du nutzt nicht Python
Du brauchst nur freien Text ohne Struktur
Du benötigst komplexe Multi-Agent-Orchestrierung (nutze LangGraph)
Du willst minimale Abhängigkeiten
Dein Projekt ist sehr klein und einfach (direkte API reicht)

Wann Pydantic AI nutzen solltest

Du nutzt Python und Pydantic bereits
Du brauchst zuverlässige, validierte KI-Ausgaben
Type-Safety ist dir wichtig
Du willst zwischen LLM-Providern wechseln können
Du entwickelst APIs mit KI-Integration
Du willst Tool-Calling mit validierten Parametern

Praxisbeispiel: Unternehmen mit API zu Langdock

Innerhalb eines Unternehmens nutze ich FastAPI mit Langdock, um innerhalb des Unternehmens eine DSGVO-konforme Umgebung zu schaffen. Der Chat funktioniert, die Chatbots ebenfalls. Warum solltes ich Pydantic AI in Betracht ziehen?

Antwort: In den aktuellen Szenario wahrscheinlich nicht.

Wenn der Chatbot nur freien Text liefert und keine strukturierten Daten zurückgibt, ist Pydantic AI überflüssig. Langdock und FastAPI erledigen bereits die DSGVO-Konformität und die Chat-Funktionalität.

Wann Pydantic AI allerdings dennoch benötigt werden könnte:

Angenommen, wir erweitern das Szenario ein wenig:

# Aktuell: Nur freier Text
response = "Hallo! Ich kann dir helfen."

# Mit Pydantic AI: Strukturierte Ausgaben
from pydantic import BaseModel
from pydantic_ai import Agent

class SupportTicket(BaseModel):
    kategorie: str  # z.B. "technisch", "billing", "hr"
    prioritaet: str  # z.B. "hoch", "mittel", "niedrig"
    beschreibung: str
    assigned_to: str | None = None

# KI analysiert die Anfrage und gibt strukturierte Daten zurück
ticket = agent.run_sync(
    "Mein Rechner startet nicht mehr, ich brauche dringend Hilfe!",
    result_type=SupportTicket
)
# SupportTicket(kategorie='technisch', prioritaet='hoch', beschreibung='Mein Rechner startet nicht mehr...', assigned_to=None)

Konkretes Beispiel für das Unternehmen:

Ohne Pydantic AI: Chatbot gibt Text zurück → Du musst den Text parsen, um Kategorien zu erkennen
Mit Pydantic AI: Chatbot gibt direkt ein SupportTicket-Objekt zurück → Du kannst es direkt in deine Datenbank speichern, ohne Parsing

Fazit für das Szenario:

Wenn du nur Chats brauchst: Kein Pydantic AI nötig
Wenn du strukturierte Daten aus Chats extrahieren willst (Tickets, Formulare, Berichte): Pydantic AI sehr nützlich

Merksatz:

Ein Chatbot braucht kein Pydantic AI. Ein KI-Agent meistens schon. Typische Einsatzfälle sind Code-Assistenten, Recherche-Agenten, Automatisierungen, Workflows mit mehreren Tools oder Anwendungen, die typisierte und validierte Ausgaben benötigen.

Installation

pip install pydantic-ai

Für spezifische Provider:

pip install pydantic-ai[openai]  # OpenAI
pip install pydantic-ai[anthropic]  # Anthropic
pip install pydantic-ai[openai,anthropic]  # Beide

Grundlagen: Strukturierte Ausgaben

Einfaches Beispiel

from pydantic import BaseModel
from pydantic_ai import Agent

class UserResponse(BaseModel):
    name: str
    age: int
    email: str

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

result = agent.run_sync(
    'Erstelle ein Benutzerprofil für einen Entwickler',
    result_type=UserResponse
)

print(result.data)
# UserResponse(name='Max Mustermann', age=28, email='max@example.com')

Mit System-Prompt

from pydantic_ai import Agent, SystemPrompt

agent = Agent(
    'openai:gpt-4o',
    system_prompt=SystemPrompt('Du bist ein hilfreicher Assistent für Entwickler.')
)

result = agent.run_sync(
    'Erstelle ein Profil für einen Python-Entwickler',
    result_type=UserResponse
)

Komplexere Modelle

Verschachtelte Strukturen

from typing import List
from pydantic import BaseModel

class Skill(BaseModel):
    name: str
    years_experience: int
    level: str  # beginner, intermediate, advanced

class DeveloperProfile(BaseModel):
    name: str
    role: str
    skills: List[Skill]
    github_url: str | None = None
    available_for_hire: bool

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

result = agent.run_sync(
    'Erstelle ein detailliertes Profil für einen Senior Python-Entwickler',
    result_type=DeveloperProfile
)

Enum-Validierung

from enum import Enum
from pydantic import BaseModel

class SkillLevel(str, Enum):
    BEGINNER = 'beginner'
    INTERMEDIATE = 'intermediate'
    ADVANCED = 'advanced'
    EXPERT = 'expert'

class Skill(BaseModel):
    name: str
    level: SkillLevel

Multi-Provider Support

OpenAI

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o')
result = agent.run_sync('Hallo Welt!')

Anthropic

agent = Agent('anthropic:claude-3-5-sonnet-20241022')
result = agent.run_sync('Hallo Welt!')

Lokale Modelle (Ollama)

agent = Agent('ollama:llama3.2')
result = agent.run_sync('Hallo Welt!')

Groq

agent = Agent('groq:llama-3.1-70b-versatile')
result = agent.run_sync('Hallo Welt!')

Tool-Calling

Einfaches Tool

from pydantic_ai import Agent, Tool

def get_weather(location: str) -> str:
    """Holt das Wetter für einen Ort."""
    # In der Realität: API-Aufruf
    return f'In {location} sind es 22°C.'

agent = Agent('openai:gpt-4o', tools=[Tool(get_weather)])

result = agent.run_sync('Wie ist das Wetter in Berlin?')

Mit Pydantic-Modellen

from pydantic import BaseModel

class WeatherQuery(BaseModel):
    location: str
    unit: str = 'celsius'

def get_weather(query: WeatherQuery) -> str:
    return f'In {query.location} sind es 22°{query.unit}.'

agent = Agent('openai:gpt-4o', tools=[Tool(get_weather)])

Streaming

Text-Streaming

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

async for chunk in agent.run_stream('Erzähle mir eine Geschichte'):
    print(chunk.content, end='')

Strukturiertes Streaming

async for chunk in agent.run_stream(
    'Erstelle ein Benutzerprofil',
    result_type=UserResponse
):
    if chunk.content:
        print(chunk.content, end='')

Fehlerbehandlung

Validierungsfehler

from pydantic import ValidationError

try:
    result = agent.run_sync(
        'Erstelle ein Profil',
        result_type=UserResponse
    )
except ValidationError as e:
    print(f'Validierungsfehler: {e}')

Retry-Logik

from pydantic_ai import Agent, RetryPolicy

agent = Agent(
    'openai:gpt-4o',
    retry_policy=RetryPolicy(max_retries=3)
)

Best Practices

1. Klare Modelle definieren

# ✅ Gut
class UserProfile(BaseModel):
    name: str
    email: str
    age: int

# ❌ Schlecht
class Response(BaseModel):
    data: dict  # Keine Type-Safety

2. System-Prompts nutzen

agent = Agent(
    'openai:gpt-4o',
    system_prompt=SystemPrompt(
        'Du bist ein technischer Dokumentations-Assistent. '
        'Antworte präzise und strukturiert.'
    )
)

3. Validierung nutzen

from pydantic import field_validator

class UserProfile(BaseModel):
    email: str
    
    @field_validator('email')
    def validate_email(cls, v):
        if '@' not in v:
            raise ValueError('Ungültige E-Mail')
        return v

4. Kostenoptimierung

# Kleinere Modelle für einfache Aufgaben
agent_simple = Agent('openai:gpt-4o-mini')

# Größere Modelle für komplexe Aufgaben
agent_complex = Agent('openai:gpt-4o')

Integration mit bestehenden Projekten

FastAPI Integration

from fastapi import FastAPI
from pydantic_ai import Agent

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

@app.post('/generate')
async def generate(prompt: str):
    result = await agent.run(prompt)
    return {'response': result.content}

Async/Await

import asyncio

async def main():
    agent = Agent('openai:gpt-4o')
    result = await agent.run('Hallo Welt!')
    print(result.content)

asyncio.run(main())

Häufige Fehler

1. Fehlende API-Keys

import os
from pydantic_ai import Agent

# API-Key setzen
os.environ['OPENAI_API_KEY'] = 'sk-...'

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

2. Ungültige Modelle

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

# ❌ Falsch
agent = Agent('openai:gpt-5')  # Modell existiert nicht

3. Fehlende Typ-Hints

# ✅ Mit Typ-Hints
def get_weather(location: str) -> str:
    return f'Wetter in {location}'

# ❌ Ohne Typ-Hints
def get_weather(location):
    return f'Wetter in {location}'

Pydantic AI vs. Alternativen

Feature	Pydantic AI	LangChain	LlamaIndex
Type-Safety	✅ Native	⚠️ Eingeschränkt	⚠️ Eingeschränkt
Pydantic-Integration	✅ Vollständig	⚠️ Partial	⚠️ Partial
Multi-Provider	✅ Einfach	✅ Ja	✅ Ja
Streaming	✅ Ja	✅ Ja	✅ Ja
Tool-Calling	✅ Native	✅ Ja	✅ Ja
Lernkurve	🟢 Niedrig	🟡 Mittel	🟡 Mittel

Täglicher Artikel