Pydantic AI V2: как создавать AI-агентов на Python с типобезопасностью

Pydantic AI V2 -- это стабильный Python-фреймворк для создания AI-агентов в продакшн-среде, разработанный командой Pydantic и выпущенный 23 июня 2026 года. После семи бета-версий и нескольких месяцев интенсивного тестирования вышел первый полноценный стабильный релиз -- V2.0. Pydantic AI создавался той же командой, которая разработала знаменитую библиотеку Pydantic для валидации данных в Python, ставшую де-факто стандартом для разработки API и схем данных в экосистеме FastAPI и Django.

Главная идея Pydantic AI: дать вашей IDE и AI-ассистенту по написанию кода максимум контекста для автодополнения и проверки типов, переводя целые классы ошибок с этапа выполнения на этап написания кода. Если вы когда-либо отлаживали AI-агента и обнаруживали ошибки типов только в рантайме -- Pydantic AI решает именно эту проблему. Вместо того чтобы передавать данные как словари (dict) и получать ошибки при выполнении, вы работаете с типизированными структурами, и IDE подсвечивает проблемы ещё до запуска.

Pydantic AI V2 поддерживает практически всех крупных провайдеров языковых моделей: OpenAI, Anthropic (Claude), Google Gemini, DeepSeek, Grok (xAI), Cohere, Mistral и Perplexity. Также поддерживаются облачные платформы -- Azure AI Foundry, Amazon Bedrock, Google Cloud -- и инструменты для локального запуска: Ollama, LiteLLM, Groq, OpenRouter, Together AI, Fireworks. Это делает Pydantic AI агностическим к провайдеру: один и тот же код агента работает с любой из поддерживаемых моделей без существенных изменений.

Ключевое нововведение V2 -- концепция capabilities (возможностей) как основного примитива. Capabilities -- это переиспользуемые модули, которые объединяют инструменты агента (tools), хуки (hooks), инструкции (instructions) и настройки модели в один компонентный блок. Вы можете встроить в агента готовую capability для веб-поиска, встроить готовый MCP-сервер, подключить capability из библиотеки сообщества или написать собственную. Это фундаментально меняет архитектуру агентных приложений: вместо монолитного кода -- модульная, переиспользуемая система.

Для кого предназначен Pydantic AI: для Python-разработчиков, которые создают продакшн AI-агентов и хотят получить всё типобезопасно, с нормальным тестированием и надёжной работой в многошаговых автономных сценариях. Это разработчики, знакомые с экосистемой Python (FastAPI, Pydantic, SQLAlchemy), которые хотят применить те же практики строгой типизации к AI-агентам. Также фреймворк подходит для команд, создающих long-running агентов -- таких, которые продолжают работу после перезапуска или временных ошибок API, благодаря встроенной поддержке durable execution.

Pydantic AI является open-source проектом и не требует регистрации или подписки. Вам нужен Python 3.9 или новее и pip-менеджер пакетов.

Шаг 1 -- установка базового пакета. Откройте терминал и выполните команду: pip install pydantic-ai. Это установит базовый пакет без конкретных провайдеров. Для запуска агентов вам также потребуются зависимости под конкретного провайдера: pip install pydantic-ai[openai] для OpenAI, pip install pydantic-ai[anthropic] для Claude, pip install pydantic-ai[google-vertex] для Google Gemini. Все доступные экстра-зависимости перечислены в официальной документации на pydantic.dev.

Шаг 2 -- настройка API-ключей. Задайте переменные окружения для нужных провайдеров. Для OpenAI: export OPENAI_API_KEY="sk-...". Для Anthropic: export ANTHROPIC_API_KEY="sk-ant-...". Для Gemini: export GOOGLE_API_KEY="...". Рекомендуем использовать файл .env совместно с библиотекой python-dotenv для управления ключами в разработке, и переменные окружения или секреты менеджера секретов для продакшна.

Шаг 3 -- установка Pydantic Logfire (опционально, но рекомендуется). Pydantic AI тесно интегрирован с Pydantic Logfire -- платформой наблюдаемости на базе OpenTelemetry. Установите: pip install logfire. Logfire предоставляет трассировку вызовов модели, мониторинг расходов на токены, историю диалогов агентов и отладку в реальном времени. Для разработки и отладки AI-агентов это незаменимый инструмент. Logfire предлагает бесплатный план для разработчиков.

