Двухэтапный агент с документацией под рукой: формулировка отдельно, код отдельно

ШАГ 1 (Формулировщик, без инструментов):
  описание задачи + данные → план модели: переменные, ограничения, цель
  (до 10 обращений к LLM)

ШАГ 2 (Исполнитель, с инструментами документации):
  план → поиск функций в документации → проверка → сборка кода
  (до 6 инструментов поиска/проверки, до 50 обращений к LLM)

ВЫХОД: самостоятельный Python-скрипт, который читает данные,
       строит модель, решает и выводит расписание

СРАВНЕНИЕ:
  (б) один агент делает оба шага с инструментами
  (в) один запрос к LLM, без инструментов — базовый вариант

Шаги идут как отдельные агенты (в Langflow это отдельные компоненты). В обычном чате или в Claude Code это два последовательных этапа одной задачи.

Задача: Мебельная фабрика в Подмосковье. Восемь заказов проходят четыре станка: раскрой, кромление, сверление, сборка. У каждого заказа свой порядок операций и своё время на станке. Нужно расписание, при котором все заказы закончатся как можно раньше. Это классическая «задача цеха» (job-shop). Она в сильной зоне метода: простая структура, много готовых примеров.

Промпт (для Claude Code или другого агента с доступом к документации библиотеки):

Задача: составить расписание цеха мебельной фабрики и вывести код на Python.

ЭТАП 1. Формулировка. Пока не пиши код и не трогай документацию.
Опиши модель словами и списками:
- какие переменные решения нужны;
- какие ограничения (порядок операций внутри заказа, один станок = одна операция
  одновременно, время переналадки не учитываем);
- какая целевая функция.
Покажи мне план и остановись.

ЭТАП 2. Реализация (после моего «ок»).
Используй библиотеку OR-Tools CP-SAT.
Правила:
1. Перед использованием любой функции найди её в документации
   (папка docs/ или инструмент поиска) и проверь параметры.
2. Не используй функции, которых не нашёл в документации.
3. Если скрипт упал — прочитай ошибку, найди нужную функцию в документации,
   исправь. Не больше 5 попыток.
4. Результат: один самостоятельный скрипт, который читает данные из orders.csv,
   решает задачу и печатает расписание по станкам.

ДАННЫЕ:
8 заказов: шкаф-купе (раскрой 40 мин, кромление 30, сверление 25, сборка 60),
кухня «Милан» (раскрой 90, кромление 70, сверление 50, сборка 120),
...остальные заказы в orders.csv.
Станки: раскрой — 1, кромление — 1, сверление — 1, сборка — 1.
Цель: минимизировать время окончания последнего заказа.

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

Слабость LLM. Модель пишет код по памяти. Для популярных библиотек этого хватает, для узких (солверы, специфические API) нет. Она придумывает правдоподобные названия функций и неверные аргументы. Если формулировка и код делаются одним махом, ошибка в API ломает весь результат, а проверить её нечем.

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

Как метод это использует. Разделение убирает конкуренцию двух задач за внимание: сначала только «что моделируем», потом только «как это выразить в коде». Поиск по документации превращает «вспомни» в «найди и проверь». Не нужно загружать весь справочник в контекст: агент берёт только нужные куски. Это экономит токены и снижает шум.

Рычаги управления: - Лимит итераций (у авторов 10 у формулировщика, 50 у исполнителя). Для простых задач уменьшай, для сложных увеличивай. - Инструменты исполнителя (у авторов шесть: поиск функций, примеры, проверка). Меньше инструментов — проще агенту выбирать, больше — точнее проверка. - Остановка после плана (в промпте выше). Убери, если доверяешь формулировке, оставь, если задача новая. - Жёсткое правило «только из документации» — убирает самые частые ошибки с выдуманными функциями.

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

Агент 1. Формулировщик (без инструментов):

Ты формулируешь математическую модель для задачи планирования.
Код не пиши.

ОПИСАНИЕ ПРОЦЕССА:
{описание процесса на обычном языке}

ДАННЫЕ:
{структура данных: таблицы, поля, единицы измерения}

ЦЕЛЬ:
{что минимизировать или максимизировать}

Выдай план модели в формате:
1. Переменные решения (имя, тип, область значений)
2. Ограничения (каждое — одной строкой на человеческом языке и формулой)
3. Целевая функция
4. Допущения, которые ты принял сам

Агент 2. Исполнитель (с доступом к документации):

Ты переводишь готовую формулировку модели в рабочий код.

