Pydantic AI: Průvodce pro produkci (za hranicemi Hello World)

Pydantic AI: Průvodce pro produkci (za hranicemi Hello World)

Surové výstupy z LLM rozbíjejí aplikace. Požádáte o JSON, dostanete markdown. Požádáte o číslo mezi 1 a 10, dostanete „Jistě! Zde je číslo: sedm.“ Pokud jste s API LLM vytvořili něco reálného, pravděpodobně jste psali obranný kód pro parsování, který vás přiměl zapochybovat o své kariérní volbě. Pydantic AI toto řeší – je to typově bezpečný framework pro agenty vytvořený stejným týmem, který stojí za Pydantic a FastAPI. Představte si to jako „FastAPI pro AI agenty“: definujete, co chcete, pomocí typových nápověd Pythonu a framework se postará o validaci, opakované pokusy a volání nástrojů.

Tento průvodce Pydantic AI je určen vývojářům, kteří již provedli svůj první hovor s LLM a chtějí zavést produkční vzory: strukturované výstupy, které se nerozbijí, injektáž závislostí pro testovatelné agenty a reálné nástroje nad rámec API pro počasí. Na konci budete mít funkční agenty s nástroji, DI, streamováním a testy.

Pydantic AI v rychlosti

Nejvýraznějšími funkcemi jsou strukturované výstupy (validované pomocí modelů Pydantic), injektáž závislostí (jako Depends ve FastAPI) a TestModel (mock LLM pro testování bez volání API). Pokud přicházíte z LangChainu a ptáte se „existuje něco čistšího?“, pravděpodobně je to ono.

Instalace a první 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-..."

Váš první agent v 5 řádcích:

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 je vše. Agent obaluje model, run_sync odešle prompt a vrátí výsledek. result.output je zde obyčejný řetězec, ale to se brzy změní.

Strukturované výstupy, důvod existence Pydantic AI

Toto je klíčová funkce. Místo toho, abyste od LLM dostali řetězec a doufali, že jde o platný JSON, definujete model Pydantic a agent vrátí validovaný objekt Pythonu.

Předtím: Surový výstup 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.

Poté: Strukturovaně s 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)

Rozdíl je jako den a noc. result.output je skutečný objekt MovieReview. Pokud LLM vrátí rating: "eight" místo rating: 8, validace Pydantic to zachytí. Pro hlubší pohled na to, jak to funguje napříč různými poskytovateli, se podívejte na naši příručku o strukturovaných výstupech napříč poskytovateli LLM.

Co se stane, když validace selže

Zde je část, kterou žádný jiný tutoriál neukazuje: co se stane, když LLM udělá chybu?

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")

Tato smyčka opakování s zpětnou vazbou je killer feature Pydantic AI. LLM se učí ze svých vlastních chyb při validaci. Nepíšete logiku pro opakování, framework se o ni postará.

Verdikt: Strukturované výstupy jsou jediným nejlepším důvodem k používání Pydantic AI namísto surových volání API. Pokud ručně parsujete JSON z LLM, přestaňte.

Nástroje a volání funkcí

Nástroje umožňují vašemu agentovi volat funkce Pythonu pro získání reálných dat. Místo toho, aby LLM halucinoval fakta, může dotazovat vaši databázi, prohledávat vaši dokumentaci nebo volat API.

Registrace nástroje

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)

Dekorátor @agent.tool registruje funkci. Pydantic AI čte typové nápovědy a docstring funkce, aby řekl LLM, co nástroj dělá, jaké argumenty přijímá a co vrací. Žádné ruční psaní schémat, vaše typové nápovědy JSOU schématem. Pro pozadí o tom, jak volání funkcí LLM funguje pod kapotou, máme věnovaný průvodce.

RunContext: Předávání dat do nástrojů

Zde se Pydantic AI liší od ostatních frameworků. RunContext vám umožňuje předávat runtime data (připojení k databázi, informace o uživateli, API klienty) do vašich nástrojů bez globálního stavu.

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 dává nástroji přístup ke všemu, co jste předali za běhu. Nástroj neimportuje globální připojení k databázi, dostane ho. Toto je injektáž závislostí a díky ní jsou vaši agenti testovatelní.

Příklad reálného nástroje

@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)

Verdikt: Volání nástrojů v Pydantic AI je čistší než v jakémkoli jiném frameworku díky tomu, že typové nápovědy dělají těžkou práci. Píšete běžné funkce Pythonu s typovými anotacemi. Framework si zbytek vyřeší sám.

Injektáž závislostí, funkce, kterou si LangGraph přeje mít

Pokud jste používali Depends ve FastAPI, již chápete systém DI v Pydantic AI. Pokud ne, zde je krátká verze: místo toho, aby váš agent sahal po tom, co potřebuje (globální připojení k databázi, API klienty, konfigurace), mu vše předáte za běhu.

Definice závislostí

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."
)