Шаг 4 -- проверка установки. Создайте файл test_agent.py со следующим содержимым: импортируйте Agent из pydantic_ai, создайте экземпляр агента с нужной моделью и выполните простой synchronous run. Если агент вернул ответ без ошибок импорта -- установка прошла успешно. В случае ошибок зависимостей проверьте совместимость версий Python и убедитесь, что установили нужные экстра-зависимости для выбранного провайдера.

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

Пример 1 -- минимальный агент. Создайте экземпляр Agent с указанием модели: agent = Agent(model='openai:gpt-4o'). Выполните синхронный запрос: result = agent.run_sync('Объясни концепцию MoE-архитектур за три предложения'). Распечатайте результат: print(result.output). Обратите внимание, что result.output -- это строка с ответом, а result.usage содержит информацию о потреблённых токенах. Всё типизировано -- IDE подскажет доступные атрибуты.

Пример 2 -- агент с инструментами (tool use). Добавьте к агенту Python-функцию как инструмент с помощью декоратора @agent.tool. Функция принимает контекст запроса (RunContext) и аргументы, возвращает результат. Агент сам решает, когда вызвать инструмент и с какими аргументами, на основе инструкций системы и содержания диалога. Pydantic AI автоматически генерирует схему JSON Schema из типизированных аргументов функции и передаёт её в модель.

Пример 3 -- структурированный вывод. Определите Pydantic-модель (класс BaseModel) для описания ожидаемой структуры ответа. Передайте её как output_type при создании агента. Pydantic AI заставит модель вернуть данные именно в этой структуре, проверит типы и вернёт вам уже готовый типизированный Python-объект -- без ручного парсинга JSON и без ошибок несоответствия типов. Это особенно ценно при обработке результатов в последующем коде.

Пример 4 -- агент с встроенным веб-поиском. В Pydantic AI V2 появились встроенные capabilities, включая веб-поиск. Подключите capability: from pydantic_ai.capabilities import WebSearchCapability. Добавьте её к агенту при инициализации. Теперь агент может самостоятельно искать актуальную информацию в интернете в процессе ответа на вопросы пользователя -- без дополнительного кода с вашей стороны.

Пример 5 -- тестирование агента. Pydantic AI разработан с учётом тестируемости. Используйте FakeModel (встроенный мок-провайдер) для тестирования логики агента без реальных API-вызовов и расходов токенов. Это позволяет писать юнит-тесты для агентов так же, как вы тестируете обычный Python-код: быстро, воспроизводимо и бесплатно.

Capabilities как основной примитив V2. Главное архитектурное нововведение V2 -- capabilities. Это переиспользуемые модули, которые инкапсулируют набор инструментов (tools), хуки жизненного цикла агента (hooks), системные инструкции (instructions) и настройки модели в один логичный компонентный блок. Capabilities можно добавлять к агенту при инициализации, переиспользовать в разных агентах, брать из библиотеки сообщества или устанавливать как отдельные pip-пакеты. Это принципиально меняет модульность агентного кода.

Поддержка всех крупных провайдеров. Pydantic AI V2 работает с OpenAI, Anthropic, Google Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, Groq, Azure AI, Amazon Bedrock, Ollama, LiteLLM, OpenRouter, Together AI и Fireworks. Один и тот же код агента запускается с любым провайдером -- достаточно изменить строку инициализации модели. Это особенно ценно при сравнении провайдеров по качеству ответов или переключении на альтернативу при изменении цен.

Типобезопасность и IDE-поддержка. Pydantic AI использует систему типов Python на всех уровнях: аргументы инструментов, входные данные агентов, структуры вывода -- всё полностью типизировано. Ваша IDE видит все доступные методы и атрибуты, предупреждает о несовместимости типов ещё до запуска, а статический анализатор mypy или pyright находит потенциальные ошибки на этапе разработки. Это резко снижает время отладки по сравнению с фреймворками, где всё передаётся через словари.

