Pydantic AI: Przewodnik produkcyjny (poza etapem Hello World)

Pydantic AI: Przewodnik produkcyjny (poza etapem Hello World)

Surowe odpowiedzi LLM potrafią zepsuć aplikacje. Prosisz o JSON, a dostajesz markdown. Prosisz o liczbę od 1 do 10, a otrzymujesz „Jasne! Oto liczba: siedem”. Jeśli budowałeś cokolwiek rzeczywistego z wykorzystaniem API LLM, pisałeś defensywny kod parsujący, który sprawiał, że zaczynałeś kwestionować swoje wybory zawodowe. Pydantic AI rozwiązuje ten problem – to bezpieczny typowo framework agentowy stworzony przez ten sam zespół, który stoi za Pydantic i FastAPI. Traktuj go jak „FastAPI dla agentów AI”: definiujesz, czego chcesz, za pomocą podpowiedzi typów Pythona, a framework zajmuje się walidacją, ponownymi próbami i wywoływaniem narzędzi.

Ten przewodnik po Pydantic AI jest przeznaczony dla programistów, którzy wykonali już pierwsze wywołanie LLM i chcą poznać wzorce produkcyjne: strukturalne wyjścia, które nie psują aplikacji, wstrzykiwanie zależności umożliwiające testowalność agentów oraz rzeczywiste narzędzia wykraczające poza proste API pogodowe. Na końcu będziesz mieć działające agenty z narzędziami, DI, streamingiem i testami.

Pydantic AI w skrócie

Najbardziej wyróżniającymi się funkcjami są wyjścia strukturalne (walidowane za pomocą modeli Pydantic), wstrzykiwanie zależności (podobnie jak Depends w FastAPI) oraz TestModel (mock LLM do testowania bez wywołań API). Jeśli przyszedłeś ze świata LangChain i zastanawiasz się „czy istnieje coś czystszego?”, to prawdopodobnie jest to właśnie ono.

Instalacja i pierwszy agent

# Install with OpenAI support (swap openai for anthropic, google, etc.)
pip install "pydantic-ai[openai]"

# Set your API key
export OPENAI_API_KEY="sk-..."

Twój pierwszy agent w 5 liniach:

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o", system_prompt="You are a helpful assistant.")

result = agent.run_sync("What's the capital of France?")
print(result.output)  # "Paris"

To wszystko. Agent opakowuje model, run_sync wysyła prompt i zwraca wynik. result.output jest tutaj zwykłym ciągiem znaków, ale to zaraz się zmieni.

Wyjścia strukturalne, czyli powód istnienia Pydantic AI

To jest kluczowa funkcja. Zamiast otrzymywać ciąg znaków z LLM i mieć nadzieję, że jest to poprawny JSON, definiujesz model Pydantic, a agent zwraca zwalidowany obiekt Pythona.

Przed: Surowe wyjście LLM

# The old way -- hope for the best
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Review the movie Inception. Return JSON with title, rating (1-10), summary."}]
)
# response.choices[0].message.content is a string
# Maybe it's JSON. Maybe it has markdown code fences. Maybe rating is "eight".
# You're on your own.

Po: Strukturalne z Pydantic AI

from pydantic import BaseModel
from pydantic_ai import Agent

class MovieReview(BaseModel):
    title: str
    rating: int  # Guaranteed to be an int, not "eight"
    summary: str
    recommended: bool

agent = Agent("openai:gpt-4o", result_type=MovieReview)

result = agent.run_sync("Review the movie Inception")
review = result.output  # This is a MovieReview instance, not a string

print(f"{review.title}: {review.rating}/10")
print(f"Recommended: {review.recommended}")
print(review.summary)

Różnica jest kolosalna. result.output jest prawdziwym obiektem MovieReview. Jeśli LLM zwróci rating: "eight" zamiast rating: 8, walidator Pydantic to wychwyci. Aby dowiedzieć się więcej o tym, jak to działa u różnych dostawców, zobacz nasz przewodnik na temat wyjść strukturalnych u różnych dostawców LLM.

Co się dzieje, gdy walidacja nie powiedzie się

Oto część, której nie pokazuje żaden inny tutorial: co się dzieje, gdy LLM popełni błąd?

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class StrictReview(BaseModel):
    title: str
    rating: int = Field(ge=1, le=10)  # Must be 1-10
    pros: list[str] = Field(min_length=2)  # At least 2 pros

agent = Agent("openai:gpt-4o", result_type=StrictReview)

# If the LLM returns rating=15 or only 1 pro:
# 1. Pydantic validation fails
# 2. The error message is sent BACK to the LLM
# 3. The LLM tries again with the corrected output
# 4. This repeats up to the retry limit
result = agent.run_sync("Review the movie Inception")

