Почему агентские проекты ломаются не на модели, а на обвязке: что такое harness engineering

Что такое harness engineering и почему агентские проекты ломаются на обвязке

Harness engineering - это проектирование инженерного слоя вокруг LLM, который задает агенту доступный контекст, разрешенные действия, порядок работы, проверки результата и правила восстановления после ошибок. Обвязка связывает модель с данными, инструментами, состоянием задачи и внешними системами.

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

Практический вывод прост: при сбое AI-агента сначала нужно проверить весь контур выполнения. Смена модели помогает, когда причина лежит в качестве рассуждения или понимании задачи. Ошибки в контексте, правах, состоянии, схемах инструментов и проверках требуют изменений в harness. О влиянии оболочки и оркестрации на надежность агентных моделей подробнее говорится в разборе надежности GLM-5.3-Flash и других агентных моделей.

Модель отвечает за решение, обвязка - за управляемое выполнение

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

входные данные и состояние -> инструкции и политики -> решение модели -> вызов инструмента -> проверка результата -> обновление состояния или восстановление после ошибки

Модель может выбрать действие, но право на это действие выдает программный контур. Обвязка решает, какие данные попадут в контекст, какая версия правил будет применена, можно ли вызвать инструмент с такими аргументами и что делать после отказа внешнего API.

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

Где заканчивается модель и начинается обвязка для AI-агентов

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

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

Контекст и данные: агент не может надежно работать с тем, чего не видит или видит без структуры

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

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

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

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

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

Инструменты и состояние: один неверный вызов может быть дороже неточного текста

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

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

tool: create_ticket
arguments:
  project_id: string, required
  summary: string, max_length=200
  idempotency_key: string, required
result:
  ticket_id: string
  status: enum(open, rejected)

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

Подробная схема оркестрации LLM, памяти, инструментов и обработки ошибок разобрана в материале о создании AI-агента с нуля. Такой подход помогает отделить логику агента от интерфейсов внешних сервисов.

Четыре функции harness engineering: ограничить, объяснить, проверить, исправить

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

Ограничение действий агента: разрешено только то, что система готова контролировать

Автономность агента должна совпадать с уровнем контроля над последствиями. Минимальный набор ограничений включает:

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

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

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

Передача инструкций: политика должна быть частью системы, а не удачной формулировкой

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

Минимальная запись состояния может выглядеть так:

policy_version: 3
task_state: awaiting_validation
allowed_tools: search, create_ticket
success_condition: ticket_id exists and status is open
escalation_condition: missing project_id or policy violation

Версия политики попадает в трассу вместе с идентификатором модели и входными данными. При регрессии команда видит, изменилась ли модель, инструкция, состав контекста или поведение инструмента.

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

Верификация результата: финальный текст не является достаточным доказательством

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

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

Детерминированные проверки нужно выполнять в коде. LLM-судья может оценивать качество текста, полноту объяснения или соответствие стилю, но его оценка не должна быть единственным барьером перед критичным действием.

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

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

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

Тип сбоя	Действие harness
Неверные параметры	Вернуть ошибку валидации, исправить только указанные поля и повторить один раз
Таймаут или временная ошибка сервиса	Использовать ограниченный retry с задержкой, затем выбрать fallback или остановить задачу
Пустой результат	Проверить фильтры, запросить уточнение или завершить процесс со статусом недостатка данных
Конфликт данных	Сохранить конфликт, не затирать исходное состояние и передать задачу на разбор
Нарушение политики	Заблокировать вызов и направить задачу человеку

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

Верификация под ограниченными данными: чему агентские системы могут научиться у bounded-evidence подхода

Схема SA-GGCoT относится к мультимодальной проверке утверждений, а не к готовой архитектуре продакшен-агента. Ее полезно использовать как иллюстрацию трех принципов: ограничивать доступное evidence, фиксировать промежуточное состояние и проверять согласованность оснований.

В bounded-evidence setting система работает с ограниченным внешним evidence и, если оно доступно, с ранними social traces за фиксированное окно после публикации. Недостаток данных нельзя компенсировать уверенным тоном модели. Тот же принцип действует в RAG и агентских процессах: отсутствие подтвержденного документа должно вести к запросу уточнения или остановке, а не к свободному заполнению пробелов.

Контрольные точки помогают найти конфликт в данных до финального вывода

В SA-GGCoT используется checkpoint-aware state tracking, который локализует конфликтующее evidence. Агентской системе нужен похожий подход: сохранять состояние не только в конце, но и после значимых шагов.

Контрольная точка может фиксировать:

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

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

Структурированные основания и проверка согласованности сильнее свободного рассуждения

В описанной схеме LLM преобразует выбранные фрагменты evidence в structured rationales, а согласованность проверяется через heterogeneous evidence graph. Это полезная модель для агентской обвязки: хранить нужно связь между утверждением, источником, действием и результатом проверки.

