AI Agent Harness
AI Agent Harness (программная обвязка ИИ-агента) — программная инфраструктура между большой языковой моделью и внешним миром, которая управляет циклом работы ИИ-агента, контролирует доступ к инструментам, управляет контекстом и позволяет обеспечить безопасность выполнения задач. Harness — это не сам агент и не модель, а система управления, которая превращает языковую модель в автономного агента. Можно описать термин простой формулой: Агент = Модель + Harness.
Языковая модель может сформировать ответ или запросить вызов инструмента, но выполнение такого запроса организует программное окружение. Harness связывает обращения к модели и инструментам в цикл: передает необходимые данные, получает результаты действий и возвращает их модели для следующего шага. Для длительных задач также может сохранять прогресс, управлять контекстом и применять ограничения. Состав этих механизмов зависит от задачи и реализации.
Разработчики адаптируют harness к характеру задач. Например, Anthropic описывает организацию длительной работы через подготовку окружения, последовательное выполнение отдельных задач и сохранение записей о прогрессе между сессиями. OpenAI в статье о harness engineering рассматривает подготовку окружения к работе агентов: доступные источники данных, проверяемые ограничения и обратную связь от инструментов. Эти примеры показывают, какие механизмы могут дополнять агентный цикл; они не задают обязательную архитектуру для всех систем.
Зачем нужен harness
Большая языковая модель может анализировать информацию и формулировать решения, но сама по себе не способна выполнять многошаговые задачи или работать между сессиями. Переход от отдельных запросов к длительной работе требует инфраструктуры, которая связывает действия модели с реальными операциями.
Рассмотрим следующий пример: пользователь просит исправить ошибку в приложении. Для выполнения задачи нужно найти нужный код, изучить его, внести изменения и запустить тесты. Если тесты завершатся неуспешно, потребуется разобраться в результате и повторить часть действий.
Модель может сформировать ответ или запросить вызов инструмента. Но запрос на чтение файла сам по себе не открывает файл, а текст команды не запускает ее в терминале. Программная система должна выполнить эти операции, получить результат и передать его модели.
Harness связывает эти действия в рабочий процесс. Он позволяет агенту получать новую информацию по ходу задачи и выбирать следующие шаги с учетом результатов. Для пользователя это означает возможность поручить многошаговую работу, а не вручную переносить каждый ответ модели в редактор или терминал.
Подытожим список задач, которые решает harness:
- Подготовка контекста — формирует инструкции, добавляет документы и результаты предыдущих действий.
- Вызов инструментов — проверяет аргументы, выполняет вызов и представляет результат модели.
- Сохранение состояния — хранит историю, промежуточные результаты и сведения о выполненной работе.
- Управление циклом и лимитами — определяет, когда повторить запрос, остановиться или передать управление человеку.
- Участие человека — запрашивает подтверждение для небезопасных операций.
- Проверка результатов — применяет тесты и другие проверки перед завершением задачи.
- Логирование и трассировка — собирает данные для анализа ошибок и оценки расхода ресурсов.
Состав возможностей зависит от конкретной реализации harness.
Scaffolding
Также часто встречается понятие scaffolding (поддерживающая конструкция), которое нередко используется как синоним harness. Если попытаться их разделить, то под harness чаще понимают управление циклом работы агента и дополнительные функции, которые зависят от конкретной системы. Устройство harness может меняться вместе с возможностями моделей и требованиями к задачам. Например, механизм, добавленный для компенсации ограничений одной модели, может оказаться ненужным после перехода на другую.
Scaffolding фокусируется на поведенческом слое — системных промптах, описаниях инструментов и инструкциях, которые направляют модель. Scaffolding формирует то, как модель воспринимает мир и принимает решения. Это своего рода «каркас», который компенсирует ограничения модели, когда она сама по себе не может справиться со сложной задачей.
В индустрии нет единого стандарта. Некоторые компании используют термин harness для обозначения всей обвязки вокруг модели, включая scaffolding. Однако разделение понятий помогает точнее планировать архитектуру, рассматривая оптимизацию поведения модели (scaffolding) и инфраструктуры исполнения (harness) как отдельные задачи.
Как работает harness
В упрощенном виде работа агента с harness выглядит следующим образом:
- Пользователь отправляет запрос.
- Harness формирует запрос к модели: добавляет инструкции, доступный контекст и описания инструментов.
- Модель формирует ответ или запрашивает вызов одного или нескольких инструментов.
- Если модель запросила инструмент, harness обрабатывает запрос с учетом настроенных правил и разрешений. При необходимости выполнение приостанавливается до подтверждения пользователя.
- Harness организует выполнение разрешенного вызова и передает модели результат или сообщение об ошибке.
- На основе полученных данных модель формирует ответ или запрашивает следующие действия. Цикл повторяется.
- Выполнение завершается при получении итогового ответа либо останавливается по предусмотренным условиям: например, при достижении лимита, отмене пользователем или ошибке, после которой продолжение невозможно.
Конкретная реализация определяет, как сохраняется состояние, какие ограничения применяются и когда требуется участие человека.
Критерии выбора
Harness не гарантирует правильность или безопасность результата. При выборе или разработке harness следует учитывать:
- Какие операции доступны агенту и как ограничиваются его права.
- Можно ли продолжить задачу после сбоя и какие данные при этом сохраняются.
- Позволяет ли история выполнения восстановить последовательность вызовов и результатов.
- Как задаются ограничения времени, количества шагов и расхода ресурсов.
- Какие проверки подтверждают выполнение задачи и когда требуется участие человека.
При этом harness нужен не каждому приложению с LLM. Если требуется классифицировать обращение или получить ответ в заданном формате, может хватить одного запроса. Для заранее известной последовательности действий подойдет обычный рабочий процесс. Агентный подход полезен, когда следующие шаги зависят от информации, полученной во время выполнения.
Примеры harness
Существует множество решений для создания AI Agent Harness. Возможности Harness могут быть частью готового агентного приложения или предоставляться библиотеками для разработки. Эти решения отличаются тем, сколько логики уже реализовано и что разработчик должен настроить самостоятельно:
-
Готовые инструменты:
- Codex — инструмент для работы с проектом из терминала. Объединяет взаимодействие с моделью, вызовы инструментов и управление агентной сессией.
- Claude Code — агентный инструмент для разработки с моделями Claude. Предоставляет готовый цикл работы с кодом и инструментами.
-
Библиотеки для создания агентных приложений:
- Claude Agent SDK — предоставляет программный доступ к агентному циклу, инструментам и управлению контекстом, используемым в Claude Code.
- OpenAI Agents SDK — предоставляет средства организации агентного цикла, выполнения инструментов, управления сессиями, взаимодействия агентов и трассировки.
-
Фреймворки:
- LangChain — компоненты и интеграции для создания агентов, включая готовый агентный цикл.
- LangGraph — средства описания процессов, переходов между шагами и управления состоянием.
- Agent Framework — официальный фреймворк Microsoft для Python и .NET с поддержкой мультиагентных систем.
- Google ADK — инструмент от Google для разработки агентов с открытым исходным кодом на Python, TypeScript, Go, Java и Kotlin.
Безопасность
Набор защитных механизмов зависит от реализации harness. Часть ограничений применяется в нем, часть — в инструментах, операционной системе или внешних сервисах. Возможные механизмы защиты:
- Проверка разрешений. Ограничивает доступные инструменты и операции; для отдельных действий может требоваться подтверждение пользователя.
- Изоляция выполнения. Ограничивает доступ запускаемого кода к файлам, сети и другим ресурсам.
- Проверки входных данных, вызовов и результатов. Помогают обнаруживать нарушения заданных правил и блокировать или направлять на проверку соответствующие действия.
- Ограничение привилегий. Агентам и их инструментам предоставляются права, необходимые для выполнения предусмотренных задач.
- Журналирование. Позволяет фиксировать вызовы инструментов и их результаты для расследования ошибок и нежелательных действий.
- Хуки. Автоматически запускаются при определенных событиях и позволяют прервать, модифицировать или проанализировать действие агента.
Инструкция в промпте сама по себе не создает технического запрета. Например, требование не изменять файлы следует подкреплять ограничениями записи, если приложение должно гарантировать такой режим работы.
Ограничения
Harness помогает организовать выполнение задачи, но не гарантирует правильность результата. При разработке и использовании агента следует учитывать следующие ограничения:
- Ошибочные действия. Модель может выбрать неподходящий инструмент, передать неверные параметры или неправильно интерпретировать ответ.
- Потеря необходимого контекста. При сокращении истории или восстановлении сессии часть значимой информации может оказаться недоступной модели.
- Сбои инструментов. Внешний сервис может не ответить или выполнить операцию частично. Повторный вызов требует осторожности: например, повторная отправка запроса может создать дубликат записи.
- Неполная проверка результата. Успешное выполнение команды или прохождение тестов не всегда означает, что задача пользователя решена.
- Нежелательные действия под влиянием внешних данных. Документ или ответ инструмента может содержать инструкции, направляющие агента за пределы задачи. Возможные последствия зависят от предоставленных прав и действующих ограничений.
- Расход ресурсов. Повторные обращения к модели и инструментам увеличивают стоимость и время выполнения. Лимиты помогают контролировать расход, но могут остановить работу до завершения задачи.
Harness в Yandex Cloud
Yandex Cloud предоставляет инструменты для создания и развертывания ИИ-агентов:
SourceCraft
SourceCraft — платформа для разработки со встроенным ИИ-ассистентом. Code Assistant использует принципы agent harness для помощи разработчикам: анализирует код, предлагает исправления, генерирует документацию и выполняет другие задачи, взаимодействуя с репозиторием через контролируемый интерфейс.
SourceCraft Code Assistant доступен в двух вариантах:
- SourceCraft CLI — интерфейс командной строки для работы с платформой SourceCraft, включающий harness OpenCode с настроенным доступом к моделям Code Assistant и инструментам платформы.
- Плагин для Visual Studio Code и IntelliJ IDEA — позволяет выполнять многошаговые задачи с сохранением контекста между операциями.
Подробнее в документации.
Yandex AI Studio
Yandex AI Studio — платформа для работы с генеративным ИИ. Предоставляет средства для создания собственных агентов:
- Agent Atelier — позволяет создавать, тестировать и публиковать текстовых ИИ-агентов в интерфейсе AI Studio.
- Responses API — API для управления многошаговыми диалогами и сессиями.
- MCP Hub — функциональность для создания и управления MCP-серверами.
Подробнее в документации.