Ta pętla ponawiania z informacją zwrotną to zabójcza cecha Pydantic AI. LLM uczy się na własnych błędach walidacji. Nie piszesz logiki ponawiania, framework zajmuje się tym za Ciebie.

Werdykt: Wyjścia strukturalne to jedyny najlepszy powód, by używać Pydantic AI zamiast surowych wywołań API. Jeśli ręcznie parsujesz JSON z LLM, przestań to robić.

Narzędzia i wywoływanie funkcji

Narzędzia pozwalają Twojemu agentowi wywoływać funkcje Pythona, aby uzyskać rzeczywiste dane. Zamiast halucynować fakty, LLM może odpytać Twoją bazę danych, przeszukać dokumentację lub wywołać API.

Rejestrowanie narzędzia

from pydantic_ai import Agent

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

@agent.tool
async def search_docs(query: str) -> str:
    """Search the documentation for relevant articles."""
    # Your actual search logic here
    results = await doc_search_engine.search(query, limit=5)
    return "\n".join(r.title + ": " + r.snippet for r in results)

Dekorator @agent.tool rejestruje funkcję. Pydantic AI odczytuje podpowiedzi typów i docstring funkcji, aby poinformować LLM, co robi narzędzie, jakie argumenty przyjmuje i co zwraca. Bez ręcznego pisania schematów – Twoje podpowiedzi typów SĄ schematem. Tło na temat tego, jak działa wywoływanie funkcji LLM pod maską, znajdziesz w naszym dedykowanym przewodniku.

RunContext: Przekazywanie danych do narzędzi

Tutaj Pydantic AI różni się od innych frameworków. RunContext pozwala przekazywać dane czasu wykonania (połączenia z bazą danych, informacje o użytkowniku, klienty API) do Twoich narzędzi bez używania stanu globalnego.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class SupportDeps:
    customer_id: str
    db_connection: DatabaseConnection

agent = Agent("openai:gpt-4o", deps_type=SupportDeps)

@agent.tool
async def get_order_history(ctx: RunContext[SupportDeps], limit: int = 5) -> str:
    """Fetch recent orders for the current customer."""
    orders = await ctx.deps.db_connection.query(
        "SELECT * FROM orders WHERE customer_id = $1 ORDER BY date DESC LIMIT $2",
        ctx.deps.customer_id, limit
    )
    return format_orders(orders)

ctx.deps daje narzędziu dostęp do wszystkiego, co przekazałeś podczas uruchomienia. Narzędzie nie importuje globalnego połączenia z bazą danych, otrzymuje je. To jest wstrzykiwanie zależności i to właśnie sprawia, że Twoje agenty są testowalne.

Przykład narzędzia ze świata rzeczywistego

@agent.tool
async def run_sql_query(ctx: RunContext[SupportDeps], sql: str) -> str:
    """Run a read-only SQL query against the analytics database.
    Only SELECT queries are allowed."""
    if not sql.strip().upper().startswith("SELECT"):
        return "Error: only SELECT queries are allowed"
    results = await ctx.deps.db_connection.fetch(sql)
    return json.dumps(results, default=str)

Werdykt: Wywoływanie narzędzi w Pydantic AI jest czystsze niż w jakimkolwiek innym frameworku dzięki temu, że podpowiedzi typów wykonują ciężką pracę. Piszesz normalne funkcje Pythona z adnotacjami typów. Framework zajmuje się resztą.

Wstrzykiwanie zależności, funkcja, której brakuje LangChain

Jeśli używałeś Depends w FastAPI, już rozumiesz system DI w Pydantic AI. Jeśli nie, oto krótka wersja: zamiast allow agentowi sięgać po to, czego potrzebuje (globalne połączenia z bazą danych, klienci API, konfiguracja), przekazujesz mu wszystko w czasie wykonania.

Definiowanie zależności

from dataclasses import dataclass
from pydantic_ai import Agent

@dataclass
class AppDeps:
    db: AsyncDatabasePool
    search_client: SearchAPIClient
    current_user: User

agent = Agent(
    "openai:gpt-4o",
    deps_type=AppDeps,
    system_prompt="You are a customer support agent."
)

Używanie zależności w narzędziach

@agent.tool
async def lookup_account(ctx: RunContext[AppDeps]) -> str:
    """Look up the current user's account details."""
    account = await ctx.deps.db.fetchrow(
        "SELECT * FROM accounts WHERE user_id = $1",
        ctx.deps.current_user.id
    )
    return json.dumps(account, default=str)

