Pydantic AI: типизированные агенты на смену хаотичным выводам языковых моделей

Типовой проект с языковой моделью начинается аккуратно: промпт, вызов API, парсинг ответа — и всё работает. Но через пару недель модель вдруг добавляет перед JSON вежливое «Конечно! Вот ваш ответ:», обязательные поля исчезают, а вложенный массив приходит строкой.

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

Фреймворк создаёт команда Pydantic — та самая библиотека, на которой держится валидация в FastAPI, OpenAI SDK и десятке других проектов. Инструмент агента здесь описывается обычной функцией с аннотациями, структурированный ответ — pydantic-моделью, а замена облачной модели на локальную через Ollama сводится к правке одной строки. Установка привычна: uv add pydantic-ai или pip install pydantic-ai.

Базовая версия стала компактнее, специфичные провайдеры доустанавливаются отдельно. Для старта достаточно создать провайдер с настройками своего шлюза, модель с явным именем и передать их в Agent. Синхронный вызов run_sync — лишь надстройка над асинхронным ядром: внутри всё на asyncio, но для скриптов и блокнотов есть готовые sync-варианты, а для FastAPI — обычный await.

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

Сигнатура превращается в JSON-схему, docstring уходит модели как описание инструмента. Декораторы бывают двух видов: @agent.tool ждёт первым аргументом RunContext, @agent.tool_plain — нет. Через контекст инструмент добирается до зависимостей, которые описываются обычным типом, объявляются в конструкторе агента и передаются при запуске.

Никаких глобальных переменных: что нужно инструменту — то и в типе, статический чекер подскажет, если забыли поле. Тестам это тоже на руку: подсовываете заглушку вместо HTTP-клиента и гоняете агента без сети. Docstring здесь адресован модели: от формулировки зависит, выберет ли она инструмент и с какими аргументами вызовет.

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

Обычная ошибка из инструмента роняет запуск, а ModelRetry отправляет текст ошибки самой модели, и она пробует поправить аргументы и вызвать инструмент ещё раз. Та же логика включается при ValidationError. По умолчанию у каждого инструмента одна повторная попытка, лимит поднимается агентом или точечно.

В версии 2 появился ToolFailed для случаев, когда повторять бессмысленно: модель узнаёт о провале, но бюджет ретраев не тратится. Структурированный вывод закрывает самое больное место. Описываете pydantic-модель, передаёте в конструктор — и агент обязан вернуть данные по конкретной схеме.

Невалидный ответ не пройдёт валидацию и уйдёт модели на переделку, кривой JSON больше не доедет до бизнес-логики, а result.output в коде окажется уже готовым типизированным объектом. IDE подсказывает поля, mypy ловит опечатки, сериализация достаётся бесплатно. Дополнительно можно повесить output-валидатор, который проверит уже готовый объект на бизнес-правила и при необходимости вызовет ModelRetry.

Например, если сумма возврата превышает лимит, модель получит указание пересмотреть решение. Так схема ловит формат, а валидатор — смысл. На практике Pydantic AI позволяет собрать агента поддержки с парой инструментов и зависимостями за десяток строк.

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

Пример из статьи показывает работу с GPT-6-Luna на платформе BotHub, но точно так же подключается любая локальная модель через Ollama — достаточно сменить одну строку. Такой подход делает агентов предсказуемыми, а код — поддерживаемым, возвращая разработчикам контроль над стыком между языковой моделью и приложением.