Pydantic AI в продакшене: типы, инструменты и проверка ответов

Материал сверен с документацией разработчика и лицензией в репозитории 17 октября 2026 года. Критерии выбора здесь — валидация результата, доступ к сервисам приложения, управление рабочим процессом и восстановление после сбоев, а не место в рейтинге производительности.

Что такое Pydantic AI?

Pydantic AI — SDK для ИИ-агентов на Python от команды Pydantic. Он объединяет модель, инструкции, вызываемые функции Python и необязательный тип результата в Agent — объект, который запускает ваше приложение. Модель генерирует ответы, а SDK управляет взаимодействием с ней. В актуальном обзоре описано больше возможностей SDK, но для отдельной функции продукта достаточно понять эту основу.

Представьте, что непредсказуемому исполнителю задали контракт функции. Приложение передаёт контекст, определяет доступные операции и требует результат с именованными полями. Это полезно, например, когда функция поддержки должна вернуть категорию обращения и следующее действие в виде, пригодном для обычного кода Python.

Агент Pydantic AI: одна конфигурация для разных запусков

Объект Agent хранит конфигурацию задачи. Запуск — это конкретная попытка выполнить её с заданным промптом и зависимостями, переданными во время выполнения. В синхронном скрипте можно вызвать run_sync(), а в асинхронном коде приложения — await agent.run(). После завершения итоговое значение доступно через .output. Эти интерфейсы описаны в документации Agent.

У типизации здесь две разные задачи. Статическая типизация помогает редактору или анализатору типов находить несоответствия в коде Python. Валидация результата во время выполнения проверяет, соответствуют ли данные от модели объявленной схеме. Ни то ни другое не устраняет неоднозначность в обращении клиента.

Инструменты Pydantic AI: функции с доступом к контексту приложения

Функциональные инструменты позволяют модели запросить действие, которое умеет выполнять ваш код, например найти сведения о подписке. Для регистрации функции, которой нужен контекст запуска, используйте @agent.tool; если контекст не нужен — @agent.tool_plain. Аннотации типов описывают аргументы, а строки документации помогают объяснить модели назначение инструмента. Как из этого формируются схемы инструментов, показано в документации по функциональным инструментам.

Внедрение зависимостей — это передача в конкретный запуск тех сервисов, которые ему нужны. Параметр deps_type=CustomerContext объявляет ожидаемый тип Python, а deps=customer_context передаёт сам экземпляр. Инструмент получает RunContext[CustomerContext] и обращается к зависимостям через ctx.deps. В контексте могут находиться данные аутентифицированного клиента, соединение с базой данных или API-клиент. В руководстве по зависимостям прямо указано: deps_type нужен для проверки типов, а не для валидации объекта зависимостей во время выполнения.

Для разработчика SaaS польза вполне практическая: сервер может определить аккаунт клиента ещё до того, как модель запросит данные. Проверку прав доступа оставляйте в коде, который эти данные извлекает. Передача клиента базы данных через типизированный контекст сама по себе не ограничивает набор строк, которые он может прочитать.

Структурированный вывод в Pydantic AI: что именно проходит проверку

output_type задаёт результат, который ожидает получить приложение. Передайте Pydantic BaseModel — класс Python с типизированными полями, — и Pydantic AI построит схему и проверит сгенерированные данные. Согласно документации по выводу, поддерживаются и другие типы, в том числе dataclasses, списки и объединения типов.

Три режима вывода различаются способом, которым модель просят сформировать эти данные:

Это три документированных режима вывода SDK, а не три уровня точности. Выберите механизм, который поддерживает ваша модель, а затем оцените результат на своей задаче.

Ошибку валидации можно вернуть модели, чтобы она попробовала ещё раз. Число повторных попыток ограничено; исчерпание лимита повторов для вывода может привести к исключению UnexpectedModelBehavior. Приложению нужен сценарий обработки такого сбоя: например, запросить недостающие сведения или передать обращение человеку. Подробнее — в описании повторных попыток.

Практический пример Pydantic AI: разбор обращений в поддержку

Начните с формирования объекта решения без изменения данных и лишь затем разрешайте агенту что-либо менять. В этом примере документированные приёмы работы с Agent, RunContext и output_type применяются к небольшой задаче классификации обращений в поддержку.

