Pydantic AI bemutató: típusos Python-ügynökök ellenőrzött kimenettel

A Pydantic AI a Pydantic csapatának Python-ügynökkeretrendszere, a Pydantic pedig az adatvalidációs könyvtár. A függőségek, az eszközök és az eredmények hétköznapi Python-típusok, a modell minden strukturált válaszát pedig ellenőrzik, mielőtt a kódod megkapja. Az ítélet előre – típusos ügynökökhöz Python-szolgáltatásokon belül érdemes, ahol a csapat amúgy is Pydantic-modellekben gondolkodik. Hagyd ki, ha a csapatod TypeScriptben dolgozik, vizuális építőt akar a munkafolyamatok fő tervezőeszközének, vagy nem tud lépést tartani az API-változásokkal a kiadások között.

Mi ez

A jelenlegi kiadás a 2.55.0, amelyet 2026. október 9-én tettek közzé a PyPI-n. MIT-licencű, Python 3.11 vagy újabb kell hozzá, és a GitHubon körülbelül 20 500 csillaga van. A projekt így írja le magát: „How Python does AI“ – ügynökök, valós idejű hang, képgenerálás és beágyazások, végig típusosan. A 2.0-s ág 2026. június 23-án vált stabillá, ezért a régebbi útmutatók még az 1.x API-t írhatják le.

• Típusos függőségek. A `deps_type` megadja, mire van szüksége az ügynöknek, és minden futás egy példányt kap a `deps=` paraméteren keresztül.
• Ellenőrzött kimenet. Az `output_type` Pydantic-modellt, uniót vagy típuslistát fogad el. A modell alapértelmezetten eszközhívással tölti ki.
• Nagyjából két tucat szolgáltató. Egy előtag, például `openai:`, `anthropic:` vagy `google:` választja ki a szolgáltatót. A szolgáltatólista lefedi a Groqot, a Mistralt, az Ollamát és az OpenRoutert is, plusz bármely OpenAI-kompatibilis végpontot.
• Capability-k és tartós futtatások. A capability-k eszközöket, hookokat, utasításokat és modellbeállításokat csomagolnak egyetlen újrafelhasználható egységbe. A tartós futtatások a Temporal, a DBOS, a Prefect, a Restate és az AWS Lambda révén csatlakoznak.

Hogyan működik

Az ügynökfutás egy ciklus, a végén ellenőrzéssel. Az ügynök az utasításokat, az üzenettörténetet és az eszközsémákat küldi a modellnek. Amikor a modell eszközt hív, a Pydantic AI lefuttatja a Python-függvényedet a típusos kontextussal, és az eredményt visszaadja a modellnek. Amikor a modell abbahagyja az eszközhívásokat, a kimenetét az `output_type` ellen ellenőrzi. A sikertelen ellenőrzés újrapróbálásként visszamegy a modellhez, az alapértelmezett keret a kimeneti újrapróbálásokra pedig: egy.

A függőségek a függvényeidhez jutnak, sosem a modellhez. Egy adatbázis-pool vagy egy HTTP-session az ügynök mellett állhat anélkül, hogy megjelenne egy promptban. A modell csak az utasításokat, az eszközsémákat és az üzeneteket látja, és ezt a határt érdemes szándékosan megtervezni.

Első lépések

Telepítsd a `uv add pydantic-ai` vagy a `pip install pydantic-ai` paranccsal, majd add meg a szolgáltatód által várt hitelesítő adatokat. Az alábbi példa egy ügyfélszolgálati osztályozó ügynök. Egy típusos függőséget kap, meghív egy eszközt, és egy ellenőrzött objektumot ad vissza.

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

from myshop.orders import OrderService


@dataclass
class SupportDeps:
    customer_id: int
    orders: OrderService  # your own client, injected per run


class Triage(BaseModel):
    category: Literal['refund', 'shipping', 'other']
    risk: int = Field(ge=0, le=10, description='How urgently a person should review this')
    reply: str


support = Agent(
    'openai:gpt-6-sol',
    deps_type=SupportDeps,
    output_type=Triage,
    instructions='Triage the message. Check the order before you answer.',
)


@support.tool
async def latest_order(ctx: RunContext[SupportDeps]) -> str:
    '''Return the status of the most recent order.'''
    return await ctx.deps.orders.latest_status(ctx.deps.customer_id)


result = support.run_sync(
    'Where is my parcel?',
    deps=SupportDeps(customer_id=42, orders=OrderService()),
)
print(result.output.category, result.output.risk)

A kódban két rész végzi a munkát. A `Triage` osztály egyszerre a modellnek küldött séma és az a típus, amelyet a kódod kap. A megengedett kategóriákon vagy a 0–10-es kockázati tartományon kívüli válasz újrapróbálódik, és ha így is elbukik, hibát dob, ahelyett hogy elérné a kódodat. A `RunContext[SupportDeps]` annotáció az eszköznek a klienseden keresztül típusos nézetet ad, így a szerkesztő minden használt attribútumot ellenőrizni tud.

Típusos függőségek és ellenőrzött kimenet

