Как выбрать фреймворк для AI Agent: разбор

Сценарий уже работает в PoC, но после добавления инструментов появляются нестабильные вызовы, потеря состояния и непонятный процесс восстановления.

Быстрое решение: сначала определите, насколько процесс детерминирован и сколько состояния он должен хранить, затем выбирайте между лёгким SDK, workflow-фреймворком и multi-agent архитектурой — а до production проверяйте трассировку, восстановление и границы прав.

Эта статья предназначена для разработчиков, которые начинают новый проект с AI Agent, технических руководителей, переводящих PoC в рабочую систему, и команд, уже столкнувшихся с перегруженным фреймворком или нестабильным использованием инструментов.

Нужен ли вашему проекту отдельный фреймворк для AI Agent?

Первый вопрос при выборе — не «какой фреймворк самый популярный», а «какую часть работы действительно нужно делегировать рантайму».

Разделите проект на четыре типа:

1. Одиночный вызов модели. Вы передаёте контекст, получаете структурированный ответ и сами контролируете весь код. Для классификации, извлечения полей, суммаризации или генерации черновика обычно достаточно API-клиента и обычных функций.
2. Ассистент с инструментами. Модель выбирает функцию, получает результат и продолжает диалог. Здесь уже полезен AI Agent Framework, если вам нужны единая схема аргументов, обработка ошибок и журнал вызовов.
3. Состоящий из шагов workflow. Процесс имеет ветвления, ожидание подтверждения, повторный запуск или длительное выполнение. В таком случае важнее не «умность» агента, а сохранение состояния, контроль переходов и восстановление после сбоя.
4. Автономный или multi-agent процесс. Несколько специализированных агентов распределяют роли, передают друг другу задачи или работают с разными наборами прав. Такой подход оправдан только тогда, когда разделение действительно уменьшает сложность, а не добавляет новые каналы коммуникации.

Если задача решается обычной функцией или заранее описанным workflow, не добавляйте агентный рантайм только ради модного термина. Дополнительный слой приносит стоимость отладки: нужно тестировать промпты, выбор инструмента, формат аргументов, повторные вызовы и завершение цикла.

У вас уже есть признаки необходимости фреймворка, если:

• выполнение длится дольше одного запроса;
• модель должна выбирать между несколькими действиями;
• требуется ручное подтверждение опасной операции;
• пользователь может вернуться к незавершённой задаче;
• после сбоя нужно продолжить работу, а не начинать всё заново;
• действия должны быть видны в трассировке и доступны для аудита.

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

Как выбрать фреймворк для AI Agent по уровню абстракции?

Лёгкий SDK, workflow-фреймворк и multi-agent фреймворк решают разные проблемы. Сравнивать их по количеству интеграций некорректно: главным критерием должна быть цена контроля.

Лёгкий SDK

Лёгкий SDK подходит, если команда хочет сохранить обычный Python-код, сама управлять циклом выполнения и не нуждается в сложной долговременной оркестрации.

Преимущества:

• короткий путь от функции до инструмента;
• проще читать и тестировать код;
• легче заменить модель или провайдер;
• меньше скрытой магии;
• удобнее начать с одного агента.

Например, OpenAI Agents SDK предоставляет примитивы для агентов, function tools, handoffs, guardrails, сессий и трассировки. Официальная документация отдельно подчёркивает, что SDK рассчитан на небольшое количество базовых абстракций и Python-first оркестрацию. (документация OpenAI Agents SDK)

Недостатки:

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

SDK — хороший выбор для внутреннего помощника, API-обёртки над несколькими функциями или первого production-сервиса с ограниченным количеством сценариев.

Workflow-фреймворк

Workflow-фреймворк нужен, когда важна не только модель, но и предсказуемая последовательность действий. В такой архитектуре агент может принимать локальные решения, однако общий маршрут задаётся кодом или графом.

Сильные стороны:

• явные переходы между шагами;
• контроль ветвлений и условий;
• сохранение состояния;
• возможность остановить процесс для ручного решения;
• удобная модель повторного запуска.

LangGraph, например, описывает себя как инфраструктуру для длительных и stateful-приложений. В документации указаны durable execution, human-in-the-loop и persistence, а функциональный API позволяет добавлять эти возможности к обычным функциям без обязательной перестройки всей программы в граф. (документация LangGraph)

Цена такого контроля — более сложная модель исполнения. Разработчикам необходимо понимать, где создаётся checkpoint, какой идентификатор связывает запуски, какие действия безопасно повторять и где можно вмешиваться вручную.

