Pydantic AI: podejście type-first do agentów w Pythonie

Pydantic AI to framework open source do budowy agentów (licencja MIT) firmy Pydantic Inc. (Wielka Brytania), przeznaczony dla Pythona od wersji 3.11. Przenosi znaną z walidacji danych bibliotekę Pydantic na pracę z dużymi modelami językowymi (large language models): agenci zwracają ustrukturyzowane wyniki ze sprawdzonymi typami, zgodne ze zdefiniowanymi modelami Pydantic, zamiast swobodnie sformułowanych tekstów. Do tego dochodzą wstrzykiwanie zależności i integracja niezależna od modelu. Deklarowanym celem projektowym jest jakość inżynierska i gotowość produkcyjna, a nie najszybsza droga do dema.

• Co to jest: framework type-first dla Pythona do budowy agentów AI z wynikami walidowanymi przez modele Pydantic.
• Dla kogo: zespoły backendowe Pythona z dyscypliną type checkingu, które stawiają niezawodność i jakość produkcyjną ponad time-to-demo.
• Kiedy nie: gdy wymagany jest .NET, potrzebne jest low-code albo głównym wymaganiem są złożone orkiestracje wieloagentowe.

Dlaczego podejście „type-first” jest kluczowe

Większość błędów agentów na produkcji powstaje na styku wyniku zwracanego przez LLM i dalszego kodu: model zwraca nieco inny JSON, brakuje pola, typ danych się nie zgadza, a pipeline wysypuje się dopiero trzy kroki później. Właśnie tu wkracza Pydantic AI. Korzysta z tej samej warstwy walidacji, która w ekosystemie Pythona i tak uchodzi za standard de facto: m.in. OpenAI SDK, Google ADK, Anthropic SDK, LangChain, LlamaIndex i CrewAI opierają się na Pydantic Validation. Pydantic AI czyni tę walidację centralnym kontraktem między agentem a aplikacją.

W praktyce zespół definiuje oczekiwany wynik jako model Pydantic. Agent dostaje polecenie, by zwrócić dokładnie tę strukturę; jeśli odpowiedź modelu od niej odbiega, Pydantic waliduje wynik, zwraca typowane błędy i umożliwia kontrolowane ponowienie próby. Efektem jest bezpieczeństwo typów end-to-end: od definicji narzędzi przez wywołanie modelu aż po zwalidowaną wartość zwracaną type checker (a więc i IDE) zna struktury danych.

Cztery filary

Ustrukturyzowane, zwalidowane wyniki. Zamiast parsować stringi, deklarujesz docelowy schemat jako model Pydantic. Agent na pewno zwróci obiekt zgodny z tym schematem albo czytelny błąd walidacji.

Wstrzykiwanie zależności. Zależności takie jak połączenia z bazą danych, klienty HTTP, konfiguracja czy kontekst uprawnień są wstrzykiwane do agenta w sposób typowany. Oddziela to logikę biznesową od definicji agenta i ułatwia testy jednostkowe z mockami, czyli wzorzec, który zespoły backendowe Pythona znają z frameworków takich jak FastAPI.

Niezależność od modelu. Pydantic AI obsługuje wszystkich dużych dostawców, w tym OpenAI GPT, Anthropic Claude, Google Gemini i Mistral, a także modele lokalne przez Ollama. Dzięki temu możesz podłączyć również modele niemieckie i modele do zastosowań, w których kluczowa jest suwerenność, a później zmienić dostawcę bez przepisywania logiki agenta.

Definicja narzędzi z bezpieczeństwem typów. Narzędzia to typowane funkcje Pythona; ich sygnatury i schematy parametrów framework wyprowadza z adnotacji typów. Dzięki temu warstwa narzędzi jest sprawdzana równie rygorystycznie jak wynik.

Dodatkowo Pydantic AI oferuje Monty, bezpieczny sandbox dla Pythona, i obsługuje standardy interoperacyjności MCP oraz A2A. MCP jest zawarte w pakiecie pydantic-ai (w pydantic-ai-slim przez extra mcp), a integracja odbywa się przez MCPToolset. Wersja 2 jest stabilna od 23 czerwca 2026 r. W tym wydaniu Pydantic przeniósł A2A do osobnego pakietu fasta2a, instalowanego oddzielnie; dawne extras a2a i fastmcp od tego czasu nie istnieją. W zakresie obserwowalności Pydantic Logfire to własne, zgodne z OpenTelemetry rozwiązanie twórców frameworka, które od marca 2025 r. oferuje region UE oraz wariant self-hosted.