В актуальном руководстве по установке требуется Python 3.11 или новее. Установите библиотеку в виртуальном окружении:

python -m pip install pydantic-ai

Задайте в окружении OPENAI_API_KEY для аккаунта с доступом к модели. Сохраните следующий код в triage.py и выполните python triage.py. Идентификатор модели взят из актуальной документации Agent; его можно заменить на другую поддерживаемую модель, доступную вашему аккаунту.

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Customer:
    plan: str

class Triage(BaseModel):
    category: Literal['billing', 'technical']
    priority: Literal['normal', 'urgent']
    summary: str

agent = Agent(
    'openai:gpt-6.1-sol',
    deps_type=Customer,
    output_type=Triage,
    instructions=(
        'Triage the support message. Use customer_plan for context. '
        'Summarize the issue without inventing account facts.'
    ),
)

@agent.tool
def customer_plan(ctx: RunContext[Customer]) -> str:
    """Return the authenticated customer's plan."""
    return ctx.deps.plan

if __name__ == '__main__':
    result = agent.run_sync(
        'I was charged twice for my subscription.',
        deps=Customer(plan='business'),
    )
    print(result.output.model_dump())

При успешном запуске result.output содержит объект Triage. Категория и приоритет должны принимать одно из объявленных значений, а model_dump() преобразует объект в словарь. Инструмент доступа к контексту, типизированный результат и отклонение недопустимой категории в этом примере проверены локально, без обращения к модели, с помощью TestModel. Формулировки, которые генерирует модель, и точность классификации ещё предстоит оценить на ваших собственных случаях.

Контекст клиента здесь приведён для иллюстрации. В продукте формируйте его из аутентифицированного запроса и данных аккаунта. Также определите, по каким признакам обращение считается срочным: схема перечисляет допустимые метки, но не задаёт правила срочности. Устранить этот пробел в бизнес-правилах важнее, чем добавить ещё одного агента.

Модели в Pydantic AI: смена провайдера требует проверки поведения

Pydantic AI сокращает объём кода для подключения разных провайдеров, но при смене модели меняется и поведение системы. Для многих вариантов подключения используется идентификатор <provider>:<model>. В других случаях нужно явно создать модель или клиент, указать подходящие учётные данные и установить дополнительные компоненты. Поддержка конкретных возможностей зависит от выбранной модели и API — это видно из каталога провайдеров.

В каталоге перечислены OpenAI, Anthropic, Google/Gemini, AWS Bedrock, Groq, Mistral, xAI и Ollama. Среди других документированных вариантов подключения:

• Сервисы моделей и инференса: Alibaba Cloud/Qwen, Cerebras, Cohere, Crusoe, DeepSeek, Fireworks AI, Heroku AI, Hugging Face, Meta, Moonshot AI/Kimi, Nebius AI Studio, OVHcloud AI Endpoints, SambaNova, Snowflake Cortex, Together AI и Z.AI.
• Облачные платформы, шлюзы и самостоятельное размещение: Google Cloud/Vertex AI, Microsoft Azure/Foundry, Pydantic AI Gateway, LiteLLM, OpenRouter, Vercel AI Gateway и vLLM.
• Дополнительные способы доступа и подключения моделей для принятия решений: GitHub Copilot, OpenAI Codex, OpenAI Decisions API, System One API и TypeSafe (Jev).

За этими названиями стоят разные способы доступа к моделям, а не взаимозаменяемые наборы возможностей. Локальная модель может иначе работать с инструментами, чем передовая модель в облаке; даже совместимый API может накладывать другие ограничения на схему.

Для основателя продукта переносимость означает возможность сменить поставщика и экспериментировать. Для разработчика критерий приёмки остаётся прежним: выбирает ли новая модель правильные инструменты, соблюдает ли схему вывода и принимает ли приемлемые решения на тех же случаях? Получите и сохраните эти результаты проверки до смены модели, используемой по умолчанию в продакшене.

MCP и устойчивое выполнение: подключение инструментов и сохранение прогресса

MCP подключает агента к серверам инструментов, а устойчивое выполнение помогает продолжить работу после прерывания. Это разные задачи.

