أوضحت Machine Learning Mastery كيفية بناء وكلاء ذكاء اصطناعي في Python باستخدام Pydantic AI

Machine Learning Mastery 29 апреля 2026 года опубликовал подробный разбор Pydantic AI — Python-фреймворка для сборки AI-агентов с типизацией, валидацией и встроенными инструментами. Материал показывает, как превратить работу с LLM из набора хрупких строк и парсеров в более предсказуемый production-процесс.

Почему это важно

Главная идея статьи проста: большинство агентных обвязок до сих пор напоминают glue code. Модель возвращает строку, разработчик надеется, что там будет корректный JSON, затем руками парсит ответ, ловит ошибки и дописывает исключения на каждом шаге. Pydantic AI предлагает другой путь.

Вместо неструктурированных ответов он строит работу вокруг Pydantic-моделей, схем, проверки типов и автоматических повторных попыток, если выход модели не соответствует ожидаемой структуре. Для Python-разработчиков это означает меньше магии и больше кода, который можно тестировать, читать и сопровождать. В статье это показывают с самого базового примера: агент создаётся буквально в несколько строк, а модель указывается через строку формата provider:model-name.

Автор использует openai:gpt-4o-mini, но отдельно подчёркивает, что тот же шаблон работает и с другими провайдерами, включая Anthropic и Gemini. Инструкции для агента задаются один раз, после чего можно запускать либо синхронный сценарий через run_sync, либо асинхронный вариант с тем же API. За счёт этого порог входа остаётся низким, а архитектура не разваливается при первом усложнении логики.

Из чего состоит подход

Самая полезная часть материала — разбор четырёх механизмов, на которых держится практический agent workflow в Pydantic AI. Автор не уходит в абстракцию и не описывает фреймворк на уровне обещаний: каждый блок сопровождается коротким кодовым примером и объяснением, как он закрывает конкретную боль production-разработки, без лишней теории. В результате статья читается как карта минимального набора решений для первого рабочего агента на Python.

output_type заставляет модель возвращать данные в форме валидированного Python-объекта, а не произвольного текста. @agent.tool_plain превращает обычную функцию Python в инструмент, который агент может вызвать по ходу рассуждений.

deps_type и RunContext дают dependency injection без глобального состояния и скрытых зависимостей. capabilities подключают дополнительные возможности вроде WebSearch и Thinking без перегрузки конструктора. Отдельно автор показывает, как это выглядит на примере извлечения данных из вакансии.

Разработчик описывает модель JobPosting с полями вроде должности, компании, списка навыков, уровня seniority и признака remote-работы, а агент возвращает уже готовый объект вместо сырого текста. Если поле пропущено или тип не совпал, фреймворк валидирует ответ и пробует ещё раз до того, как ошибка уйдёт дальше в приложение. Это снимает типичную боль всех систем, где LLM должна выдавать данные, пригодные для немедленного использования в коде.

Как это ведёт в продакшен Второй крупный пример в статье посвящён tool calling.

Автор берёт простую nutrition-базу и регистрирует функцию, которая по названию ингредиента возвращает калории, белки, углеводы и жиры на 100 граммов. Дальше агент получает запрос вроде анализа блюда, сам вызывает инструмент по каждому ингредиенту, суммирует значения и отдаёт результат в виде модели MealSummary. На выходе получается не чат-ответ в свободной форме, а структурированная сводка с итоговыми цифрами, вердиктом по составу и рекомендацией.

Важная деталь: docstring у функции здесь не косметика, а часть контракта, по которой модель понимает, когда и зачем вызывать инструмент. Ещё важнее блок про dependency injection. Вместо жёстко зашитой словарной базы автор оборачивает источник данных в сервисный класс NutritionService, а затем передаёт его агенту через deps и типизированный RunContext.

Это делает код намного ближе к реальной эксплуатации: на месте словаря может быть база данных, API-клиент, пользовательская сессия или любая другая runtime-зависимость. Плюс появляется нормальная тестируемость. В примере сервис легко подменяется на mock, и агент продолжает работать без изменений в своей основной логике.

Финальный слой — встроенные capabilities. В статье разбираются как минимум две: WebSearch для доступа к актуальным данным из интернета и Thinking для более глубокого пошагового рассуждения на сложных задачах. Их можно комбинировать в одном агенте, например для исследовательского помощника, который сам решает, что искать, затем получает свежие результаты и уже после этого формирует ответ.

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

Что это значит

Материал Machine Learning Mastery полезен тем, что переводит разговор об AI-агентах из режима демо в режим инженерной практики. Pydantic AI здесь показан не как очередная обёртка над LLM, а как способ навести дисциплину в типах, зависимостях и инструментах. Для Python-команд это хороший сигнал: собирать агентов можно без тяжёлого оркестратора, если с самого начала опереться на валидируемые схемы, явные контракты и тестируемые runtime-компоненты.