Свободное рассуждение в сообщении трудно проверять автоматически. Структурированное основание можно представить как набор записей:

claim: customer has active subscription
source: billing_record_184
action: allow premium response
check: subscription_status == active
result: passed

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

Подлинный фрагмент данных может вести к ложному решению

В материалах о мультимодальной проверке названы два режима сбоя: out-of-context reuse и pixel-level forgery. Первый связан с использованием подлинного фрагмента вне исходного контекста. Второй описывает манипуляцию на уровне пикселей.

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

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

Что контролировать в продакшене: наблюдаемость, политики и цена каждого шага

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

Трассировка должна отвечать на вопрос: почему агент сделал именно это

Трасса задачи - это последовательность событий и контрольных точек, а не копия всей переписки. Минимальный набор полей включает:

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

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

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

Политики доступа и approval нужны до первого инцидента

Уровень автономности выбирают по последствиям действия, а не по удобству интерфейса.

Действие	Минимальный контроль
Чтение разрешенных данных	Область доступа, фильтр источников, аудит запроса
Подготовка черновика	Проверка структуры, источников и получателя перед отправкой
Изменение внутренней системы	Ограниченный набор методов, валидация, журнал и откат
Внешняя отправка	Проверка адресата, содержимого и approval человека
Финансовое или административное действие	Жесткая блокировка без подтверждения, лимит суммы и полный аудит

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

Как собрать минимальную обвязку для AI-агента без преждевременной сложности

Начните с одного процесса и явного контракта результата

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

1. какие данные входят в задачу;
2. какой результат считается успешным;
3. какие источники разрешены;
4. какие инструменты доступны;
5. какие действия требуют подтверждения;
6. какие ошибки приводят к повтору, остановке или передаче человеку.

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

Когда процесс становится управляемым, добавляют новые инструменты и ветки. Для нескольких параллельных конвейеров полезна двухуровневая архитектура с общим control plane и локальными гейтами, описанная в разборе harness engineering для портфеля AI-агентов.

Измеряйте сбои по слоям, прежде чем менять LLM

Разбор инцидента можно вести в фиксированном порядке:

1. Проверить, были ли у агента нужные данные и корректные источники.
2. Проверить, не конфликтовали ли инструкции и состояние задачи.
3. Проверить выбор инструмента и параметры вызова.
4. Проверить ответ внешнего сервиса, таймаут и схему результата.
5. Проверить детерминированные правила и условие завершения.
6. Проверить механизм восстановления и причину финального статуса.
7. Оценить, остается ли проблема в понимании задачи после исправления остальных слоев.

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

В одном контролируемом эксперименте, описанном в разборе пяти harness для кодинг-агентов, разброс результата от смены обвязки оказался в 7,8 раза выше разброса от смены модели на одной задаче. Эта цифра относится к конкретному эксперименту и не служит универсальным коэффициентом для любого агента. Она показывает, почему диагностика контура выполнения должна предшествовать хаотичной замене LLM.

Ошибки при разработке AI-агентов, которые маскируются под проблему модели

Анти-паттерн	Что происходит	Слой harness
Слишком широкие права	Агент получает возможность выполнить операцию, последствия которой никто заранее не ограничил	Allowlist, области доступа, лимиты и approval
Инструкции смешаны с внешними данными	Фрагмент документа или пользовательский текст начинает влиять на политику	Типизированные секции контекста, маркировка источников и приоритеты правил
Состояние хранится только в переписке	После сбоя агент теряет статус шага и повторяет уже выполненную операцию	Персистентное состояние, контрольные точки и ключи идемпотентности
Проверяется только финальный ответ	Неверный источник или опасный вызов обнаруживаются слишком поздно	Промежуточные проверки инструментов, evidence и условий завершения
Ретраи не имеют бюджета	Цикл продолжает расходовать токены и повторять одну причину сбоя	Лимит повторов, таймаут, backoff и fallback
Ошибка API смешана с ошибкой рассуждения	Команда меняет модель, хотя сервис был недоступен или вернул плохую схему	Классификация ошибок и отдельные статусы внешних вызовов
Трасса не сохраняется	Нельзя восстановить путь от входных данных к ошибочному действию	Структурированные события, маскирование секретов и аудит

Выбор модели остается важной частью архитектуры. Он влияет на качество понимания, latency, стоимость и способность проходить сложные задачи. Надежность AI-агента формируется всей системой выполнения: контекстом, правами, инструментами, состоянием, проверками, ретраями и наблюдаемостью.

Если агент часто ошибается, сначала локализуйте сбой по этим слоям. Затем изменяйте конкретный механизм: фильтр данных, контракт инструмента, политику, проверку или маршрут восстановления. Новую LLM подключайте после проверки, что текущая обвязка передает ей корректную задачу и умеет безопасно обработать любой результат.

Подписаться на канал