A függőségeket vezetném be elsőként. A `deps_type` deklarálja a típust, a `RunContext[Deps]` hozzáférést ad az eszközöknek, utasításoknak és kimeneti validátoroknak a `ctx.deps`-hez, a teszt pedig az `agent.override(deps=...)` segítségével a valódi klienst fake-re cserélheti. A bekötés a konstruktorban és a futtatási hívásban marad, nem modulszintű globális változókban, ami könnyen tesztelhetővé teszi az ügynököt.

A kimenetnél látszik igazán, mit ér a keretrendszer. Alapértelmezetten a modell eszközhívási felületén keresztül ad strukturált adatot, és a típusok uniójából tagonként egy kimeneti eszköz lesz. A `TextOutput` és a `PromptedOutput` jelölők szöveges kimenetre váltanak olyan modelleknél, amelyek eszközhívása megbízhatatlan. A `ToolOutput` egy kimeneti eszköznek saját újrapróbálási keretet ad, így az összetettebb típus több kísérletet kaphat, mint az egyszerű.

• `ModelRetry` lehetővé teszi, hogy egy eszköz vagy kimeneti függvény elutasítson egy értéket, és megmondja a modellnek, mit változtasson.
• `@agent.output_validator` a feldolgozás után futtatja a saját ellenőrzéseidet, például hogy a válaszban szereplő rendelésszám létezik-e.
• `Agent(retries={'output': N})` megemeli a kimeneti újrapróbálási keretet az egész ügynökre. Az alapérték egy.
• `ToolOutput(Fruit, max_retries=2)` egy kimeneti típusnak saját újrapróbálási számot ad.

A tesztelésnél térül meg a tervezés. A `TestModel` minden eszközt meghív, és szerkezetileg érvényes választ ad, a `FunctionModel` lehetővé teszi, hogy a teszt előre megadja a modell válaszát, az `ALLOW_MODEL_REQUESTS=False` pedig megakadályozza, hogy a CI véletlenül valódi szolgáltatókhoz forduljon. A támogatási folyamat unit-tesztje ezután sem API-kulcsot, sem hálózatot nem igényel.

Nyomkövetés és tartós futtatások

A nyomkövetés opcionális. Indításkor hívd meg a `logfire.configure()` és a `logfire.instrument_pydantic_ai()` függvényt, és minden futás, modellválasz és eszközhívás OpenTelemetry-spanné válik, amely a generatív MI szemantikai konvencióit követi. A Logfire SDK ugyanezeket az adatokat bármely OpenTelemetry-backendbe küldheti, ami számít, ha a telemetriának olyan rendszerben kell maradnia, amelyet a csapat már üzemeltet. Az átfogóbb képet itt találod: ügynök-observability OpenTelemetry-jel.

A tartós végrehajtás a második funkció, amit érdemes megérteni. A dokumentáció nyolc motort sorol fel. A Temporal, a DBOS, a Prefect, a Restate és az AWS Lambda a szállítóikkal közösen karbantartott, a Kitaru, az Apache Airflow és az Absurd pedig külső integrációként érkezik. A 2.x-ben durability-capabilityt csatolsz az ügynökhöz. A README példája a `TemporalDurability()`-t egy Temporal-workflow-ban adja hozzá egy ügynök capability-jeihez.

Költség, hosztolás és adatvédelem

2026 októberi állapot szerint a könyvtár futtatása nem kerül semmibe. A licenc a kódot fedi le, így a számlák három helyről jönnek: a szolgáltatód modell-tokenjei, a Logfire-rekordok, ha Logfire-t használsz, és egy tartós motor infrastruktúrája, ha bevezetsz egyet. A Logfire-csomagok mutatják meg, hogyan néz ki a második számla.

A Logfire rekordokat számláz: logokat, spaneket és metrikákat. A havonta benne lévő 10 milliót a csomag kerete fedezi, e fölött a Team és a Growth millionként 2 $-t kér. Egy csapat, amely havi 30 millió rekordot küld, 49 $-t fizet, plusz 40 $-t a további 20 millióért, azaz nagyjából 89 $-t, a modell-tokenek előtt. Az AI-átjáró a beépített szolgáltatóknál 5 százalékos felárat számol fel, míg legfeljebb három saját szolgáltatói kulcs felár nélkül megy át.

A könyvtár saját üzemeltetése az alapértelmezett, hiszen ez csak kód a saját környezetedben. A Logfire Enterprise szintje egy saját Kubernetes-fürtön futó, önállóan üzemeltethető változatot is ad. Az adatvédelem szempontjából három adatáramlás számít. A modellszolgáltató promptokat és eszköz-eredményeket kap, ezért az ő adatfeldolgozási feltételei és régiója az első. A Logfire minden exportált spant megkap, ezért a promptokat és a completionöket ott zárd ki, ahol nincs rájuk szükség. A Pydantic ezenfelül Data Processing Addendumot kínál a GDPR-hez, kérésre SOC 2 Type 2 jelentést és közzétett alfeldolgozói listát.