Pydantic AI na tle innych frameworków

Pydantic AI pozycjonuje się wyraźnie jako rozwiązanie code-first, skoncentrowane raczej na pojedynczym agencie. W porównaniu z dużymi frameworkami wieloagentowymi jego siłą nie jest orkiestracja dziesiątek agentów, lecz niezawodność każdej pojedynczej interakcji.

Mocne strony w skrócie: bezpieczeństwo typów end-to-end, pełna niezależność od dostawcy, licencja MIT, region UE w Logfire i jakość inżynierska jako wprost deklarowany cel projektowy. Uczciwie nazwane słabe strony: tylko Python, krótsza obecność na rynku, mniej gotowych wzorców wieloagentowych i pewna rozwlekłość generyków, którą przyznaje sam założyciel, Samuel Colvin. Pod względem dostępności specjalistów i dojrzałości ekosystemu Pydantic AI plasuje się w regionie DACH (Niemcy, Austria, Szwajcaria) na średnim poziomie, przy niskiej lub średniej dostępności freelancerów; za to razem z LangGraph v1, CrewAI v1 i Microsoft Agent Framework 1.0 należy do frameworków uznawanych za gotowe do produkcji.

Kiedy Pydantic AI się sprawdzi, a kiedy nie

Krótki przewodnik decyzyjny:

• Sprawdzi się, gdy: bezpieczeństwo typów, Python i dyscyplina inżynierska są ważniejsze niż najszybsze demo; Pydantic jest już w stacku; potrzebna jest pełna niezależność od dostawcy; wymagana jest ścisła suwerenność w Europie dzięki self-hostingowi (np. na STACKIT, IONOS lub OVHcloud).
• Raczej się nie sprawdzi, gdy: .NET/C# jest obowiązkowy (wtedy Microsoft Agent Framework), citizen developerzy w zespole potrzebują low-code (wtedy n8n) albo na pierwszym planie jest szybkie prototypowanie wieloagentowe z modelem ról/crew (wtedy CrewAI).

Krótki przykład: zwalidowany wynik w praktyce

Załóżmy, że agencja buduje agenta, który wyodrębnia ustrukturyzowane dane z przychodzącego e-maila od leada. Kontrakt definiuje się jako model Pydantic:

```python
from pydantic import BaseModel
from pydantic_ai import Agent

class Lead(BaseModel):
firma: str
budget_eur: int # musi być liczbą całkowitą
priorytet: int # od 1 do 5
nastepny_krok: str

agent = Agent(
"anthropic:claude-...", # model wymienny, niezależny od dostawcy
output_type=Lead, # wymusza zwalidowaną strukturę
)

wynik = agent.run_sync("Wyodrębnij dane z tego maila: ...")
lead = wynik.output # na pewno typu Lead
```

Kluczowe jest to, że lead.budget_eur na pewno jest wartością typu int, a nie stringiem „około 50 000 euro”. Jeśli model zwróci coś niepasującego, Pydantic waliduje wynik, a agent może uruchomić typowane ponowienie, zamiast zapisywać błędne dane w CRM. W pipelinie przetwarzającym 1000 leadów miesięcznie nakład pracy przesuwa się więc z późniejszej obsługi błędów i ręcznych poprawek na jasny obraz błędów, wychwytywanych już na interfejsie. Na tym właśnie polega różnica między demem a systemem produkcyjnym.

Podsumowanie dla agencji i firm B2B

Dla agencji marketingowych i zespołów B2B w Europie Pydantic AI jest właściwym wyborem wtedy, gdy agenci AI muszą dostarczać wiarygodne dane gotowe do dalszego przetwarzania, na przykład do kwalifikacji leadów, strukturyzowania treści lub integracji z istniejącymi systemami. Połączenie licencji MIT, pełnej niezależności od dostawcy, możliwości self-hostingu i regionu UE w Logfire sprawia, że framework jest interesujący także dla projektów, w których liczą się suwerenność i zgodność z AI Act: tracing zgodny z OpenTelemetry wspiera wymaganą identyfikowalność. Jeśli masz zespół Pythona z dyscypliną type checkingu, Pydantic AI daje Ci narzędzie, które stawia niezawodność ponad efektowność. Blck Alpaca pomoże Ci w wyborze, architekturze i self-hostingu odpowiedniej platformy agentowej dla Twojego stacku.