Pydantic AI: Посібник для продакшену (після Hello World)

Pydantic AI: Посібник для продакшену (після Hello World)

Сирий вивід від LLM ламає додатки. Ви просите JSON, а отримуєте markdown. Ви просите число від 1 до 10, а отримуєте «Звісно! Ось число: сім». Якщо ви створювали щось реальне за допомогою API LLM, ви вже писали захисний код для парсингу, який змушує вас сумніватися у правильності свого кар'єрного вибору. Pydantic AI виправляє це. Це типобезпечний фреймворк для агентів, створений тією ж командою, що стоїть за Pydantic та FastAPI. Уявіть собі «FastAPI для ШІ-агентів»: ви визначаєте бажане за допомогою анотацій типів Python, а фреймворк займається валідацією, повторними спробами та викликом інструментів.

Цей посібник із Pydantic AI призначений для розробників, які вже зробили свій перший виклик до LLM і хочуть освоїти патерни для продакшену: структуровані виводи, які не ламаються, впровадження залежностей для агентів, придатних до тестування, та реальні інструменти beyond простих API погоди. Наприкінці ви матимете робочих агентів з інструментами, DI, стрімінгом та тестами.

Pydantic AI коротко

Найвидатнішими функціями є структуровані виводи (валідовані моделями Pydantic), впровадження залежностей (схоже на Depends у FastAPI) та TestModel (мок LLM для тестування без викликів API). Якщо ви прийшли з LangChain і запитуєте: «чи є щось чистіше?», то, ймовірно, це воно.

Встановлення та перший агент

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

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

Ваш перший агент у 5 рядках:

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"

Ось і все. Agent обгортає модель, run_sync надсилає промпт і повертає результат. Тут result.output є звичайним рядком, але це скоро зміниться.

Структуровані виводи: чому існує Pydantic AI

Це ключова функція. Замість того щоб отримувати рядок від LLM і сподіватися, що це валідний JSON, ви визначаєте модель Pydantic, і агент повертає валідований об'єкт Python.

До: Сирий вивід 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.

Після: Структурований вивід з 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)

Різниця колосальна. result.output — це справжній об'єкт MovieReview. Якщо LLM поверне rating: "eight" замість rating: 8, валідація Pydantic це виявить. Для глибшого розуміння того, як це працює у різних провайдерів, перегляньте наш посібник щодо структурованих виводів у різних постачальників LLM.

Що стається, коли валідація не проходить

Ось частина, яку не показує жоден інший туторіал: що відбувається, коли LLM помиляється?

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

Цикл повторних спроб зі зворотним зв'язком є головною перевагою Pydantic AI. LLM вчиться на власних помилках валідації. Вам не потрібно писати логіку повторних спроб, фреймворк обробляє це сам.

Вердикт: Структуровані виводи — це найкраща причина використовувати Pydantic AI замість сирих викликів API. Якщо ви вручну парсите JSON від LLM, припиніть це робити.

Інструменти та виклик функцій

Інструменти дозволяють вашому агенту викликати функції Python для отримання реальних даних. Замість того щоб LLM вигадувала факти, вона може робити запити до вашої бази даних, шукати у вашій документації або викликати API.

Реєстрація інструменту

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)

Декоратор @agent.tool реєструє функцію. Pydantic AI зчитує анотації типів функції та її docstring, щоб повідомити LLM, що робить інструмент, які аргументи він приймає і що повертає. Жодного ручного написання схеми, ваші анотації типів І Є схемою. Для довідки про те, як працює виклик функцій LLM під капотом, у нас є окремий посібник.

RunContext: передача даних інструментам