Workflow-фреймворк обычно оправдан для обработки заявок, финансовых согласований, многошагового research-процесса, CI/CD-автоматизации и других задач, где сбой на последнем шаге не должен обнулять результаты предыдущих.

Multi-agent фреймворк

Multi-agent подход стоит вводить, если у системы есть действительно разные роли, права, контексты или критерии качества. Само наличие нескольких этапов ещё не означает, что нужны несколько агентов.

Плюсы:

• разделение специализированных инструкций;
• разные инструменты и разрешения для разных ролей;
• возможность изолированно тестировать специалистов;
• поддержка маршрутизации и делегирования.

Минусы:

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

В руководстве AutoGen прямо рекомендуется начинать с одного агента и переходить к команде только после того, как одиночный агент с подходящими инструментами оказался недостаточным. Там же указано, что команды требуют дополнительного управляющего каркаса. (руководство AutoGen по командам агентов)

Следовательно, multi-agent фреймворк становится разумным выбором, когда специалист по поиску, специалист по проверке и специалист по изменению данных имеют разные границы ответственности. Если же три агента просто по очереди переписывают один и тот же ответ, архитектура, скорее всего, избыточна.

Где инструменты превращаются из преимущества в риск?

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

Проверяйте для каждого инструмента пять свойств.

1. Схема аргументов

Поля должны иметь строгие типы, описание допустимых значений и ограничения. Для операции изменения заказа недостаточно параметра id; нужно определить формат идентификатора, допустимые статусы и правила проверки владельца записи.

OpenAI Agents SDK поддерживает автоматическое создание схемы function tools и валидацию аргументов через Pydantic. В документации также описаны отдельные параметры для тайм-аутов и обработки ошибок инструментов. (справка по инструментам OpenAI Agents SDK)

2. Тайм-аут и повтор

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

Например, повторный запрос на чтение обычно безопаснее, чем повторное списание средств или создание заявки. Если фреймворк автоматически повторяет все ошибки одинаково, это не готовая production-функция, а потенциальный источник дублей.

3. Одобрение и права

Инструмент, который отправляет письмо, изменяет базу данных или запускает shell-команду, должен иметь отдельную политику доступа. Нельзя полагаться только на системный промпт.

В OpenAI Agents SDK tool guardrails выполняются вокруг function tools: проверки могут сработать до вызова, после него или остановить операцию через tripwire. При этом guardrails агента и guardrails инструмента действуют на разных уровнях, поэтому проверка только финального ответа не заменяет контроль каждого опасного действия. (документация по guardrails)

4. Логирование

В журнале должны сохраняться:

• идентификатор запуска;
• имя агента;
• выбранный инструмент;
• нормализованные аргументы;
• результат или тип ошибки;
• длительность;
• решение о повторе или ручном подтверждении.

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

5. Параллельность

Параллельные вызовы полезны для независимых операций, но опасны для инструментов с побочными эффектами. В документации AutoGen отдельно отмечено, что при использовании AgentTool или TeamTool параллельные вызовы необходимо отключать, поскольку агенты и команды сохраняют внутреннее состояние, которое может конфликтовать. (руководство AutoGen по агентам)

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

Расширяемость фреймворка определяет срок жизни архитектуры

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

Разделите расширяемость на два уровня.

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

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

Перед выбором задайте команде следующие вопросы:

• Можно ли использовать другую модель без изменения формата всего workflow?
• Где хранится состояние и можно ли заменить это хранилище?
• Можно ли перехватить каждый вызов инструмента?
• Есть ли middleware или lifecycle hooks?
• Можно ли ограничить набор инструментов для отдельного агента?
• Как добавляется собственный тип события в трассировку?
• Можно ли запустить workflow вне встроенного сервера?
• Что произойдёт при обновлении основной версии?

Если ответы находятся только в исходном коде или в обсуждениях сообщества, учитывайте это как технический риск. Сверяйте обещания с официальной документацией, API Reference и журналом изменений. Для инфраструктурной части заранее изучите описание среды и инфраструктуры Kvmjet, особенно если агент должен работать постоянно, а не только на ноутбуке разработчика.

Как проверить production environment deployment до запуска?

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

Шаг 1. Опишите границы задачи

Зафиксируйте вход, ожидаемый результат, разрешённые инструменты и условия остановки. Если команда не может описать задачу обычной схемой состояний, рано переходить к multi-agent архитектуре.

