Harness для ИИ-агента: что это, как он устроен и зачем нужен разработчику
Выясняем, как ИИ-агенты пользуются инструментами.
Генерацией текстов и картинок уже мало кого удивишь. Пользователей всё чаще волнует, как научить ИИ самостоятельно выполнять сложные задачи, использовать инструменты и доводить задачи до конца. Для создания таких систем используют harness.
В этой статье мы разберёмся, как устроен harness, как именно он заставляет ИИ‑агента работать со сторонними инструментами и чем отличается от агентных фреймворков.
Содержание
- Что такое harness в ИИ
- Примеры задач с harness и без него
- Из чего состоит harness
- Чем harness отличается от ИИ-агента и агентного фреймворка
- Когда нужен полноценный harness
- Ошибки и риски при работе с harness
- Как оценить качество harness
Что такое harness в ИИ
Harness (agent harness, или харнесс) — это программная система, которая обеспечивает работу языковой модели (LLM) в составе ИИ-агента. Она передаёт модели данные и инструкции, обрабатывает запросы к инструментам и возвращает результаты. Само английское слово harness буквально переводится как «упряжь».
В такой системе есть три основных элемента:
- Языковая модель (LLM) — анализирует запрос, формирует ответ или предлагает воспользоваться инструментом.
- Harness — организует выполнение операций в среде исполнения.
- Среда исполнения (runtime) — инфраструктура, в которой выполняются шаги агента.
Сначала harness получает запрос пользователя и добавляет к нему инструкции, историю чатов и другие данные, которые помогают выполнить задачу. Расширенный запрос получает языковая модель. Она изучает информацию и либо готовит ответ, либо просит воспользоваться инструментом. Например, найти информацию в интернете или запустить код.
Если модель запрашивает инструмент, harness проверяет, разрешено ли выполнить это действие. Если да — организует его выполнение и передаёт результат модели. Модель анализирует результат работы инструмента и выбирает следующий шаг: подготовить итоговый ответ пользователю или продолжить работу с помощью инструментов.
Этот повторяющийся процесс называют агентным циклом (agent loop). В зависимости от настроек harness также может запускать проверки и повторять операции при технических сбоях. Цикл продолжается, пока агент не выдаст итоговый ответ или пока не сработает условие остановки.

Примеры задач с harness и без него
Рассмотрим два способа выполнения одной задачи с помощью LLM: обычный текстовый ответ и работу ИИ-агента под управлением harness. В первом случае языковая модель получает запрос и формирует ответ без внешних инструментов. Во втором модель работает в агентной системе, которая может использовать инструменты, выполнять операции и проверять результаты по заданным условиям.
Представим, что во время путешествия за границей пользователь приехал в незнакомый город и планирует поездку с помощью ИИ. За один день он хочет посмотреть основные достопримечательности, попробовать местную кухню и немного погулять. На питание и развлечения у него есть 20 долларов.
Языковая модель без harness
Пользователь передаёт модели запрос с описанием поездки и просит составить маршрут. Опираясь на свои знания, LLM предложит список достопримечательностей и заведений, где можно поесть, а также распределит посещения по времени. Но без внешних инструментов и дополнительной проверки модель может ошибиться. Например, предложить посетить музей в день, когда он закрыт, или неверно подсчитать расходы.
Даже если модель учтёт все условия, нет гарантии, что цены и часы работы будут актуальными. Чтобы убедиться, что маршрут составлен верно, пользователю придётся самому проверить информацию или воспользоваться дополнительными инструментами.
ИИ-агент с harness
Теперь ту же задачу получает ИИ-агент с harness. Система сохраняет условия прогулки и даёт модели доступ к разрешённым инструментам для поиска информации о достопримечательностях, заведениях и их расположении. На основе полученных данных модель предлагает маршрут, после чего harness организует его проверку. Например, отдельная функция может подсчитать расходы и сравнить их с бюджетом, а сведения о часах работы помогут проверить, удастся ли посетить выбранные места.
Допустим, ИИ-агент запланировал обед за 12 долларов, посещение музея за 5 долларов и ещё одно развлечение за 5 долларов. Проверка покажет, что общая стоимость составит 22 доллара — на 2 доллара больше бюджета.
Harness передаёт модели результат проверки, и та предлагает заменить одно из платных развлечений бесплатным. Обновлённый маршрут снова проходит проверку. Система проверяет, укладывается ли он в бюджет, открыты ли выбранные места в запланированное время и хватает ли времени на дорогу. Когда все условия соблюдены, ИИ-агент готовит окончательную версию плана и завершает работу. Если какие-то данные проверить не удалось, система должна сообщить об этом.

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