Používání závislostí v nástrojích

@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)
)

Proč DI činí vaše agenty testovatelnými

To je skutečná odměna. V LangChainu byste předávali kontext přes kwargs řetězce nebo uzávěry, neexistuje žádný standardní vzor. V Pydantic AI je výměna skutečných závislostí za testovací dvojnícíky triviální:

# 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

Žádné monkey-patchování. Žádné mockování globálních importů. Prostě předáte jiné deps.

Verdikt: Injektáž závislostí je důvodem, proč zkušení pythonisté preferují Pydantic AI. Je vidět vliv FastAPI.

Poskytovatelé modelů, OpenAI, Anthropic, Gemini, Ollama

Pydantic AI je agnostický vůči modelu. Změna poskytovatele je změna na jeden řádek:

# 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")

Všechno ostatní, nástroje, strukturované výstupy, DI, zůstává identické. Vaše business logika se nemění, když měníte modely.

Verdikt: Design agnostický vůči modelu znamená, že nikdy nejste uzamčeni u jednoho poskytovatele. Začněte s OpenAI pro pohodlí, benchmarkujte s Anthropic a používejte Ollama pro lokální vývoj.

Streamování odpovědí

Pro chatová UI a aplikace v reálném čase je streamování nezbytné. Pydantic AI jej podporuje při zachování typové bezpečnosti:

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)")

Toto krásně funguje s StreamingResponse z FastAPI, stejné ekosystémy, stejné vzory. Dokumentace agentů Pydantic AI pokrývá pokročilé možnosti streamování včetně streamování pouze textu pomocí stream_text().

Pydantic AI vs LangGraph vs OpenAI Agents SDK

Jste zde, takže se pravděpodobně ptáte: „Mám použít Pydantic AI nebo LangGraph?“ Upřímná odpověď: řeší různé problémy a možná použijete oba.

Tabulka porovnání funkcí

Kdy použít který

Zvolte Pydantic AI, když chcete čistý, typově bezpečný kód agenta. Je ideální pro úlohy s jedním agentem s nástroji (boti pro zákaznickou podporu, extrakce dat, agenti pro revizi kódu) a situace, kde záleží na testovatelnosti. Pokud váš tým již používá FastAPI a Pydantic, křivka učení je téměř nulová.

Zvolte LangGraph, když potřebujete složité více kroků workflow s podmíněným větvením, schválením člověkem ve smyčce (human-in-the-loop) a sofistikovanou správou stavu. LangGraph vyniká v orchestraci více kroků, nikoli v kvalitě jednotlivých agentů. Pro hlubší ponor se podívejte na naše úplné srovnání LangGraph vs CrewAI vs OpenAI Agents SDK.

Zvolte OpenAI Agents SDK, když jste 100 % na OpenAI, chcete co nejjednodušší nastavení a nepotřebujete podporu více poskytovatelů nebo DI.

Vzorec kombinace

Zde je to, co zkušené týmy skutečně dělají: používají Pydantic AI pro jednotlivé agenty (čistý kód, testovatelný, typované výstupy) a LangGraph pro orchestraci mezi agenty (směrování, stavové stroje, podmíněná logika). Nesoutěží, jsou to doplňkové vrstvy.

# 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)

Verdikt: Zvolte Pydantic AI pro čistý, testovatelný kód agenta. Zvolte LangGraph pro složité více kroků workflow. Nejsou mutually exclusive.

Testování vašich agentů s TestModel

Toto je sekce, která odděluje průvodce pro začátečníky od průvodce pro produkci. Každá reálná codebase potřebuje testy a testování agentů je notoricky obtížné – volání LLM jsou pomalá, drahá a nedeterministická. Pydantic AI přináší řešení: 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 platná data, která odpovídají vašemu result_type, aniž by prováděla jakákoli volání API. Nulové náklady, deterministické, rychlé. Dokumentace testování Pydantic AI pokrývá pokročilé vzory jako FunctionModel pro vlastní odpovědi a capture_run_messages pro inspekci volání nástrojů.

Testování nástrojů a DI dohromady

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)

Žádná volání API. Žádné nestabilní testy. Žádné náklady. Spusťte toto v CI/CD vedle zbytku vaší testovací sady.

Toto je největší mezera v obsahu na celém SERP. Žádný jiný průvodce Pydantic AI nepokrývá testování. Pokud vytváříte agenty pro produkci, toto je to, co potřebujete.

Pozorovatelnost, integrace Logfire za 5 minut