Шаг 2. Разделите действия на безопасные и опасные

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

Шаг 3. Назначьте идентификатор выполнения

Каждый запуск должен иметь устойчивый run_id или эквивалентный идентификатор. Для stateful workflow нужен также ключ состояния пользователя или задачи. В LangGraph thread_id используется для загрузки и сохранения checkpoint; без него система не сможет корректно возобновить выполнение после interrupt. (документация LangGraph по persistence)

Шаг 4. Проверьте сбой инструмента

Имитируйте тайм-аут, неправильный ответ API, истёкший токен и частично выполненную операцию. Для каждого случая определите: повторить, завершить с ошибкой, передать человеку или продолжить с последнего безопасного шага.

Шаг 5. Проверьте восстановление процесса

Перезапустите worker между двумя шагами и убедитесь, что уже выполненные действия не запускаются повторно. Это особенно важно для операций с внешними побочными эффектами. LangGraph предупреждает, что при replay шаги после checkpoint выполняются заново, включая LLM-вызовы, API-запросы и interrupt, поэтому повторяемые действия должны быть спроектированы с учётом этого поведения. (документация LangGraph по durable execution)

Шаг 6. Проверьте ручное вмешательство

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

Шаг 7. Проверьте наблюдаемость

В трассировке должны быть видны модель, инструменты, handoff, guardrails, ошибки и итоговое состояние. OpenAI Agents SDK включает трассировку событий запуска, включая генерации модели, вызовы инструментов, handoffs и guardrails. (документация по трассировке OpenAI Agents SDK)

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

Чек-лист выбора кандидата

Оставьте не более двух финальных кандидатов и прогоните их через один и тот же отказоустойчивый сценарий.

• [ ] Я могу решить задачу обычными функциями; если да, фреймворк не добавляется без отдельного обоснования.
• [ ] Я определил, требуется ли только цикл tool calling или полноценный workflow.
• [ ] Для каждого инструмента описаны типы аргументов, тайм-аут, повтор и права.
• [ ] Опасные действия требуют подтверждения независимо от текста промпта.
• [ ] Есть устойчивый идентификатор запуска и состояние, доступное после перезапуска.
• [ ] Повторный запуск не создаёт дубли внешних операций.
• [ ] Ошибки модели, API и бизнес-логики различаются.
• [ ] Трассировка позволяет найти конкретный неудачный шаг.
• [ ] Multi-agent режим добавляет разные роли, а не просто больше сообщений.
• [ ] Модель, хранилище и исполнитель инструментов можно заменить через публичный интерфейс.
• [ ] Команда способна протестировать выбранную абстракцию на своём языке и в своей системе сборки.
• [ ] Кандидат прошёл тест с тайм-аутом, ручным подтверждением и восстановлением.

Условия проекта	Предпочтительный вариант	Когда отступить к более простому решению
Короткий запрос, один-два инструмента, состояние не сохраняется	Лёгкий SDK или обычный API-клиент	Если появились повторные запуски и ручные approval
Несколько ветвлений, длительный процесс, обязательное восстановление	Workflow-фреймворк	Если ветвления фактически детерминированы и проще описываются функциями
Разные роли, права, контексты и независимые специалисты	Multi-agent фреймворк	Если один агент с хорошими инструментами решает задачу без потери качества
Жёсткий аудит, ручное вмешательство и внешние побочные эффекты	Workflow с persistence, tracing и approval gates	Если команда не готова поддерживать состояние и тесты отказов

Если текущая реализация держится на ноутбуке одного разработчика, ручном перезапуске и незафиксированных переменных окружения, это слабая база для долгоживущего агента. Локальная среда удобна для первых экспериментов, но ограничивает постоянную доступность, совместную отладку и контролируемое восстановление. В таком случае аренда Mac-среды Kvmjet может быть практичнее для временного тестового контура: вы сохраняете доступ к реальной среде, не покупаете отдельное устройство под короткий проект и можете заранее проверить требования к непрерывной работе. Доступные варианты размещения можно сопоставить на странице заказа Mac-узлов Kvmjet.

Не выбирайте самый крупный фреймворк заранее. Для короткого tool-calling цикла берите SDK, для состояния и восстановления — workflow-уровень, а multi-agent добавляйте только после доказательства, что один агент не справляется. Затем проведите единый тест отказа, подтвердите права и трассировку — и только после этого переносите AI Agent в production.