Читайте также:
Из чего состоит harness в ИИ
Универсальной архитектуры harness не существует: всё зависит от задач ИИ-агента. Иногда достаточно нескольких программных функций, а в масштабных проектах уже нужны отдельные механизмы управления контекстом, памятью, инструментами и безопасностью. Рассмотрим основные компоненты.
Инструкции и сборка контекста
Перед каждым обращением к модели harness дополняет запрос пользователя инструкциями, сведениями из истории взаимодействия и результатами работы инструментов. Так LLM учитывает условия задачи и уже выполненные действия. Всю историю передавать необязательно. Harness может выбирать данные, нужные для текущего этапа.
Разработчик может задать дополнительные инструкции для конкретного проекта. Например, агенту для написания кода — передать инструкции по работе с библиотеками и правила безопасности. Такие инструкции могут храниться в отдельных файлах. В Claude Code это CLAUDE.md, который размещают в корне проекта или папке .claude.
В некоторых системах применяют поэтапное раскрытие (progressive disclosure): модель сначала получает краткие описания доступных материалов, а подробные инструкции и документацию загружает по мере необходимости. Это экономит место в контекстном окне и помогает не перегружать модель лишними данными.

Читайте также:
Память и управление состоянием
Чтобы агент мог продолжать работу с учётом предыдущих действий, harness может сохранять данные и восстанавливать их при необходимости. Здесь важно различать три вида информации:
- История текущей сессии — сообщения пользователя, ответы модели и результаты вызовов инструментов.
- Сохранённое состояние процесса — текущий этап задачи, выполненные операции, промежуточные результаты и ошибки. Эти данные помогают продолжить работу после остановки, не начиная заново.
- Долговременная память — информация, которая сохраняется между сессиями: предпочтения пользователя, правила проекта или важные сведения из предыдущих взаимодействий. Её можно использовать в новых задачах.
Эти виды информации решают разные задачи, поэтому не каждому ИИ-агенту необходимы все три. К примеру, для написания файла с кодом необязательно запоминать интересы пользователя, но важно сохранить промежуточные результаты, если работа состоит из нескольких этапов.
Оркестрационный цикл и условия остановки
Оркестрация (orchestration) — управление последовательностью действий агента: запросами к модели, вызовами инструментов и передачей результатов между этапами. За неё отвечает программный компонент — оркестратор (orchestrator). Обычно он организует работу в виде агентного цикла:
Запрос. Harness получает запрос пользователя, готовит необходимый контекст и передаёт его языковой модели вместе с инструкциями.
Решение. LLM анализирует полученную информацию и определяет дальнейшие действия. Например, она может сформировать ответ или запросить использование внешнего инструмента.
Действие. Если модель запросила инструмент, harness проверяет этот запрос и организует выполнение разрешённой операции в среде исполнения.
Наблюдение. Harness получает результат выполненной операции. Это могут быть данные из файла, ответ сервиса или сообщение об ошибке.
Проверка. Harness организует проверку результата по заданным требованиям. Например, если ИИ-агент исправляет ошибку в программе, после изменения кода можно запустить тестирование.
Следующий шаг или завершение. Если задача ещё не решена, harness передаёт необходимые результаты модели для следующего шага. Если все требования выполнены, работа завершается.

