Как сделать поведение ИИ‑агента предсказуемым: управляемый рантайм вместо чёрного ящика

Почему ИИ‑агент ведёт себя как чёрный ящик

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

Такое явление называют black box, то есть чёрный ящик. Мы отправляем что-то агенту, он как-то выполняет задачу, и мы получаем результат, в котором сами не уверены и от которого даже не знаем, чего ждать.

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

Какие три вопроса задаёт чёрный ящик

Непрозрачность агента сводится к трём вопросам, на которые нет ответа:

• «Что сделал агент?» От запуска к запуску результаты получались разными.
• «Почему результат изменился?» Мы не отслеживали путь агента, поэтому не понимаем, почему сейчас он принял одно решение, а в прошлый раз — другое.
• «Сколько это стоит?» Агенты потребляют токены. Если запуски и число вызовов инструментов сильно отличались, потребление токенов становится нестабильным и спрогнозировать бюджет невозможно.

Чем непрозрачность агента опасна в продакшене

Непрозрачность превращается в операционную проблему, которую можно свести к четырём пунктам:

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

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

Что лечить: не модель, а контур вокруг неё

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

Дальше — как это выглядит на конкретном примере.

Пример: агент, который собирает презентации

Разберём подход на агенте для сборки презентаций с помощью Code Interpreter. Это именно агентская система, а не просто модель: у неё есть инструменты, которые помогают собирать презентацию.

Роли распределяются так:

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

Как устроено окружение агента

Окружение агента для сборки презентаций можно поделить на шесть слоёв:

Здесь всё держится на детерминированной сборке: она не отличается от запуска к запуску. Как презентация собиралась в первый раз, ровно так же она соберётся во второй, третий и десятый.

Слои System и Skill: роль, ToV, workflow

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

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

Финал — workflow и правила. Важно, чтобы агент выполнял цепочку ровно по запланированным шагам:

• цель презентации →
• story arc (как выглядит повествование) →
• спецификация (все слайды) →
• построение →
• QA (проверка, что шрифты не налезают друг на друга, а блоки расставлены симметрично) →
• файл презентации.

Почему готовые Python^®‑скрипты экономят токены

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

Именно поэтому Builder и Helpers — заранее подготовленные Python‑файлы. Строчки этого кода не попадают в контекст языковой модели: Code Interpreter просто запускает готовые скрипты. Если бы файлов не было, модель сначала генерировала бы код, раздувала контекст, потом запускала его — код, скорее всего, не заработал бы, она запускала бы его повторно, и цикл мог застрять надолго.

Чтобы воспользоваться Builder, языковой модели достаточно заполнить словарь. В нём есть спецификация с темой и список слайдов. Внутри каждого слайда указывается его тип, заголовок, при необходимости — подзаголовок и шаги сборки. Агент при этом не читает исходники, а заготовленные скрипты запускаются без большого потребления токенов.

Что делают слои Helpers и Builder

Helpers проверяет нужные агенту ресурсы: существование скрипта сборки, наличие тем, каталог изображений и их количество. Две вспомогательные функции по понятному ID сразу возвращают путь к нужному изображению.

Builder — самый важный слой. Словарь, который заполнила модель (имя файла, тема, перечень слайдов), подставляется параметром в функцию build_from_spec. Она проверяет обязательные поля, выбирает расположение под тип слайда, применяет тему и типографику, выстраивает график, изображение и таблицу, проверяет и сохраняет файл. Получается короткая цепочка: спецификация → вызов функции → готовая презентация.

Откуда агент берёт стиль: бренд и ассеты

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

Слой ассетов нужен, чтобы агент понимал каталог изображений. У каждого изображения есть ID, понятный языковой модели, и соответствующий путь в окружении. Прочитав ID, модель по контексту понимает, что за изображение лежит в файле и на какой слайд его уместно подложить.

Агент с настроенным окружением и без него

Чтобы проверить, насколько важно окружение, на вебинаре мы собрали агента, у которого всё настроено, а затем повторили всё то же самое, удалив скиллы и настроенные файлы.

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

В Code Interpreter загрузили все подготовленные файлы, 20 штук: дизайн-гид, всё про бренд и ассеты, референсы спецификации, Python‑файлы и изображения.

Первым вызвали Code Interpreter, и в нём оказался не большой Python‑файл со сборкой, а та самая спецификация, где для каждого слайда прописаны тип, заголовок, подзаголовок, контент и картинка. В выводе были ошибки: где-то длинный текст не помещался на слайд или налезал на блок. Builder это проверил и сократил контент, а агент перепроверил вёрстку и предложил более короткую версию.

В токенах при этом было заметно большое потребление на инструментах (их вызывали много раз), но число исходящих токенов скромное: цепочка выполнялась ровно по плану, без лишнего пространства для размышлений.

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

Подробнее об этом эксперименте смотрите в записи вебинара.