A régió minden csomagnál olyan beállítás, amit érdemes ellenőrizni. Az árazási táblázat minden hosztolt csomagnál, a Personaltól az Enterprise Cloudig, pipát tesz az EU- vagy USA-adatrégióra. Az Enterprise Dedicated bármely Google Cloud-régiót kínál, a saját üzemeltetés pedig ott tartja az adatokat, ahol futtatod. Az árazási oldal nem írja le, melyik régió az alapértelmezett egy új projektnél, ezért ezt ellenőrizd, mielőtt személyes adatot küldesz. A modell-API-k adatrezidenciájának szélesebb kérdését külön cikk tárgyalja.

Hol nem elég jó

A fő kockázat a változás – és a changelog ezt nyíltan írja. A 2.0-s ág hét bétán ment keresztül 2026. május 20. és június 10. között, mielőtt a stabil kiadás június 23-án megjelent. A nem visszafelé kompatibilis változások (breaking change-ek) két csoportba tartoznak: olyan eltávolítások, amelyeket a V1 elavulási figyelmeztetései nem tudtak bejelenteni, és olyan változások, amelyekre a V1 figyelmeztetett. Az eltávolított elemek között van az Outlines-integráció és a kiegészítői, a `ModelProfile` pedig dataclassból TypedDictté alakult. Az átállás valódi feladat, nem verziószám-emelés.

A kisebb kiadások is gyakoriak. A 2.51.0 2026. szeptember 25-én jelent meg, a 2.55.0 október 9-én, így egy lazán rögzített projektben két hét alatt több változás is érkezik. A verziókezelési szabályzat nem ígér szándékos breaking change-eket a kisebb kiadásokban, de a béta modulban lévő funkciók kifejezetten instabilak, és olyan módon változhatnak, amely a meglévő kódot megtöri. Minden béta modulból származó importot rögzített függőségként kezelj.

A biztonsági közleményeket is figyeld. A 2.52.0 kiadás javított egy CPU- és memóriaproblémát a helyi `web_fetch` eszközben, ahol a mélyen egymásba ágyazott HTML túlzott erőforrást emészthetett. A szolgáltató saját webes letöltését ez nem érintette. Végül – ez egy Python-könyvtár. A TypeScriptben ügynököket építő csapatoknak más keretrendszer kell, a tartós motorok pedig olyan infrastruktúrát hoznak, amelyet valakinek üzemeltetnie vagy fizetnie kell.

Összegzés

A Pydantic AI az alapértelmezett választásom olyan Python-csapatnak, amely már Pydantic-cal modellezi az adatait, és típusos, tesztelhető ügynököket szeretne, amelyeket könnyű a szolgáltatás többi része mellett futtatni. Rossz választás TypeScript-kódbázishoz, olyan csapatnak, amely vizuális gráfszerkesztőt szeretne fő tervezőeszközként, és bármelyik csapatnak, amely nem bírja el a kiadások közötti API-változásokat. Ezekben az esetekben az alábbi alternatívák jobban illenek.

1. Válaszd a Pydantic AI-t ha a szolgáltatásaid Pythonban futnak, az adataid már Pydantic-modellekben vannak, és típusos eszközöket meg ellenőrzött kimenetet szeretnél.
2. Válaszd az OpenAI Agents SDK-t, ha elkötelezted magad az OpenAI mellett, és nagyon kevés primitívet szeretnél. Kapcsold ki a nyomkövetést, vagy adj hozzá saját processzort, mielőtt valódi ügyféladatok áramlanának rajta keresztül.
3. Válaszd a LangGraph-ot, ha a munkafolyamat a termék: explicit állapot, ellenőrzőpontok és elnevezett jóváhagyási lépések. Több kódot írsz, és minden átmenetet te irányítasz.

Források

• Pydantic AI dokumentáció
• pydantic-ai 2.55.0 a PyPI-n (2026. október 9.)
• pydantic/pydantic-ai a GitHubon: licenc, csillagok és README
• Pydantic AI kiadási jegyzetek: 2.51.0–2.55.0 és a 2.52.0 biztonsági javítás
• Pydantic AI verziókezelési szabályzat
• Pydantic AI frissítési útmutató: a V2-béták és a stabil kiadás
• Pydantic AI output: eszközkimenet, újrapróbálások és kimeneti validátorok
• Pydantic AI függőségek és RunContext
• Pydantic AI modellek és szolgáltatók
• Pydantic AI egységtesztelés TestModel és FunctionModel használatával
• Pydantic AI áttekintés a tartós végrehajtásról
• Pydantic Logfire: megfigyelhetőség a Pydantic AI-hoz
• Pydantic Logfire árazás
• Pydantic: biztonság és megfelelőség
• OpenAI Agents SDK dokumentáció
• OpenAI Agents SDK nyomkövetés
• openai/openai-agents-python a GitHubon
• openai-agents 0.23.1 a PyPI-n
• langchain-ai/langgraph a GitHubon
• langgraph 1.2.14 a PyPI-n
• LangGraph áttekintés
• LangGraph megszakítások (interrupts)