Что такое agent harness и когда писать свой — на Python
- практикум
- Python
- ИИ-агенты
- LLM
Языковая модель умеет предложить следующий шаг: «поищи в каталоге», «спроси клиента», «готово». Но сама она ничего не исполняет. Она не ходит в базу, не помнит, что нашлось на прошлом шаге, и не знает, когда пора остановиться. Всё это делает обычный код вокруг модели. Его называют agent harness — буквально «упряжь»: сила у модели, а направление, пределы и право на действие задаёт программа.
Коротко: модель предлагает, harness решает.
Что делает harness
Даже у самого простого агента с одним инструментом harness отвечает за несколько вещей:
- цикл. Вызвать модель, разобрать её ответ, исполнить разрешённый инструмент, вернуть результат и повторить;
- права. Какие инструменты модели доступны и что делать, если она попросила другой или передала неверные аргументы;
- контекст. Что модель увидит на следующем шаге: задачу, ответы инструментов, их источник;
- остановку. Предел числа шагов и различимый итог: ответ найден, нужно уточнение, лимит исчерпан, источник недоступен;
- происхождение результата. Пользователю можно показать только то, что действительно вернул инструмент, а не то, что модель «вспомнила».
Когда агент растёт, к этому добавляются сохранение незавершённого запуска, утверждение действий человеком и трассы, по которым видно, что поведение изменилось после смены модели или промпта.
Когда стоит написать свой harness
Готовых решений много, и для части задач их достаточно. Свой harness обычно оправдан в таких ситуациях.
Агент — часть существующего продукта. У приложения уже есть свои правила доступа, предметная модель и тесты. Агенту нужно встроиться в них, а не принести собственные. Например, цену считает предметный код, а модель только помогает найти нужную запись.
Агент небольшой. Для одного-двух инструментов настройка фреймворка и его абстракции иногда сложнее самого цикла, который нужен задаче.
Сервис написан не на Python. Если основной код на Go, Java или Rust, Python-фреймворк разделит приложение между языками. Цикл вызова инструментов переносится на любой язык: у провайдеров моделей разный формат запросов, но схема одна.
Нужно доказывать поведение. Что модель вызвала, с какими аргументами, на основании чего получился итог. Когда ошибка стоит денег или доверия, эти ответы нужны в тестах и журнале, а не только в логах провайдера.
Действие требует согласия человека. Агент готовит черновик, но утверждает его сотрудник, и именно ту версию, которую видел.
Процесс длиннее одного запроса. Клиент отвечает на уточнение через день, а запуск должен продолжиться с сохранёнными основаниями.
Обратная ситуация тоже бывает. Если задача совпадает со сценарием готового агента — например, агента, который работает с файлами и кодом, — разумно начать с него.
Как это помогает понять готовые инструменты
Слово «harness» используют и авторы популярных инструментов. В LangChain разделяют три уровня: LangChain — фреймворк с абстракциями, LangGraph — среда выполнения агента, а harness у них — Deep Agents, который добавляет к ним готовые промпты, обработку вызовов инструментов, планирование и файловую систему. Anthropic называет Claude Agent SDK harness-ом, на котором работает Claude Code.
Внутри у них те же вопросы: какие действия разрешены, что модель видит на следующем шаге, когда остановиться, как пережить паузу и сменить модель без сюрпризов. Если вы хотя бы раз ответили на них в своём коде, документация готового инструмента читается как набор чужих ответов на знакомые вопросы. Проще понять, что он делает за вас, где его поведение придётся настраивать и стоит ли он своих абстракций в вашей задаче.
Практикум «Создание agent harness — Python»
В SoftPractice есть практикум, в котором вы собираете такой harness по частям. Заказчик — компания «Нева-Ремонт», которая занимается внутренней отделкой офисов. Сотрудник получает заявку свободным текстом, а ставки хранятся во внутреннем каталоге. Вы пишете помощника сметчика: он ищет нужные сведения и готовит черновик сметы.
Маршрут из шести заданий в одном растущем проекте:
- Поиск работы через инструмент. Цикл одного инструмента: итоговый тариф берётся только из найденной записи.
- Несколько разрешённых источников. Выбор инструмента, проверка аргументов, сбой источника как отдельный исход.
- Неполная заявка и происхождение сведений. Вопрос о конкретном недостающем условии; слова клиента не выдаются за замер.
- Сохранение черновика и продолжение после паузы. Состояние и источники переживают завершение процесса.
- Расчёт позиции и утверждение ревизии. Сумму считает предметный код, а сотрудник утверждает конкретную версию.
- Структурированная трасса и регрессия. Сценарии замечают, что поведение изменилось при смене модели, инструкции или инструмента.
Практикум рассчитан на уверенного Python-разработчика: понадобятся pytest, Git, JSON и подстановка зависимостей в тестах. Знать конкретный SDK модели не нужно. Проверки используют управляемую учебную модель, поэтому ключ провайдера для прохождения не требуется. На задания заложите около 14 часов и ещё около часа на короткую теорию.
Практикум не учит строить универсальный фреймворк агентов. Его цель — чтобы вы умели управлять действиями модели в своём приложении и доказывать это тестами.
Как начать
Код вы пишете у себя в редакторе — сами или с ИИ-инструментами, — фиксируете commit-ом и отправляете командой softpractice submit. SoftPractice запускает проверки, а ИИ-наставник помогает разобрать результат, не выдавая готового решения. Следующие задания приходят в тот же проект командой softpractice update.
Первое задание открыто без подписки.