Чтобы цикл не продолжался бесконечно, разработчик задаёт условия остановки: лимиты шагов, расхода токенов, времени выполнения или стоимости работы. Цикл также может останавливаться после повторных ошибок или при невозможности выполнить операцию.
Инструменты, права и песочница
С помощью инструментов агент может искать информацию, работать с файлами, базами данных и API, управлять браузером и запускать код. Разработчик указывает в harness названия, назначение и параметры инструментов. Система передаёт их описания модели и может отклонять запросы с неверными параметрами.
Инструменты подключают через API, расширения или MCP — открытый протокол взаимодействия ИИ-приложений с внешними сервисами и источниками данных.

Читайте также:
Для ограничения доступа к ресурсам используют песочницу (sandbox) — изолированную среду. Дополнительный контроль обеспечивают гардрейлы (guardrails) — правила и проверки входных данных, запросов к инструментам и результатов. Для отдельных действий, например удаления документов, система может запрашивать разрешение пользователя.
Ошибки, логи, наблюдаемость и проверка результата
В harness предусматривают обработку ошибок и повторных попыток (retries) при временных сбоях. Например, если сервис не отвечает, система может повторить запрос. Для этого задают тайм-аут — максимальное время ожидания ответа — и ограничивают число повторов. При работе с платежами важно исключить повторное списание.
Логи фиксируют запросы, вызовы инструментов и ошибки, а трассировка (tracing) — последовательность связанных операций. Метрики показывают время работы, расход токенов и количество ошибок. Вместе они обеспечивают наблюдаемость (observability): помогают понять, как работал агент и где произошёл сбой.
Для проверки результата harness может запускать тесты и использовать валидаторы — функции, которые проверяют соответствие заданным требованиям. Например, сравнивают итоговую выручку в отчёте с суммой продаж по заказам. Если ошибка может привести к серьёзным последствиям, результат дополнительно проверяет человек.
Чем harness отличается от ИИ-агента и агентного фреймворка
При разработке ИИ-систем наряду с harness часто встречаются смежные понятия. Все они связаны с автоматизацией, но подразумевают разные части системы.
Harness и ИИ-агент
ИИ-агент — система, которая использует LLM для выбора действий и решения задач с помощью инструментов. Harness организует его работу: управляет обращениями к модели и инструментам, отслеживает состояние задачи и условия завершения.
На практике граница между понятиями не всегда очевидна: готовые агентные системы могут включать собственную обвязку.
Harness и агентный фреймворк
Агентный фреймворк (agent framework) — набор готовых компонентов для создания ИИ-агентов. Он помогает подключать модели и инструменты, настраивать взаимодействие между агентами. Примеры таких фреймворков — LangChain, OpenAI Agents SDK и Mastra.
Harness — обвязка конкретного агента. Её можно написать самостоятельно, например на Python, или собрать с помощью фреймворка. В некоторых фреймворках уже есть готовые компоненты для управления агентным циклом.
На практике это разделение помогает оценить объём собственной разработки. При выборе решения стоит выяснить, какие возможности уже реализованы, что придётся дописать и какие компоненты можно изменить — например, подключить другую модель или задать собственные правила вызова инструментов.
Когда и зачем нужно создавать полноценный harness
Иногда для задачи достаточно одного обращения к языковой модели. В других случаях нужна система, которая может сама выбирать действия, работать с несколькими инструментами и контролировать результаты. Выбор архитектуры зависит от сложности задачи, количества операций, необходимости взаимодействия с внешними сервисами и последствий возможных ошибок. Рассмотрим четыре подхода.
Одиночный вызов языковой модели. Подходит для задач, которые можно решить одним обращением к LLM без внешних инструментов: например, составить краткое содержание статьи или объяснить сложный термин. Если не нужны уточнения, сохранение промежуточных результатов или отдельные проверки, harness с агентным циклом будет лишним.
Детерминированный рабочий процесс. Подходит, когда порядок операций заранее известен. Например, интернет-магазину нужно ежедневно выгружать данные о продажах, рассчитывать выручку и отправлять отчёт менеджеру. LLM можно подключить на отдельном этапе — например, для текстового описания результатов. Остальные операции программа выполнит по заранее заданному плану.
Простой агентный цикл. Нужен, когда следующий шаг зависит от полученных данных. Например, техподдержке нужно выяснить, почему покупатель не получил заказ: проверить статус доставки, информацию об оплате или уточнить данные у пользователя. LLM выбирает следующий шаг, а harness организует обращения к разрешённым инструментам. Для таких сценариев бывает достаточно простой обвязки с несколькими функциями, сохранением состояния и ограниченным числом попыток. Даже в ней нужны обработка ошибок и условия остановки, чтобы агент не повторял неудачные действия бесконечно.
Сложные и ответственные задачи. Если агент работает с персональными данными или денежными переводами, просто подключить LLM к инструментам недостаточно. Нужно разграничить права доступа, защитить данные, предусмотреть обработку ошибок, а также вести журналы операций и проверять результаты. Например, агент может подготовить заявку на возврат, но перед перечислением денег система должна запросить подтверждение уполномоченного сотрудника.
Выбранную архитектуру стоит проверить на небольшом прототипе с реальными задачами. Это покажет, каких возможностей не хватает и оправданно ли усложнять систему. Каждый новый компонент harness должен решать конкретную проблему, а его пользу стоит сопоставлять с затратами на разработку и поддержку.
Ошибки и риски при работе с harness
Даже хорошо спроектированный harness не гарантирует, что агент справится с задачей. При сокращении длинной истории взаимодействия могут потеряться важные условия или результаты проверок. Агент также может зациклиться: повторять неудачные действия и тратить деньги на обращения к платной модели. Поэтому ключевые сведения сохраняют отдельно, а число попыток и расходы ограничивают.
Избыточные права доступа увеличивают серьёзность ошибки. Например, агент, которому достаточно читать заказы, может получить возможность менять данные всей клиентской базы. Конфиденциальные сведения также могут случайно попасть в запросы к сторонним сервисам, ответы пользователям или логи. Поэтому агенту выдают только необходимые права и данные, а пароли и API-токены скрывают в журналах работы.
Отдельный риск — промпт-инъекции (prompt injection). Это попытки повлиять на модель через инструкции во внешних данных. Например, агент может принять команду из письма клиента за указание к действию и отправить внутренние документы на сторонний адрес. Отделение внешних данных от системных инструкций, ограничение прав и проверка опасных действий снижают риск, но не исключают его полностью.
Модель может сообщить об успехе, хотя операция завершилась ошибкой. Например, заявить об отправке письма, которое почтовый сервис не принял. Harness должен проверять результат по данным самого сервиса. При этом принятие письма к отправке ещё не означает его доставку адресату. В задачах, где ошибка может привести к серьёзным последствиям, важно предусмотреть возможность вмешательства специалиста.
Как оценить качество harness
Даже если агент успешно выполняет задачи, его harness может тратить лишнее время и ресурсы. Для проверки используют фиксированный набор тестовых задач с заранее заданными критериями успеха. Например, агенту поддержки предлагают обращения о доставке, возвратах и оплате. Такой подход называют оценочным тестированием (evaluation); его описывает Anthropic в руководстве по оценке ИИ-агентов.
Проверять нужно фактический результат: агент не просто подготовил ответ, а отправил его через систему поддержки и получил подтверждение. Передача обращения сотруднику тоже считается успехом, если этого требуют правила. Основные показатели:
- Успешность — доля задач, выполненных по заданным критериям.
- Шаги и вызовы инструментов — нет ли лишних действий и хватает ли необходимых проверок.
- Время и стоимость — длительность работы, расход токенов и плата за сервисы.
- Ошибки и повторы — как часто инструменты дают сбой и приходится повторять операции.
- Участие человека — какую часть задач агент решает самостоятельно.
- Стабильность — достигает ли агент нужного результата при повторных запусках.
Одни и те же задания запускают несколько раз. После изменений harness тестирование повторяют с той же моделью, настройками и исходными данными — иначе сложно определить причину улучшений или новых ошибок. Задачи должны быть близки к реальному применению: одних публичных бенчмарков недостаточно. Важно разбирать и неудачные попытки, чтобы понять, какие элементы системы требуют доработки.