Саме тут Pydantic AI відрізняється від інших фреймворків. RunContext дозволяє передавати дані часу виконання (з'єднання з базою даних, інформацію про користувача, клієнти API) вашим інструментам без глобального стану.

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 надає інструменту доступ до всього, що ви передали під час виконання. Інструмент не імпортує глобальне з'єднання з базою даних, він отримує його. Це впровадження залежностей, і саме воно робить ваших агентів придатними для тестування.

Приклад інструменту з реального світу

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

Вердикт: Виклик інструментів у Pydantic AI чистіший, ніж у будь-якому іншому фреймворку, завдяки тому, що анотації типів беруть на себе основну роботу. Ви пишете звичайні функції Python з анотаціями типів. Фреймворк вирішує решту.

Впровадження залежностей: функція, якої бракує LangChain

Якщо ви використовували Depends у FastAPI, ви вже розумієте систему DI у Pydantic AI. Якщо ні, ось коротке пояснення: замість того щоб ваш агент сам шукав те, що йому потрібно (глобальні з'єднання з БД, клієнти API, конфігурацію), ви передаєте йому все під час виконання.

Визначення залежностей

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

Використання залежностей в інструментах

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

Чому DI робить ваших агентів придатними для тестування

Це справжня винагорода. У LangChain ви б передавали контекст через kwargs ланцюжка або замикання, немає стандартного патерну. У Pydantic AI заміна реальних залежностей на тестові заглушки є тривіальною:

# 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

Жодного монкі-патчингу. Жодного мокування глобальних імпортів. Ви просто передаєте інші залежності.

Вердикт: Впровадження залежностей — це причина, чому досвідчені Python-розробники надають перевагу Pydantic AI. Це вплив FastAPI дає про себе знати.

Постачальники моделей: OpenAI, Anthropic, Gemini, Ollama

Pydantic AI є агностичним щодо моделей. Перемикання провайдерів — це зміна в один рядок:

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

Усе інше — інструменти, структуровані виводи, DI — залишається ідентичним. Ваша бізнес-логіка не змінюється, коли ви перемикаєте моделі.

Вердикт: Дизайн, агностичний до моделей, означає, що ви ніколи не будете прив'язані до одного провайдера. Почніть з OpenAI для зручності, проводьте бенчмарки з Anthropic і використовуйте Ollama для локальної розробки.

Стрімінг відповідей

Для чат-інтерфейсів та застосунків реального часу стрімінг є необхідним. Pydantic AI підтримує його, зберігаючи типобезпеку:

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

Це чудово працює з StreamingResponse у FastAPI, та сама екосистема, ті самі патерни. Документація агентів Pydantic AI охоплює розширені опції стрімінгу, включаючи стрімінг лише тексту за допомогою stream_text().

Pydantic AI проти LangGraph проти OpenAI Agents SDK

Ви тут, тому, ймовірно, запитуєте: «чи варто мені використовувати Pydantic AI чи LangGraph?». Чесна відповідь: вони вирішують різні проблеми, і ви можете використовувати обидва.

Таблиця порівняння функцій

Коли використовувати кожен

Обирайте Pydantic AI, якщо вам потрібен чистий, типобезпечний код агентів. Він ідеальний для задач з одним агентом та інструментами (боти підтримки клієнтів, вилучення даних, агенти код-рев'ю) та ситуацій, де важлива можливість тестування. Якщо ваша команда вже використовує FastAPI та Pydantic, крива навчання майже плоска.

Обирайте LangGraph, якщо вам потрібні складні багатокрокові робочі процеси з умовним розгалуженням, затвердженням людиною (human-in-the-loop) та складним управлінням станом. LangGraph чудово справляється з оркестрацією кількох кроків, а не з якістю окремого агента. Для глибокого занурення перегляньте наше повне порівняння LangGraph проти CrewAI проти OpenAI Agents SDK.

Обирайте OpenAI Agents SDK, якщо ви на 100% використовуєте OpenAI, хочете найпростішого можливого налаштування і вам не потрібна підтримка кількох провайдерів або DI.

Патерн комбінування

Ось що насправді роблять досвідчені команди: використовують Pydantic AI для окремих агентів (чистий код, тестованість, типізовані виводи) та LangGraph для оркестрації між агентами (маршрутизація, стейт-машини, умовна логіка). Вони не конкурують, вони є комплементарними шарами.

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

Вердикт: Обирайте Pydantic AI для чистого, придатного до тестування коду агентів. Обирайте LangGraph для складних багатокрокових робочих процесів. Вони не є взаємовиключними.

Тестування ваших агентів за допомогою TestModel

Це розділ, який відрізняє посібник для початківців від посібника для продакшену. Кожна реальна кодова база потребує тестів, а тестування агентів є notoriously складним: виклики LLM повільні, дорогі та недетерміновані. Pydantic AI пропонує рішення: 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 генерує валідні дані, які відповідають вашому result_type, без здійснення будь-яких викликів API. Нульова вартість, детермінованість, швидкість. Документація з тестування Pydantic AI охоплює розширені патерни, такі як FunctionModel для_custom_ відповідей та capture_run_messages для перевірки викликів інструментів.

Тестування інструментів та DI разом

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)

Жодних викликів API. Жодних нестабільних тестів. Жодних витрат. Запускайте це в CI/CD разом із рештою вашого набору тестів.

Це найбільша прогалина в контенті на всій SERP. Жоден інший посібник із Pydantic AI не охоплює тестування. Якщо ви будуєте агентів для продакшену, це саме те, що вам потрібно.

Спостережуваність: інтеграція Logfire за 5 хвилин

Продакшен-агентам потрібна спостережуваність ШІ. Ви хочете бачити кожен виклик LLM, виклик інструменту, затримку, кількість токенів та вартість. Pydantic AI нативно інтегрується з Logfire, платформою спостережуваності від команди Pydantic (побудованою на 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")

Три рядки. Ви отримуєте повні трейси, що показують: надісланий промпт, відповідь моделі, виклики інструментів (якщо є), успішні/невдалі валідації, повторні спроби, затримку та оцінкову вартість. Якщо Logfire вам не підходить, Langfuse є солідною альтернативою з відкритим кодом з підтримкою контекстного інжинірингу для відстеження еволюції ваших промптів.

FAQ

Що таке Pydantic AI і чим він відрізняється від LangChain?

Pydantic AI — це типобезпечний фреймворк агентів, де анотації типів Python керують валідацією, схемами інструментів та впровадженням залежностей. LangChain — це більший фреймворк, орієнтований на chaining викликів LLM разом. Ключова відмінність: Pydantic AI валідує виводи на рівні фреймворку та надає вбудоване впровадження залежностей для тестованості, LangChain за замовчуванням не робить ні того, ні іншого.

Як створити типобезпечного ШІ-агента з Pydantic AI?

Визначте Pydantic BaseModel для вашого виводу, передайте її як result_type до Agent і викличте run_sync() або run(). Агент повертає валідований екземпляр вашої моделі, а не сирий рядок. Дивіться розділ «Структуровані виводи» для повних прикладів.

Чи варто використовувати Pydantic AI чи LangGraph для продакшен-агентів?

Використовуйте Pydantic AI для окремих агентів, де важливі типобезпека, тестованість та чистота коду. Використовуйте LangGraph для оркестрації складних багатокрокових робочих процесів з умовною маршрутизацією. Багато команд використовують обидва: агенти Pydantic AI всередині шару оркестрації LangGraph.

Як Pydantic AI обробляє виклик інструментів та впровадження залежностей?

Прикрасьте функцію декоратором @agent.tool, і Pydantic AI зчитає її анотації типів для генерації схеми інструменту. Для DI встановіть deps_type на Agent і прийміть RunContext[YourDeps] в інструментах. Залежності часу виконання (з'єднання з БД, клієнти API) проходять через систему без глобального стану.

Як додати стрімінг до агента Pydantic AI?

Використовуйте agent.run_stream() замість agent.run(). Це повертає асинхронний менеджер контексту, який видає часткові результати через stream_structured() або stream_text(). Кінцевий результат все одно повністю валідується проти вашого result_type.

Чи готовий Pydantic AI до продакшену у 2026 році?

Так. Версія 1.0 вийшла у вересні 2025 року із зобов'язанням щодо стабільності API. Його підтримує команда Pydantic (найпопулярніша бібліотека Python для валідації даних), і зараз він має версію v1.74.0 з регулярними оновленнями.

Чи можна використовувати Pydantic AI з Ollama та локальними моделями?

Так. Використовуйте Agent("ollama:llama3.1") і переконайтеся, що Ollama запущена локально. Встановіть додатковий пакет провайдера ollama: pip install "pydantic-ai[ollama]". Структуровані виводи та інструменти працюють так само, як і з хмарними провайдерами.

Як тестувати агентів Pydantic AI?

Використовуйте TestModel, мок-модель, яка генерує валідні структуровані дані, що відповідають вашому result_type, без викликів API. Обгорніть ваш тест у agent.override(model=TestModel()) і виконайте ассершни на виводі. Дивіться розділ «Тестування» для повних прикладів pytest.

Чи працює Pydantic AI з FastAPI?

Ідеально. Вони поділяють одну філософію впровадження залежностей і створені однією командою. Ви можете використовувати агентів Pydantic AI всередині ендпоінтів FastAPI, спільно використовувати типи залежностей між ними та стрімити відповіді агентів через StreamingResponse.

Яка різниця між Pydantic AI та OpenAI Agents SDK?

Pydantic AI є агностичним до моделей (працює з OpenAI, Anthropic, Gemini, Ollama тощо), має впровадження залежностей, TestModel для тестування та валідацію Pydantic. OpenAI Agents SDK простіший, але прив'язаний до моделей OpenAI і не має DI та вбудованого тестування. Обирайте Pydantic AI для гнучкості; обирайте OpenAI Agents SDK для найпростішого можливого налаштування тільки для OpenAI.

Ключові висновки та наступні кроки

Почніть з малого агента, який має структуровані виводи. Додайте інструмент. Додайте залежності. Напишіть тест з TestModel. Це шлях до продакшену, і тепер у вас є все необхідне, щоб ним піти.

Офіційна документація Pydantic AI та репозиторій GitHub є чудовими ресурсами для поглиблення знань. Фреймворк розвивається швидко, тому додайте changelog у закладки.

Джерела

• Pydantic AI, Офіційна документація
• Документація залежностей Pydantic AI
• Документація тестування Pydantic AI
• Анонс релізу Pydantic AI v1
• Спостережуваність ШІ Logfire
• pydantic/pydantic-ai, Репозиторій GitHub