PydanticAI

1. Przegląd koncepcji i problem systemowy

Pierwsza fala bibliotek do pracy z modelami językowymi powstawała w erze szybkiego prototypowania: opierała się na zagnieżdżonych klasach dynamicznych, słownikach bez typów, niewidocznych promptach i skomplikowanym dziedziczeniu. W produkcyjnym backendzie prowadziło to do katastrofalnych trudności:

1. Brak autouzupełniania i refaktoryzacji: IDE nie rozumie, jakie pola zwraca agent, a zmiana nazwy jednej właściwości łamie kod w runtime bez ostrzeżeń.
2. Problemy z testowalnością: Niemożliwe jest izolowanie logiki agenta od usług zewnętrznych lub podmiana bazy danych na testowy mock ze względu na brak normalnego Dependency Injection.
3. Niezawodna obsługa błędów struktury: Modele często pomijają obowiązkowe pola lub mylą typy (np. string zamiast liczby), co prowadzi do awarii API.

PydanticAI, stworzony przez Samuela Colvina (autora Pydantic), przywraca rozwój agentów na ścieżkę klasycznej, czystej inżynierii oprogramowania: jest to type-safe, minimalistyczny i szybki framework zbudowany na standardzie Pydantic v2.

2. Taksonomia architektoniczna i model mentalny

Architektura PydanticAI opiera się na czterech filarach koncepcyjnych:

• 1. Parametryzowany agent (Agent[Deps, ResultType]): Agent jest jawnie typizowany dwoma parametrami: typem zależności kontekstowych (Deps), których potrzebuje do działania, oraz typem końcowego wyniku (ResultType). Jeśli wynikiem jest model Pydantic, agent gwarantuje zwalidowaną instancję klasy.
• 2. Kontekst wykonania i DI (RunContext[Deps]): Mechanizm wstrzykiwania zależności. Każdy tool i dynamiczny prompt ma dostęp do ctx.deps, gdzie przechowywane są aktywne połączenia z bazą danych, konfiguracja lub informacje o uprawnieniach użytkownika.
• 3. Typizowane narzędzia (@agent.tool): Funkcje Pythona, których argumenty są automatycznie translowane do JSON Schema dla LLM. Opisy argumentów pobierane są z Type Hints i docstrings.
• 4. Dynamiczne prompty systemowe (@agent.system_prompt): Asynchroniczne funkcje tworzące instrukcję systemową „w locie” na podstawie przekazanych zależności (np. wstawiając aktualne saldo użytkownika czy strefę czasową).

3. Pipeline techniczny i mechanika wewnętrzna

Cykl życia zapytania w PydanticAI:

1. Instantiation & Context Binding (Budowanie kontekstu): Przy wywołaniu agent.run(prompt, deps=my_deps) framework inicjalizuje RunContext i rozwiązuje wszystkie funkcje oznaczone dekoratorem @agent.system_prompt.
2. Schema Generation & Model Inference (Wywołanie modelu): Typy argumentów narzędzi oraz finalny ResultType konwertowane są do surowych schematów JSON przez silnik Pydantic Core (napisany w Rust, zapewniający mikrosekundową prędkość).
3. Tool Invocation with Self-Correction (Walidacja i korekta): Gdy model zwraca wywołanie toola, argumenty wejściowe są przepuszczane przez walidator Pydantic. Jeśli walidacja nie przejdzie (np. przekazano liczbę ujemną tam, gdzie oczekiwano PositiveInt), PydanticAI nie rzuca wyjątku, lecz automatycznie wysyła do modelu komunikat: „Błąd walidacji pola X: oczekiwano wartości > 0. Spróbuj ponownie”.
4. Structured Output Serialization & Streaming (Zwrot wyniku): Finalna odpowiedź deserializowana jest do docelowego obiektu Pythona. Wspierana jest metoda run_stream(), pozwalająca transmitować częściowo sformułowane pola obiektu klientowi w czasie rzeczywistym.

4. Praktyczne scenariusze inżynierskie w produkcji

01. Natywne agenty wewnątrz FastAPI

Wspólne wykorzystanie modeli: ta sama schema InvoiceExtractionResponse służy jako wyjściowa schema PydanticAI, jako response_model w endpointcie FastAPI oraz do automatycznej generacji typu klienta TypeScript przez OpenAPI.

02. Bezpieczna praca z transakcjami bazy danych

Poprzez RunContext do narzędzi przekazywana jest sesja transakcyjna AsyncSession SQLAlchemy. Agent może wykonywać sprawdzenia i zapisywać dane. Jeśli na etapie końcowym wystąpi błąd, zewnętrzny menedżer kontekstu cofa transakcję, zapobiegając zapisaniu półsurowych danych.

03. Streaming interfejsów strukturalnych (Generative UI)

Agent generuje dynamiczny dashboard. Dzięki wsparciu dla walidacji streamingu w PydanticAI frontend może renderować wykresy i karty jeszcze przed zakończeniem formowania pełnego dokumentu JSON przez model.

5. Pułapki, typowe błędy i bezpieczeństwo

• Brak opisów pól (Field(description=...)): Model buduje wywołanie, opierając się wyłącznie na nazwach i opisach pól. Jeśli pole jest nazwane niejednoznacznie (np. status: int) i brakuje opisu, model regularnie będzie halucynował nieprawidłowe wartości.
• Wyczerpanie prób korekty błędów (Max Retries Exceeded): Jeśli schema jest zbyt złożona, model może wyczerpać limit retries=3, próbując dopasować odpowiedź do walidatora, co doprowadzi do awarii zapytania. Uproszczaj schematy lub dekomponuj je na podzadania.
• Wyciek cyklu życia zasobów w Deps: Upewnij się, że obiekty przekazywane do deps (pule połączeń, klienci HTTP) są prawidłowo zamykane po zakończeniu pracy agenta (poprzez async with).