Produkční agenti potřebují pozorovatelnost AI. Chcete vidět každé volání LLM, vyvolání nástroje, latenci, počet tokenů a náklady. Pydantic AI se nativně integruje s Logfire, platformou pro pozorovatelnost týmu Pydantic (postavenou 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")

Tři řádky. Získáte plné trace ukazující: odeslaný prompt, odpověď modelu, volání nástrojů (pokud existují), úspěchy/neúspěchy validace, opakování, latenci a odhadované náklady. Pokud Logfire není pro vás, Langfuse je solidní open-source alternativa s podporou context engineering pro sledování evoluce vašich promptů.

FAQ

Co je Pydantic AI a jak se liší od LangChain?

Pydantic AI je typově bezpečný framework pro agenty, kde typové nápovědy Pythonu řídí validaci, schémata nástrojů a injektáž závislostí. LangChain je větší framework zaměřený na řetězení volání LLM dohromady. Klíčový rozdíl: Pydantic AI validuje výstupy na úrovni frameworku a poskytuje vestavěnou injektáž závislostí pro testovatelnost, LangChain ve výchozím nastavení nedělá ani jedno.

Jak vytvořit typově bezpečného AI agenta s Pydantic AI?

Definujte Pydantic BaseModel pro svůj výstup, předejte jej jako result_type do Agent a zavolejte run_sync() nebo run(). Agent vrátí validovanou instanci vašeho modelu, nikoli surový řetězec. Úplné příklady naleznete v sekci Strukturované výstupy.

Mám použít Pydantic AI nebo LangGraph pro produkční agenty?

Použijte Pydantic AI pro jednotlivé agenty, kde záleží na typové bezpečnosti, testovatelnosti a čistém kódu. Použijte LangGraph pro orchestraci složitých více kroků workflow s podmíněným směrováním. Mnoho týmů používá obojí, agenty Pydantic AI uvnitvr orchestační vrstvy LangGraph.

Jak Pydantic AI zpracovává volání nástrojů a injektáž závislostí?

Ozdobte funkci dekorátorem @agent.tool a Pydantic AI přečte její typové nápovědy pro vygenerování schématu nástroje. Pro DI nastavte deps_type na Agent a přijměte RunContext[YourDeps] v nástrojích. Runtime závislosti (připojení k DB, API klienti) proudí bez globálního stavu.

Jak přidat streamování do agenta Pydantic AI?

Použijte agent.run_stream() místo agent.run(). Vrátí asynchronní context manager, který yields částečné výsledky přes stream_structured() nebo stream_text(). Koncový výsledek je stále plně validován proti vašemu result_type.

Je Pydantic AI připraveno pro produkci v roce 2026?

Ano. Verze 1.0 byla vydána v září 2025 se závazkem stability API. Je podporována týmem Pydantic (nejstahovanější knihovnou Pythonu pro validaci dat) a aktuálně je na verzi v1.74.0 s pravidelnými aktualizacemi.

Mohu používat Pydantic AI s Ollama a lokálními modely?

Ano. Použijte Agent("ollama:llama3.1") a ujistěte se, že Ollama běží lokálně. Nainstalujte extra balíček pro poskytovatele ollama: pip install "pydantic-ai[ollama]". Strukturované výstupy a nástroje fungují stejně jako u cloudových poskytovatelů.

Jak testovat agenty Pydantic AI?

Použijte TestModel, mock model, který generuje platná strukturovaná data odpovídající vašemu result_type bez volání API. Obalte svůj test do agent.override(model=TestModel()) a spusťte assertace na výstupu. Úplné příklady pytest naleznete v sekci Testování.

Funguje Pydantic AI s FastAPI?

Perfektně. Sdílejí stejnou filozofii injektáže závislostí a jsou vytvořeny stejným týmem. Můžete používat agenty Pydantic AI uvnitř endpointů FastAPI, sdílet mezi nimi typy závislostí a streamovat odpovědi agentů prostřednictvím StreamingResponse.

Jaký je rozdíl mezi Pydantic AI a OpenAI Agents SDK?

Pydantic AI je agnostický vůči modelu (funguje s OpenAI, Anthropic, Gemini, Ollama atd.), má injektáž závislostí, TestModel pro testování a validaci Pydantic. OpenAI Agents SDK je jednodušší, ale uzamčené k modelům OpenAI a postrádá DI a vestavěné testování. Zvolte Pydantic AI pro flexibilitu; zvolte OpenAI Agents SDK pro nejjednodušší možné nastavení pouze pro OpenAI.

Klíčové poznatky a další kroky

Začněte s malým agentem, který má strukturované výstupy. Přidejte nástroj. Přidejte závislosti. Napište test s TestModel. To je cesta do produkce a nyní máte vše, co potřebujete, abyste ji prošli.

Oficiální dokumentace Pydantic AI a GitHub repozitář jsou vynikající pro hlubší ponoření. Framework se rychle vyvíjí, takže si záložkujte changelog.

Zdroje

• Pydantic AI, Oficiální dokumentace
• Dokumentace závislostí Pydantic AI
• Dokumentace testování Pydantic AI
• Oznámení o vydání Pydantic AI v1
• Pozorovatelnost AI Logfire
• pydantic/pydantic-ai, GitHub Repozitář