# Run with real dependencies
result = await agent.run(
    "What's my account status?",
    deps=AppDeps(db=real_db, search_client=real_search, current_user=user)
)

Dlaczego DI czyni Twoje agenty testowalnymi

To jest prawdziwa korzyść. W LangChain przekazywałbyś kontekst przez kwargs łańcucha lub domknięcia, nie ma tam standardowego wzorca. W Pydantic AI zamiana rzeczywistych zależności na atrapy testowe jest trywialna:

# In your test file
from pydantic_ai import Agent
from your_app import agent, AppDeps

async def test_account_lookup():
    mock_deps = AppDeps(
        db=MockDatabase({"user_123": {"status": "active", "plan": "pro"}}),
        search_client=MockSearch(),
        current_user=User(id="user_123")
    )
    result = await agent.run("What's my account status?", deps=mock_deps)
    assert "active" in result.output
    assert "pro" in result.output

Bez monkey-patchingu. Bez mockowania globalnych importów. Po prostu przekazujesz inne deps.

Werdykt: Wstrzykiwanie zależności to powód, dla którego doświadczeni programiści Pythona preferują Pydantic AI. To widoczny wpływ FastAPI.

Dostawcy modeli: OpenAI, Anthropic, Gemini, Ollama

Pydantic AI jest niezależny od modelu. Zmiana dostawcy to zmiana w jednej linii:

# OpenAI
agent = Agent("openai:gpt-4o")

# Anthropic
agent = Agent("anthropic:claude-sonnet-4-20250514")

# Google Gemini
agent = Agent("google-gla:gemini-2.0-flash")

# Local Ollama
agent = Agent("ollama:llama3.1")

Wszystko inne – narzędzia, wyjścia strukturalne, DI – pozostaje identyczne. Twoja logika biznesowa nie zmienia się, gdy zmieniasz modele.

Werdykt: Niezależność od modelu oznacza, że nigdy nie jesteś związany z jednym dostawcą. Zacznij od OpenAI dla wygody, benchmarkuj z Anthropic i używaj Ollama do lokalnego developmentu.

Streaming odpowiedzi

Dla interfejsów czatowych i aplikacji w czasie rzeczywistym streaming jest niezbędny. Pydantic AI obsługuje go, zachowując bezpieczeństwo typów:

from pydantic_ai import Agent
from pydantic import BaseModel

class AnalysisResult(BaseModel):
    summary: str
    sentiment: str
    confidence: float

agent = Agent("openai:gpt-4o", result_type=AnalysisResult)

async def stream_analysis(text: str):
    async with agent.run_stream(f"Analyze this text: {text}") as stream:
        async for partial in stream.stream_structured():
            # partial is a partially-validated AnalysisResult
            print(f"Streaming: {partial}")

        # Final result is fully validated
        result = await stream.get_output()
        print(f"Final: {result.summary} ({result.confidence:.0%} confident)")

Działa to pięknie z StreamingResponse z FastAPI – ten sam ekosystem, te same wzorce. Dokumentacja agentów Pydantic AI obejmuje zaawansowane opcje streamingu, w tym streaming tylko tekstu za pomocą stream_text().

Pydantic AI vs LangGraph vs OpenAI Agents SDK

Skoro tu jesteś, prawdopodobnie pytasz: „czy powinienem używać Pydantic AI czy LangGraph?”. Szczęra odpowiedź: rozwiązują różne problemy i możesz używać obu.

Tabela porównania funkcji

Kiedy wybrać który

Wybierz Pydantic AI, gdy chcesz czysty, bezpieczny typowo kod agenta. Jest idealny do zadań jednoagentowych z narzędziami (boty obsługi klienta, ekstrakcja danych, agenci recenzujący kod) i sytuacji, gdzie testowalność ma znaczenie. Jeśli Twój zespół już używa FastAPI i Pydantic, krzywa uczenia jest niemal płaska.

Wybierz LangGraph, gdy potrzebujesz złożonych, wieloetapowych przepływów pracy z warunkowym rozgałęzieniem, zatwierdzaniem przez człowieka (human-in-the-loop) i zaawansowanym zarządzaniem stanem. LangGraph exceluje w orkiestracji wielu kroków, a nie w jakości pojedynczego agenta. Dla głębszej analizy zobacz nasze pełne porównanie LangGraph vs CrewAI vs OpenAI Agents SDK.

Wybierz OpenAI Agents SDK, gdy w 100% opierasz się na OpenAI, chcesz najprostszą możliwą konfigurację i nie potrzebujesz obsługi wielu dostawców ani DI.

Wzorzec kombinacji