БИБЛИОТЕКА: {название библиотеки и версия}
ФОРМУЛИРОВКА (от предыдущего этапа):
{план модели}

ИСТОЧНИК ДАННЫХ:
{файл или база данных, где лежат данные}

ПРАВИЛА:
1. Прежде чем использовать функцию, найди её в документации через
   инструмент {инструмент_поиска} и проверь параметры.
2. Не используй функции, которых нет в документации.
3. Запусти скрипт. При ошибке найди нужную функцию в документации
   и исправь. Не больше {число} попыток.
4. Результат: один самостоятельный скрипт, который читает данные,
   строит модель, решает её и печатает решение.

Что подставлять: - {описание процесса} — как работает цех, склад, смена, обычными словами; - {библиотека} — солвер или любая узкая библиотека, с которой модель работает плохо; - {инструмент_поиска} — MCP-сервер с документацией или папка с файлами документации; - {число} — лимит попыток, чтобы агент не крутился бесконечно.

🚀 Быстрый старт — вставь в чат или в Claude Code:

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

[вставить шаблон выше]

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

⚠️ Неполный текст: В доступной части статьи нет таблиц результатов. Известны только итоговые цифры из аннотации. Сравнение «один агент против двух» в деталях не видно. Нельзя сказать, какую долю успеха даёт разделение ролей, а какую — поиск по документации.

⚠️ Сложные связанные задачи: Модели с тесной связью транспорта, сборки и склада остаются открытой проблемой. Даже лучший вариант запускается сразу не всегда. Ожидайте правок руками.

⚠️ Запуск ≠ правильность: Скрипт, который запустился, может содержать неверные ограничения. Авторы отдельно измеряли точность модели и успех запуска, но на практике правильность расписания нужно проверять вам: на маленьком примере, где ответ известен.

⚠️ Нужна настройка: Авторы строили свой MCP-сервер и собирали агентов в Langflow. Читатель без программирования может повторить логику через готовые инструменты с документацией, но сами цифры к такой настройке не применимы.

⚠️ Узкая область: Проверяли один солвер (IBM CP Optimizer) на шести задачах планирования. Общий принцип «агент с документацией лучше, чем память» переносится на другие библиотеки, но статья этого не проверяла.

Авторы взяли шесть производственных задач разной сложности: поточный цех (flow-shop), цех с разным порядком операций (job-shop), гибкий цех и три варианта складской логистики с транспортом и сборкой заказов. Сравнили три схемы: два агента, один агент и один запрос к LLM без инструментов. Каждую схему прогнали на трёх разных LLM с одинаковой температурой (0,15) и одинаковыми системными промптами. Различалась только архитектура.

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

Результаты: формулировка модели современным LLM почти всегда по силам. Главная проблема в реализации. Двухагентная схема подняла долю рабочих скриптов с 14,8% до 59,3%, а на четырёх менее сложных задачах дошла до 80,6%. Инсайт для практики: ошибки идут не от «непонимания задачи», а от незнания API. Лечить их надо доступом к документации, а не более длинным промптом с условием.

🔧 Техника: убрать инструменты у первого агента → формулировка не «прилипает» к знакомым функциям

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

Экстраполяция (в статье этого нет): правило «найди в документации, прежде чем использовать» можно вписать в CLAUDE.md или AGENTS.md для любой узкой библиотеки:

## Работа с {библиотека}
- Перед вызовом любой функции {библиотеки} найди её описание в docs/{библиотека}/.
- Если функции в документации нет — не используй её, спроси меня.
- После написания кода запусти его на тестовых данных из tests/small.csv
  и сравни с ожидаемым ответом из tests/expected.txt.

Это идея, достроенная по мотивам статьи, а не проверенный авторами приём.

• Название: Agentic AI-Assisted Modeling for Production Scheduling: Assessment in Constraint Programming
• Авторы: Ángel Sánchez-Fernández, Javier Pernas-Álvarez, Diego Crespo-Pereira
• Университет: Universidade da Coruña, Campus Industrial de Ferrol, CITENI, Grupo Integrado de Ingeniería
• Инструменты из исследования: Langflow Desktop (сборка агентов), MCP-сервер документации docplex.cp (IBM ILOG CP Optimizer). Промпты и данные опубликованы в репозитории проекта (Sánchez-Fernández et al., 2026).
• Близкие работы: Szeider (2025) — MCP-архитектура для генерации CP-моделей; OptiMUS-0.3 — многоагентная схема для линейных моделей.