PydanticAI

1. Обзор концепции и системная проблема

Первая волна библиотек для работы с языковыми моделями создавалась в эпоху быстрого прототипирования: они полагались на вложенные динамические классы, нетипизированные словари, невидимые промпты и сложное наследование. В продакшен-бэкенде это создавало катастрофические трудности:

1. Отсутствие автодополнения и рефакторинга: IDE не понимает, какие поля возвращает агент, а изменение названия одного свойства ломает код в рантайме без предупреждений.
2. Сложности с тестируемостью: Невозможно изолировать агентскую логику от внешних сервисов или подменить базу данных тестовым моком из-за отсутствия нормального Dependency Injection.
3. Ненадежная обработка ошибок структуры: Модели часто пропускают обязательные поля или путают типы (например, строка вместо числа), что приводит к падению API.

PydanticAI от Самуэля Колвина (автора Pydantic) возвращает разработку агентов в русло классической, чистой софтверной инженерии: это типобезопасный, минималистичный и быстрый каркас, построенный на стандарте Pydantic v2.

2. Архитектурная таксономия и ментальная модель

Архитектура PydanticAI базируется на четырех концептуальных столпах:

• 1. Параметризованный агент (Agent[Deps, ResultType]): Агент явно типизируется двумя параметрами: типом контекстных зависимостей (Deps), которые ему нужны для работы, и типом конечного результата (ResultType). Если результат — модель Pydantic, агент гарантированно вернет валидированный экземпляр класса.
• 2. Контекст выполнения и DI (RunContext[Deps]): Механизм инъекции зависимостей. Каждый инструмент и динамический промпт получают доступ к ctx.deps, где хранятся активные соединения с базой данных, конфигурация или информация о правах пользователя.
• 3. Типизированные инструменты (@agent.tool): Функции Python, аргументы которых автоматически транслируются в JSON Schema для LLM. Описания аргументов берутся из Type Hints и docstrings.
• 4. Динамические системные промпты (@agent.system_prompt): Асинхронные функции, которые формируют системную инструкцию «на лету» на основе переданных зависимостей (например, подставляя актуальный баланс пользователя или часовой пояс).

3. Технический пайплайн и внутренняя механика

Жизненный цикл выполнения запроса в PydanticAI:

1. Instantiation & Context Binding (Сборка контекста): При вызове agent.run(prompt, deps=my_deps) фреймворк инициализирует RunContext и резолвит все функции, помеченные декоратором @agent.system_prompt.
2. Schema Generation & Model Inference (Вызов модели): Типы аргументов инструментов и финальный ResultType конвертируются в строгие JSON-схемы через движок Pydantic Core (написанный на Rust, что обеспечивает микросекундную скорость).
3. Tool Invocation with Self-Correction (Валидация и исправление): Когда модель возвращает вызов тула, входные аргументы прогоняются через валидатор Pydantic. Если валидация не прошла (например, передано отрицательное число там, где ожидается PositiveInt), PydanticAI не выбрасывает исключение, а автоматически отправляет модели сообщение: «Ошибка валидации поля X: ожидалось значение > 0. Попробуй еще раз».
4. Structured Output Serialization & Streaming (Возвращение результата): Финальный ответ десериализуется в целевой объект Python. Поддерживается метод run_stream(), который позволяет транслировать частично сформированные поля объекта клиенту в реальном времени.

4. Практические инженерные сценарии в продакшене

01. Нативные агенты внутри FastAPI

Совместное использование моделей: одна и та же схема InvoiceExtractionResponse используется как выходная схема PydanticAI, как response_model в эндпоинте FastAPI и для автоматической генерации клиентского TypeScript-типа через OpenAPI.

02. Безопасная работа с транзакциями базы данных

Через RunContext в тули прокидывается транзакционная сессия AsyncSession SQLAlchemy. Агент может выполнять проверки и записывать данные. Если на финальном этапе произошла ошибка, внешний менеджер контекста откатывает транзакцию, предотвращая сохранение полусырых данных.

03. Стриминг структурированных интерфейсов (Generative UI)

Агент генерирует динамический дашборд. Благодаря поддержке валидации потока PydanticAI фронтенд может рендерить графики и карточки еще до того, как модель завершила формирование полного JSON-документа.

5. Подводные камни, типовые ошибки и безопасность

• Отсутствие описаний полей (Field(description=...)): Модель формирует вызов, опираясь исключительно на имена и описания полей. Если поле названо неоднозначно (например, status: int), и описание отсутствует, модель регулярно будет галлюцинировать неверными значениями.
• Исчерпание попыток исправления ошибок (Max Retries Exceeded): Если схема слишком запутанная, модель может исчерпать лимит retries=3, пытаясь подогнать ответ под валидатор, что приведет к падению запроса. Упрощайте схемы или декомпозируйте их на подзадачи.
• Утечка жизненного цикла ресурсов в Deps: Убедитесь, что объекты, которые вы передаете в deps (пулы коннектов, клиенты HTTP), имеют правильное закрытие после завершения работы агента (через async with).