Model Context Protocol, или MCP, стандартизирует способ, которым приложения предоставляют инструменты и контекст ИИ-клиентам. Поддержка MCP в Pydantic AI позволяет передавать URL серверов, клиенты или наборы инструментов; там, где провайдер поддерживает MCP напрямую, доступны и такие варианты подключения. Благодаря этому сервер инструментов можно использовать повторно, не создавая отдельную интеграцию для каждого агента. Однако MCP не определяет, какому клиенту разрешено выполнять операции этого сервера.

Устойчивое выполнение сохраняет прогресс, чтобы работа могла продолжиться после сбоя, перезапуска или долгого ожидания. В актуальной документации по устойчивому выполнению указаны 9 решений:

• Поддерживаются совместно с командами поставщиков: Temporal, DBOS, Prefect, Restate и AWS Lambda.
• Внешние интеграции с SDK: Kitaru, Apache Airflow, Absurd и pgtask.

Для других движков также есть средство создания бэкенда. Выбирайте документированную интеграцию, если агент должен продолжать работу дольше, чем существует запустивший его запрос или процесс. Наличие этих интеграций не означает, что обычного вызова Agent достаточно для развёртывания системы с устойчивым выполнением.

Представьте задачу поддержки: подготовить рекомендацию по возврату денег, дождаться одобрения и затем выполнить возврат. Сохранённый запуск позволяет удержать работу на этапе ожидания, но платёжная операция всё равно должна быть идемпотентной: повтор запроса не должен приводить к ещё одному возврату. Определите, как распознавать уже выполненную операцию и как выяснять итог, если он неизвестен. Это задача приложения, которую движок сам по себе не снимает.

Pydantic Evals: как проверить решение за структурированным ответом

Pydantic Evals проверяет, насколько приемлемо агент выполнил задачу, а не только можно ли разобрать его ответ. Это отдельный пакет для оценки качества с описанием проверок в коде; Pydantic AI для него не требуется. Вы задаёте случаи и оценщики, запускаете задачу на этих случаях и изучаете отчёт. В документации разобрана оценка как итоговых результатов, так и траекторий вызова инструментов — последовательностей действий во время запуска.

Для примера с классификацией обращений подготовьте случаи с двойным списанием, неудачным входом в аккаунт, отсутствующим контекстом аккаунта и сообщением, которое просит ассистента проигнорировать инструкции. Проверяйте категорию, решение о передаче обращения специалисту и факт обязательного запроса данных аккаунта. Включите случаи, где правильное действие — задать уточняющий вопрос.

При эксплуатации трассировка объясняет отдельный запуск, а оценка качества показывает поведение на наборе случаев. Pydantic AI использует OpenTelemetry — стандарт телеметрии приложений — и через инструментирование поддерживает другие системы наблюдаемости. Если проверка не пройдена, изучите запрос к модели и вызовы инструментов, а затем сохраните этот случай в наборе для оценки.

Дополнительный сервис Pydantic Logfire предоставляет трассировку агентов, моделей и инструментов. Согласно его странице тарифов, план Personal бесплатный, а Team стоит от $49 в месяц; дополнительное потребление и места пользователей оплачиваются отдельно.

Когда выбирать Pydantic AI среди других фреймворков

Выбирайте абстракцию под ту часть функции, которая действительно сложна. Разработчику Python с готовыми доменными моделями и сервисами стоит рассмотреть Pydantic AI, если главная задача интеграции — типизированные входные данные, инструменты и результаты. Основателю с техническим опытом стоит оценить, какой вариант позволит обойтись наиболее компактной системой, работу которой команда сможет объяснить и поддерживать.

Pydantic AI или LangGraph

LangGraph — более подходящая отправная точка, если вы хотите явно спроектировать рабочий процесс вокруг агента. В его документации основной акцент сделан на долго работающих агентах с состоянием, устойчивом выполнении и участии человека. Представьте приложение с обязательными этапами: собрать подтверждающие данные, получить одобрение, выполнить разрешённое действие и сверить результат.