Oto, co rzeczywiście robią doświadczone zespoły: używają Pydantic AI dla pojedynczych agentów (czysty kod, testowalność, typowane wyjścia) oraz LangGraph do orkiestracji między agentami (routing, automaty stanów, logika warunkowa). Nie konkurują ze sobą, są komplementarnymi warstwami.

# Pydantic AI agent -- clean, testable, type-safe
support_agent = Agent("openai:gpt-4o", result_type=SupportResponse, deps_type=SupportDeps)

# LangGraph graph -- orchestrates when to call which agent
graph = StateGraph(SupportState)
graph.add_node("classify", classify_intent)
graph.add_node("support", lambda state: support_agent.run_sync(state["query"]))
graph.add_node("escalate", escalate_to_human)

Werdykt: Wybierz Pydantic AI dla czystego, testowalnego kodu agenta. Wybierz LangGraph dla złożonych, wieloetapowych przepływów pracy. Nie wykluczają się nawzajem.

Testowanie Twoich agentów z TestModel

To sekcja, która odróżnia przewodnik dla początkujących od przewodnika produkcyjnego. Każda rzeczywista baza kodu potrzebuje testów, a testowanie agentów jest notorycznie trudne – wywołania LLM są wolne, drogie i niedeterministyczne. Pydantic AI dostarcza rozwiązanie: TestModel.

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic import BaseModel

class SupportResponse(BaseModel):
    answer: str
    confidence: float
    escalate: bool

agent = Agent("openai:gpt-4o", result_type=SupportResponse)

# In tests: swap the real model for TestModel
def test_support_agent():
    with agent.override(model=TestModel()):
        result = agent.run_sync("I need help with billing")
        # TestModel returns valid structured data matching your result_type
        assert isinstance(result.output, SupportResponse)
        assert isinstance(result.output.confidence, float)
        assert isinstance(result.output.escalate, bool)

TestModel generuje poprawne dane pasujące do Twojego result_type bez wykonywania żadnych wywołań API. Zerowy koszt, deterministyczność, szybkość. Dokumentacja testowania Pydantic AI omawia zaawansowane wzorce, takie jak FunctionModel dla niestandardowych odpowiedzi i capture_run_messages do inspekcji wywołań narzędzi.

Testowanie narzędzi i DI razem

def test_order_lookup_tool():
    # Mock dependencies
    mock_deps = SupportDeps(
        customer_id="test-123",
        db_connection=MockDB(orders=[{"id": "ord-1", "status": "shipped"}])
    )

    with agent.override(model=TestModel()):
        result = agent.run_sync(
            "Where is my order?",
            deps=mock_deps
        )
        assert isinstance(result.output, SupportResponse)

Brak wywołań API. Brak niestabilnych testów. Brak kosztów. Uruchom to w CI/CD obok reszty swojej suite testowej.

To jest największa luka treściowa w całym SERP. Żaden inny przewodnik po Pydantic AI nie omawia testowania. Jeśli budujesz agenty do produkcji, tego właśnie potrzebujesz.

Obserwowalność, integracja z Logfire w 5 minut

Agenty produkcyjne potrzebują obserwowalności AI. Chcesz widzieć każde wywołanie LLM, wywołanie narzędzia, opóźnienie, liczbę tokenów i koszt. Pydantic AI integruje się natywnie z Logfire, platformą obserwowalności zespołu Pydantic (zbudowaną na OpenTelemetry).

import logfire
from pydantic_ai import Agent

logfire.configure()  # Uses LOGFIRE_TOKEN env var
logfire.instrument_pydantic_ai()

agent = Agent("openai:gpt-4o", result_type=MovieReview)
# Every run is now traced automatically
result = agent.run_sync("Review Inception")

Trzy linie. Otrzymujesz pełne ślady pokazujące: wysłany prompt, odpowiedź modelu, wywołania narzędzi (jeśli wystąpiły), udane/nieudane walidacje, ponowne próby, opóźnienie i szacowany koszt. Jeśli Logfire nie jest dla Ciebie, Langfuse to solidna alternatywa open-source z obsługą inżynierii kontekstu do śledzenia ewolucji Twoich promptów.

FAQ

Czym jest Pydantic AI i czym różni się od LangChain?

Pydantic AI to bezpieczny typowo framework agentowy, w którym podpowiedzi typów Pythona sterują walidacją, schematami narzędzi i wstrzykiwaniem zależności. LangChain to większy framework skupiony na łączeniu wywołań LLM w łańcuchy. Kluczowa różnica: Pydantic AI waliduje wyjścia na poziomie frameworku i zapewnia wbudowane wstrzykiwanie zależności dla testowalności, LangChain domyślnie nie robi żadnego z tych rzeczy.

