Практический guide
Как построить harness для повторяющегося workflow агента

Разовая задача агента часто выглядит убедительно: он нашёл страницы, извлёк данные и подготовил ответ. Но при повторном запуске меняются входы, порядок действий, число обращений к инструментам и итоговая стоимость. Чтобы превратить такую работу в управляемый процесс, нужен harness — управляющий слой, который задаёт входы, ограничивает шаги, проверяет результат и сохраняет журнал выполнения.
В этой статье соберём минимальную конструкцию harness для workflow, который извлекает сведения с веб-страниц. Цель не в том, чтобы сделать агента полностью автономным. Цель — сделать его поведение наблюдаемым, воспроизводимым и сопоставимым между запусками.
Что именно должен контролировать harness
У повторяющегося workflow есть пять разных объектов контроля:
- Входы: что именно подаётся агенту и в каком формате.
- Шаги: какие действия разрешены и в каком порядке.
- Завершение: по какому проверяемому условию работа считается оконченной.
- Лимиты: сколько времени, шагов, страниц и вызовов инструментов разрешено.
- Журнал: какие страницы действительно были открыты и что из них извлечено.
Если хотя бы один из этих элементов не определён, сравнивать запуски трудно. Например, увеличение стоимости может быть связано не с моделью, а с тем, что агент стал открывать вдвое больше страниц из-за неясного критерия остановки.
Шаг 1. Опишите вход как данные, а не как просьбу
Начните с контракта входа. Не передавайте агенту длинное неструктурированное описание, если задачу можно представить набором полей. Пример входного объекта:
{
"task_id": "example-001",
"start_url": "https://example.org/catalog",
"target": "найти карточки товаров",
"fields": ["name", "url", "availability"],
"max_pages": 10,
"max_steps": 30,
"timeout_seconds": 180
}
Это пример схемы, а не утверждение о конкретном сайте или реальном результате. Важны явные поля: стартовая страница, требуемые поля и ограничения. Для каждого поля заранее определите тип и допустимое отсутствие значения. Например, если цена не найдена, журнал должен содержать null и причину, а не молча пропускать запись.
Полезное правило: вход должен быть достаточным для запуска без дополнительных вопросов. Если агенту нужно догадаться, какие страницы считать релевантными или когда остановиться, часть спецификации уже потеряна.
Шаг 2. Разделите workflow на проверяемые шаги
Не описывайте весь процесс одной инструкцией. Разбейте его на операции с понятными результатами:
- Проверить и нормализовать стартовый URL.
- Открыть стартовую страницу.
- Извлечь ссылки, подходящие под правило отбора.
- Посетить разрешённые страницы до достижения лимита.
- Извлечь целевые поля.
- Проверить полноту и формат результата.
- Записать итог и журнал.
Каждый шаг должен возвращать не только полезные данные, но и статус. Минимальная форма ответа шага:
{
"step": "extract_fields",
"status": "ok",
"items_found": 4,
"pages_visited": 3,
"next": "validate"
}
Возможные статусы стоит ограничить небольшим набором: ok, skipped, retryable_error, fatal_error, limit_reached. Это упрощает автоматическую проверку и не даёт агенту маскировать сбой свободным текстом.
Шаг 3. Задайте критерии завершения
Фраза «собери всё необходимое» не является критерием завершения. Она не говорит, сколько страниц достаточно и что делать при неполных данных. Используйте условия, которые можно вычислить:
- найдены все обязательные поля хотя бы для одной записи;
- обработано не больше
max_pagesстраниц; - новых подходящих ссылок больше нет;
- достигнут лимит шагов или времени;
- ошибка признана неисправимой.
Критерии могут срабатывать одновременно. В таком случае сохраняйте причину остановки, например completed_no_new_links или stopped_max_pages. Причина важнее общего сообщения «готово»: она позволяет отличить успешное завершение от остановки по лимиту.
Шаг 4. Введите лимиты до первого запуска
Лимиты — это часть корректности, а не только способ сэкономить. Без них агент может зациклиться, повторно открывать одну страницу или продолжать поиск после того, как полезный результат уже найден.
Минимальный набор ограничений:
| Лимит | Что ограничивает | Что записать в журнал |
|---|---|---|
| Время | Общую продолжительность запуска | время начала, окончания и причина остановки |
| Шаги | Количество действий агента | номер последнего шага |
| Страницы | Объём обхода | URL посещённых страниц |
| Повторы | Попытки после временной ошибки | номер попытки и тип ошибки |
Не подбирайте лимиты по одному удачному запуску. Сначала задайте безопасный верхний предел, затем смотрите журнал и уменьшайте его, если полезный результат стабильно появляется раньше. Указанные числа в примере выше не являются универсальными.
Шаг 5. Ведите журнал реально извлечённых страниц
Итогового списка ссылок недостаточно. Чтобы проверить работу агента, нужно различать страницу, которую он планировал открыть, и страницу, которую действительно открыл. Записывайте событие после успешного получения содержимого:
{
"run_id": "2026-11-21T10:00:00Z-example-001",
"event": "page_fetched",
"url": "https://example.org/catalog/item-1",
"source_url": "https://example.org/catalog",
"step": 7,
"status": 200,
"content_hash": "example-hash",
"fields_extracted": ["name", "availability"],
"timestamp": "2026-11-21T10:00:12Z"
}
Значение content_hash здесь показано как пример поля. В реальной системе оно должно вычисляться вашим кодом, а не выдумываться агентом. Не сохраняйте в журнал секреты, токены, cookies и лишние персональные данные. Если URL содержит чувствительные параметры, нормализуйте или редактируйте его перед записью.
Журнал должен позволять ответить на четыре вопроса: какие страницы открыты, в каком порядке, какой шаг их открыл и какие поля были извлечены. Именно эти данные дают основу для повторной проверки и сравнения стоимости.
Шаг 6. Сделайте проверку результата отдельным этапом
Нельзя считать ответ корректным только потому, что модель вернула JSON. Проверка должна быть независимой от текста объяснения агента. Например:
Проверки:
- run_id существует;
- причина завершения входит в разрешённый список;
- число посещённых страниц не превышает max_pages;
- каждый URL присутствует в журнале page_fetched;
- обязательные поля имеют допустимый тип;
- дубликаты записей устранены или явно отмечены;
- итоговое число записей согласуется с журналом.
При ошибке валидации harness должен вернуть не «почти готовый» ответ, а понятный статус: validation_failed. Это позволяет отделить проблему извлечения от проблемы формата.
Шаг 7. Сравнивайте запуски по одинаковым метрикам
Для экономичности не обязательно сразу строить сложную систему аналитики. Достаточно сохранять одинаковые поля на каждый запуск:
- идентификатор задачи и версии workflow;
- число шагов и посещённых страниц;
- число повторов и ошибок;
- число извлечённых записей и заполненных полей;
- причину завершения;
- доступные показатели использования модели и инструментов.
Стоимость сравнивайте только между запусками с сопоставимыми входами и критериями качества. Если один запуск обрабатывал пять страниц, а другой — пятьдесят, разница сама по себе ничего не говорит об эффективности. Сначала сравните качество при одинаковом лимите, затем — расход ресурсов на одинаковый объём результата.
Безопасный локальный контур
Для первого прототипа достаточно хранить вход, журнал и итог в отдельной директории. Команды ниже только создают каталоги и проверяют файлы; они не удаляют данные и не отправляют запросы во внешние сервисы:
mkdir -p runs/example-001
touch runs/example-001/input.json
touch runs/example-001/events.jsonl
touch runs/example-001/result.json
ls -la runs/example-001
Перед запуском проверьте, что в input.json нет ключей доступа и приватных данных. После запуска убедитесь, что файл событий содержит только разрешённые поля. Если workflow работает с внешними страницами, отдельно определите допустимые домены, таймауты и правила повторных запросов.
Проверка результата перед использованием
Используйте короткий чек-лист:
- Вход можно прочитать и проверить по схеме.
- Каждый шаг имеет статус и понятный следующий переход.
- Есть одна из заранее определённых причин завершения.
- Лимиты соблюдены, а превышение явно зафиксировано.
- Каждая реально извлечённая страница есть в журнале.
- Итог проходит независимую валидацию.
- Запуск можно сопоставить с предыдущим по версии workflow и метрикам.
Если пункт не выполняется, не увеличивайте лимиты автоматически. Сначала выясните, отсутствует ли нужное правило, неверно ли определяется ошибка или журнал записывается слишком поздно.
Типовые ошибки
Один большой промпт вместо контракта
Свободная инструкция может работать в демонстрации, но плохо подходит для сравнения. Исправление — вынести входы, лимиты и формат результата в отдельную схему.
«Готово» без причины
Одно слово не показывает, завершился ли поиск естественно или агент упёрся в лимит. Сохраняйте код причины завершения.
Журнал после финального ответа
Если журнал формируется только в конце, сбой может уничтожить сведения о промежуточных действиях. Записывайте события по мере выполнения и делайте запись устойчивой к частичной остановке.
Неограниченные повторы
Повторная попытка полезна для временной ошибки, но опасна без верхнего предела. Разделяйте повторяемые и неисправимые ошибки и фиксируйте каждую попытку.
Ограничения подхода
Harness не делает внешний источник достоверным и не гарантирует, что модель правильно интерпретирует страницу. Он также не заменяет проверку юридических ограничений, правил сайта, авторизации и обработки персональных данных. Его задача уже: ограничить процесс, сделать действия наблюдаемыми и дать проверяемую основу для сравнения.
На динамических сайтах журнал URL и HTTP-статуса может быть недостаточен: содержимое страницы меняется, а одинаковый адрес ведёт к разным состояниям. В таких случаях дополнительно храните время получения, версию парсера и безопасный отпечаток извлечённого содержимого. Если данные критичны, добавьте ручную проверку спорных записей.
Итоговая схема
Минимальный harness для повторяющегося workflow можно описать так:
input
→ validate_input
→ plan
→ execute_step
→ log_page_fetched
→ validate_partial_result
→ stop_if_complete_or_limited
→ validate_final_result
→ write_result_and_metrics
Начните с одного повторяемого сценария и небольшого набора полей. Когда журнал станет полным, а причина завершения — однозначной, добавляйте новые источники, параллельность или более сложные стратегии. Такой порядок сохраняет связь между изменением workflow, качеством результата и расходом ресурсов.
Для следующего шага откройте раздел guides, а определения терминов проверьте в глоссарии.