Pydantic AI удобен, когда типизированный агент — компонент процесса, которым приложение уже управляет. Он тоже может участвовать в устойчивых рабочих процессах, поэтому одно лишь сохранение состояния не определяет выбор. Главный вопрос: вы хотите моделировать бизнес-процесс вокруг агента или в первую очередь настраивать поведение самого агента? При использовании LangGraph вам придётся самим проектировать процесс и управлять его состоянием. Ограничение Pydantic AI в том, что удобный контракт агента не проектирует за вас весь процесс.

Pydantic AI или LangChain

LangChain имеет смысл, если его готовые интеграции с моделями и инструментами, а также архитектура агентов уже подходят вашему приложению. Согласно обзору LangChain, агенты LangChain построены на LangGraph. Поэтому выбор более высокоуровневого API агентов сохраняет эту основу выполнения.

Выбирайте Pydantic AI для сервиса на Python, если его контракты зависимостей и результатов соответствуют тому, как вы уже пишете код. Работающую функцию на LangChain стоит сохранить, пока вы не можете назвать конкретную сложность, которую устранит миграция. В абстракциях LangChain всё равно придётся разобраться, когда поведение затрагивает и агента, и рабочий процесс; замена библиотеки лишь перенесёт эту работу в другое место. Подробнее об их связи — в сравнении LangChain и LangGraph.

OpenAI Agents SDK или прямые вызовы API

OpenAI Agents SDK подходит для агентного цикла, которым управляет приложение, с инструментами, передачей задач между агентами и трассировкой. SDK работает внутри вашего приложения и поддерживает структурированные результаты; его интерфейсы провайдеров позволяют использовать и модели других разработчиков. Считать типизированный вывод или выбор провайдера исключительными возможностями Pydantic AI было бы неверно.

Выбирайте этот SDK, если его модель агентов и передачи задач согласуется с интеграцией OpenAI, которую вы планируете поддерживать. Выбирайте Pydantic AI, если лучше подходят его модель зависимостей Python и настройка провайдеров. В обоих случаях развёртывание, права доступа к инструментам и корректность приложения остаются вашей ответственностью.

Прямых вызовов API достаточно, если задача сводится к запросу модели и небольшому объёму детерминированного кода вокруг него. API уже умеют возвращать результаты, ограниченные схемой. Для извлечения данных из чеков не нужен агентный фреймворк только потому, что результат представлен объектом Pydantic. Предел этого подхода наступает, когда для разных функций приходится снова и снова реализовывать циклы вызова инструментов, повторные попытки при ошибках валидации и инструментирование.

Более широкий выбор разобран в руководстве по фреймворкам ИИ-агентов. Если вы пока выбираете между явным управлением процессом и разделением ролей между специализированными агентами, переходите к сравнению LangGraph и CrewAI.

Какие ожидания от типизированных агентов завышены

Главное преувеличение — считать, что типизированный агент автоматически даёт корректно работающую систему для продакшена. Библиотека не может устранить несколько принципиальных ограничений:

• Типобезопасность не гарантирует достоверность. Ответ правильной структуры может неверно трактовать запрос пользователя. Определите, что нужно сверять с авторитетными источниками данных.
• Переносимость между моделями не означает одинаковое качество. Конфигурацию с новым провайдером нужно оценивать на вашей задаче так же, как новый промпт.
• Устойчивое выполнение не решает все вопросы развёртывания. Нужно выбрать и эксплуатировать движок, хранилище и механизм восстановления, необходимые вашей функции.
• Повторная попытка — это дополнительная работа. Ещё один запрос к модели увеличивает задержку и потребление ресурсов. Явно задайте, что делает приложение после исчерпания попыток.

Начинайте внедрение, если вашей следующей функции на Python уже нужны инструменты и структурированные решения. Отложите смену фреймворка, если существующая система работает, а единственное обещанное преимущество — более аккуратный демонстрационный код. Если функция просто извлекает данные одним вызовом модели и уже имеет достаточную валидацию и обработку ошибок, менять почти ничего не требуется.

Частые вопросы о Pydantic AI

Что выпустить на следующей неделе

Прежде чем расширять самостоятельность агента, задайте чёткие критерии приёмки для небольшой функции, работающей только на чтение. В продукте для поддержки начните с объекта классификации из примера, а финальное действие с аккаунтом оставьте обычному коду приложения.

За практическими заметками о разработке функций с ИИ подписывайтесь на рассылку.