Durable agents для long-running задач. Pydantic AI поддерживает агентов с сохранением состояния через временные сбои API и перезапуски приложения. Это критически важно для реальных продакшн-сценариев: если агент выполняет длительную многошаговую задачу и происходит сетевая ошибка или плановый рестарт сервиса -- агент продолжит работу с места остановки, а не начнёт заново. Также поддерживаются сценарии human-in-the-loop: агент может приостановиться, запросить подтверждение у человека и продолжить работу после одобрения.

Встроенная интеграция с Pydantic Logfire. Pydantic AI имеет нативную интеграцию с платформой наблюдаемости Logfire на базе OpenTelemetry. Это даёт: трассировку каждого вызова модели, мониторинг стоимости и потребления токенов, историю агентных диалогов, мониторинг производительности и аномалий. Для команд, выводящих AI-агентов в продакшн, наблюдаемость -- не опция, а необходимость, и Pydantic AI делает её настройку тривиальной.

MCP-совместимость. Pydantic AI V2 поддерживает протокол Model Context Protocol (MCP) -- открытый стандарт Anthropic для передачи контекста между инструментами и языковыми моделями. Это означает возможность подключения любых MCP-совместимых инструментов и серверов к агенту как встроенных capabilities без написания адаптеров вручную.

Pydantic AI является полностью бесплатным open-source проектом, доступным на GitHub под лицензией MIT. Сам фреймворк ничего не стоит -- вы платите только за использование API конкретных LLM-провайдеров (OpenAI, Anthropic, Google и других) в соответствии с их тарифами.

Pydantic Logfire, встроенная платформа наблюдаемости, предлагает бесплатный план для индивидуальных разработчиков и открытых проектов. Платные планы для команд и предприятий включают расширенные лимиты хранения логов, права доступа и приоритетную поддержку. Конкретные цены на момент написания уточняйте на сайте logfire.pydantic.dev -- тарификация может меняться.

Технические требования: Python 3.9 или новее. Совместимость с asyncio -- все методы агентов доступны в синхронной (run_sync) и асинхронной (run) версии. Pydantic AI V2 содержит breaking changes по сравнению с V1 -- конкретный перечень изменений и миграционное руководство опубликованы в официальной документации на pydantic.dev. Если вы уже используете Pydantic AI V1, рекомендуем ознакомиться с changelog перед обновлением, так как API capabilities существенно переработан.

Ограничения: Pydantic AI -- это низкоуровневый фреймворк, ориентированный на Python-разработчиков. Он не предоставляет готового UI или no-code интерфейса. Для построения сложных мультиагентных систем с визуальным редактором рассмотрите LangGraph или CrewAI -- более высокоуровневые решения, хотя и с меньшей типобезопасностью. Pydantic AI сильнее всего именно в типобезопасности и тестируемости, а не в высокоуровневых абстракциях оркестрации.

Pydantic AI -- это библиотека Python с открытым исходным кодом. Сам пакет устанавливается через PyPI (pip), доступный в России без ограничений. GitHub, где размещён исходный код проекта, также работает в России. VPN для установки и работы с самим фреймворком не нужен.

Отдельный вопрос -- доступность AI-провайдеров, которые вы планируете использовать совместно с Pydantic AI. OpenAI (ChatGPT, GPT-4o) официально не работает с российскими пользователями с марта 2022 года. Anthropic (Claude) также ограничивает доступ из России. Google Gemini доступен с российских IP, однако оплата может потребовать зарубежной карты.

Практическое решение для разработчиков из России: используйте Pydantic AI совместно с провайдерами, доступными без VPN. DeepSeek API работает в России напрямую. Ollama для локального запуска open-source моделей (Hy3, GLM-5.2, Qwen 3.6) не требует ни VPN, ни API-ключей. Groq предлагает быстрый API без явных региональных ограничений. OpenRouter доступен из России для чтения каталога и бесплатных квот. Для всех перечисленных Pydantic AI обеспечивает первоклассную поддержку через соответствующие модели провайдеров.

Для работы с OpenAI или Anthropic через Pydantic AI из России потребуется VPN с американским или европейским сервером. Технически это работает без проблем -- Pydantic AI не привязан к конкретному региону и не проверяет IP-адрес клиента. Выбор провайдера и решение вопросов с VPN остаётся на вашей стороне.

Этот материал подготовлен командой AI-агентов AravanaAI и проверен главным редактором.