Как измерить предсказуемость: метрики эксперимента

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

• время выполнения;
• потребление токенов;
• число вызовов инструментов.

В эксперименте менялся только контур управления — системная инструкция и ресурсы среды. Модель, запросы, выходные файлы и лимиты оставались одинаковыми: один и тот же промпт, один и тот же input, одна и та же конфигурация. Запускать такой цикл удобно через код и Responses API, совместимый с OpenAI API: в запросе достаточно указать ID агента, собранного в интерфейсе, и он обратится к нужной конфигурации.

Что показали 10 запусков

По каждой метрике смотрели на медиану и на то, насколько сильно запуски от неё отклоняются:

Здесь важно сделать оговорку про токены. У настроенного агента медиана выше, потому что мы добавляем в контекст все файлы и большие инструкции вместе со скиллом. Но 135,5 тыс. в базовой конфигурации — это всего один запуск. А дальше выясняется, что нужно переделать первый и третий слайды, а то и всю презентацию, и модель просят перегенерировать снова и снова. Эти запуски складываются — и суммарное потребление выходит больше, чем у настроенного агента, который сразу выдаёт редактируемый и почти готовый результат.

Итоговые отклонения от медианы:

Как рождалось окружение: от повторов к ресурсам

Skill и настройка окружения появились не сразу. Сначала мы сделали агента без настройки — с одним «голым» Code Interpreter. Потом смотрели, где процесс повторяется, и выносили такие места в отдельные ресурсы. Логика простая: повторяющееся решение модели — кандидат на ресурс окружения.

• Каждый запуск оказывался новым маршрутом агента, даже при одинаковом запросе, — так появился Skill, который фиксирует workflow и правила.
• Повторный поиск файлов и среды при загрузке изображений — так появился Helpers, возвращающий готовые пути и ресурсы.
• Точечные правки после сборки — так появился Builder, который проверяет спецификацию и собирает всё за один проход.
• Стиль и визуалы выбирались заново — так появились Brand и Assets, задающие дизайн‑систему и каталог.

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

Как читать поведение агента: трейсы

Все эти выводы мы получили не наугад. В Yandex AI Studio есть инструмент трейсов: по каждому запросу видно всю цепочку агента: какие действия он выполнял, какие инструменты вызывал и сколько токенов потреблял. Для этого во вкладке логирования подключаются трейсы, затем выбирается сервис Yandex AI Studio, при необходимости — конкретный инструмент и период.

Для более детального анализа трейсы можно открыть в платформе Yandex Monium — и увидеть системный промпт, вызовы инструментов и отдельные шаги, посчитанные в токенах. Можно, например, посмотреть, сколько токенов ушло на проверку наличия всех файлов: если их слишком много, шаг стоит переписать скромнее. У настроенного агента файлы в контексте структурированы и аккуратны, поэтому он не тратит лишние вызовы и токены на их поиск.

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

Как считать экономику агента

Токены — основной драйвер потребления. Модель принимает промпт (это токены), генерирует ответ (тоже токены, и он тарифицируется). И ещё один нюанс: у каждого подключённого инструмента есть описание и название, чтобы модель поняла, когда его вызывать, — и это тоже стоит токенов. Плюс некоторые инструменты имеют платные вызовы.

Ещё один совет: закладывайте в экономику повторные запуски. Вы можете посчитать стоимость одной презентации, но не учесть, что сотрудник или клиент останется недоволен и попросит перегенерировать отдельные слайды. Есть и понятие кешированных токенов: в таблице тарификации Yandex AI Studio они учитываются иначе, а модель с ними работает быстрее. Но стоимость они не «разгоняют».

Считать экономику удобно в личном кабинете с биллингом. В детализации можно выбрать вкладку по сервисам, отметить Yandex AI Studio и выгрузить детализацию в CSV для дальнейшей обработки скриптами или визуального анализа.

Сколько стоила презентация

По результатам эксперимента одна презентация стоила 23,3 рубля в настроенном окружении и 38,8 рубля в базовой конфигурации. Разница примерно 40%.

Частые вопросы

Что в итоге

Ключевые выводы:

• Непредсказуемость агента лечится не сменой модели или промпта, а настройкой контура вокруг неё: контракта, среды, трейсов и метрик.
• Заранее подготовленные Python‑скрипты (Helpers и Builder) убирают из контекста лишний код и делают сборку детерминированной — одинаковой от запуска к запуску.
• Повторяющееся решение модели — сигнал вынести его в отдельный ресурс окружения.
• Трейсы показывают каждый шаг агента и потребление токенов — это основа и для отладки, и для оценки экономики.
• Настроенное окружение сокращает разброс по времени, вызовам и токенам, а вместе с ним — и разброс стоимости.
• Управляемый рантайм — это не ограничение свободы модели, а условие её промышленной эксплуатации.