Jak zbudować bezpiecznego typowo agenta AI z Pydantic AI?

Zdefiniuj Pydantic BaseModel dla swojego wyjścia, przekaż go jako result_type do Agent i wywołaj run_sync() lub run(). Agent zwraca zwalidowaną instancję Twojego modelu, a nie surowy ciąg znaków. Zobacz sekcję Wyjścia Strukturalne, aby zobaczyć kompletne przykłady.

Czy powinienem używać Pydantic AI czy LangGraph dla agentów produkcyjnych?

Używaj Pydantic AI dla pojedynczych agentów, gdzie liczy się bezpieczeństwo typów, testowalność i czysty kod. Używaj LangGraph do orkiestracji złożonych, wieloetapowych przepływów pracy z warunkowym routingiem. Wiele zespołów używa obu, umieszczając agentów Pydantic AI w warstwie orkiestracji LangGraph.

Jak Pydantic AI obsługuje wywoływanie narzędzi i wstrzykiwanie zależności?

Odekoruj funkcję za pomocą @agent.tool, a Pydantic AI odczyta jej podpowiedzi typów, aby wygenerować schemat narzędzia. Dla DI ustaw deps_type w Agent i akceptuj RunContext[TwojeDeps] w narzędziach. Zależności czasu wykonania (połączenia z DB, klienci API) płyną bez stanu globalnego.

Jak dodać streaming do agenta Pydantic AI?

Użyj agent.run_stream() zamiast agent.run(). Zwraca asynchroniczny menedżer kontekstu, który yielduje częściowe wyniki przez stream_structured() lub stream_text(). Końcowy wynik jest nadal w pełni walidowany względem Twojego result_type.

Czy Pydantic AI jest gotowy do produkcji w 2026 roku?

Tak. Wersja 1.0 została wydana we wrześniu 2025 z zobowiązaniem do stabilności API. Jest wspierana przez zespół Pydantic (najczęściej pobieraną bibliotekę Pythona do walidacji danych) i obecnie znajduje się w wersji v1.74.0 z regularnymi aktualizacjami.

Czy mogę używać Pydantic AI z Ollama i modelami lokalnymi?

Tak. Użyj Agent("ollama:llama3.1") i upewnij się, że Ollama działa lokalnie. Zainstaluj dodatkowy provider ollama: pip install "pydantic-ai[ollama]". Wyjścia strukturalne i narzędzia działają tak samo jak z dostawcami chmurowymi.

Jak testować agenty Pydantic AI?

Użyj TestModel, mockowanego modelu, który generuje poprawne dane strukturalne pasujące do Twojego result_type bez wywołań API. Otocz swój test za pomocą agent.override(model=TestModel()) i uruchom asercje na wyjściu. Zobacz sekcję Testowanie, aby zobaczyć kompletne przykłady pytest.

Czy Pydantic AI współpracuje z FastAPI?

Idealnie. Dzielą tę samą filozofię wstrzykiwania zależności i są budowane przez ten sam zespół. Możesz używać agentów Pydantic AI w endpointach FastAPI, dzielić między nimi typy zależności i streamować odpowiedzi agentów przez StreamingResponse.

Jaka jest różnica między Pydantic AI a OpenAI Agents SDK?

Pydantic AI jest niezależny od modelu (działa z OpenAI, Anthropic, Gemini, Ollama itp.), posiada wstrzykiwanie zależności, TestModel do testowania i walidację Pydantic. OpenAI Agents SDK jest prostszy, ale ograniczony do modeli OpenAI i brak mu DI oraz wbudowanego testowania. Wybierz Pydantic AI dla elastyczności; wybierz OpenAI Agents SDK dla najprostszej możliwej konfiguracji tylko dla OpenAI.

Kluczowe wnioski i kolejne kroki

Zacznij od małego agenta z wyjściami strukturalnymi. Dodaj narzędzie. Dodaj zależności. Napisz test z TestModel. To jest ścieżka produkcyjna i masz teraz wszystko, czego potrzebujesz, aby nią podążać.

Oficjalna dokumentacja Pydantic AI i repozytorium GitHub są doskonałe do pogłębiania wiedzy. Framework rozwija się szybko, więc warto dodać changelog do zakładek.

Źródła

• Pydantic AI, Oficjalna Dokumentacja
• Dokumentacja Zależności Pydantic AI
• Dokumentacja Testowania Pydantic AI
• Ogłoszenie Wydania Pydantic AI v1
• Obserwowalność AI Logfire
• pydantic/pydantic-ai, Repozytorium GitHub