Обзор OpenHands: задачи для ИИ-агента и проверка кода сводится к одному: платформа даёт агенту рабочую среду с файлами, командами и браузером, а качество результата вы определяете сами через diff и тесты. Ниже — архитектура, учебный вход и разбор ошибок приёмки.
Что такое OpenHands и из каких частей он собран
Документация проекта на docs.openhands.dev описывает OpenHands как набор связанных компонентов. Agent Canvas — открытый браузерный клиент и центр управления диалогами и автоматизациями, который подключается к одному или нескольким бэкендам Agent Server. SDK — составная Python-библиотека для сборки агентов, работающих с кодом; в том же репозитории лежит Agent Server, открывающий выполнение агентов, диалоги, инструменты и рабочие пространства через REST и WebSocket. Cloud — управляемый коммерческий сервис для запуска без собственной инфраструктуры бэкенда и песочниц; он даёт хостинговое выполнение, интеграции, совместную работу, контроль доступа, отчётность по расходу и управление бюджетом. Sandbox Server — поддерживаемый сообществом отдельный API и плоскость управления песочницами: он создаёт и обслуживает изолированные среды, где живёт Agent Server, и может использовать Agent Canvas как браузерный клиент.
Такая разбивка объясняет, почему в разговорах про OpenHands путаются команды запуска. Локальный GUI — устаревшее Docker-приложение из прежнего монорепозитория; для активной разработки браузерного клиента документация направляет в Agent Canvas. Каждый публичный репозиторий несёт собственную лицензию, и проверять нужно тот, который вы правите.
Механизм простыми словами: модель получает интерфейс к среде, среда даёт файлы, терминал и браузер, а событийный поток связывает действия агента с интерфейсом и человеком. Статья arXiv 2407.16741 описывает OpenDevin как платформу с событийной архитектурой взаимодействия, песочницей с операционной системой и браузером, интерфейсом для создания кода, его выполнения и просмотра сайтов, а также средой оценки. Там же указано: в поставку входит хаб агентов с более чем десятью реализациями и поддержка пятнадцати бенчмарков.
Предел механизма задаёт сама среда. В варианте установки без песочницы agent-server запускается прямо на машине, и агент получает полный доступ к её файловой системе. Для Docker и удалённых бэкендов права и доступные файлы определяются их отдельной конфигурацией. Права определяет окружение, в котором вы его запустили, и текст промпта эти права не меняет.
Учебный вход: задание price_calc и минимальный diff
Возьмём ограниченную задачу с проверяемым результатом. Файл calc.py, функция apply_discount(price, discount). Дефектный исходник возвращает price - discount; требование — price * (1 - discount). Эталоны: 100 и 0.2 дают 80; 0 и 0.2 дают 0; 100 и 0 дают 100. Область работ: только calc.py и test_calc.py, без сети, обновления пакетов, коммита и публикации. Результат — минимальный diff и три эталона. Это учебный пример; запуск модели в нём не выполнялся.
Промпт для постановки задачи агенту:
Задача: исправить функцию apply_discount в файле calc.py.
Текущий код:
def apply_discount(price, discount):
return price - discount
Требование: скидка вычитается как доля от цены.
Ожидаемая формула: return price * (1 - discount)
Эталоны, которые должны проходить:
apply_discount(100, 0.2) == 80
apply_discount(0, 0.2) == 0
apply_discount(100, 0) == 100
Область работ: только calc.py и test_calc.py.
Запрещено: сеть, обновление зависимостей, коммит, публикация.
Результат: минимальный diff и вывод трёх эталонов.
Минимальный diff, который ожидается на выходе:
--- a/calc.py
+++ b/calc.py
@@
def apply_discount(price, discount):
- return price - discount
+ return price * (1 - discount)
Файл тестов, который прикладывается к заданию:
from calc import apply_discount
def test_discount_basic():
assert apply_discount(100, 0.2) == 80
def test_discount_zero_price():
assert apply_discount(0, 0.2) == 0
def test_discount_zero_rate():
assert apply_discount(100, 0) == 100
Смысл ограничения области в том, что вы принимаете ровно тот diff, который просили. Всё за её пределами — повод вернуть работу на доработку.
Структурная корректность и фактическая правильность
Две проверки отвечают на разные вопросы. Структурная корректность: затронуты ли только разрешённые calc.py и test_calc.py, нет ли правок в других файлах, нет ли новых зависимостей, не тронут ли UI. Фактическая правильность: даёт ли формула верные значения на эталонах. Зелёные тесты сами по себе не закрывают первую проверку.
| Что проверяем | Инструмент | Признак приёмки | Признак возврата |
|---|---|---|---|
| Формула | просмотр diff | строка return price * (1 - discount) |
осталась price - discount |
| Эталоны | запуск тестов | три теста проходят | хотя бы один падает |
| Посторонние файлы | git status --short, git diff --stat и просмотр новых файлов |
затронуты только calc.py и test_calc.py |
появились другие файлы |
| Внешние действия | журнал инструментов | сеть и публикация не вызывались | есть сетевые вызовы или коммит |
Практический порядок приёмки: сначала git status --short и git diff --stat, затем чтение diff и новых файлов, затем тесты и журнал инструментов. Обычный diff не показывает содержимое неотслеживаемых файлов; например, новый test_calc.py нужно просмотреть отдельно. Обратный порядок создаёт ловушку: зелёные тесты успокаивают, и посторонние правки проходят незамеченными.
Отдельно про «без сети» в промпте. Это пожелание в тексте задания. Технические ограничения задаёт среда: политика исходящего сетевого доступа, права процесса и доступные монтирования. Отсутствие ключей само по себе не запрещает сеть, а контейнер требует проверки фактической конфигурации. Если агент обновил зависимости или переписал UI, выполнение не принимается даже при зелёных тестах — формула верна, а область работ нарушена.
Как разворачивается среда и что это меняет
Документация на GitHub описывает установку на любую машину: ноутбук, выделенный компьютер, сервер в облаке. Локально агенты идут по умолчанию, а подключаться можно к нескольким бэкендам — контейнерам Docker, виртуальным машинам, инфраструктуре компании, Cloud или Enterprise. Один и тот же фронтенд Agent Canvas переключается между средами: общий Agent Server для ревью кода и обновления зависимостей, личные агенты на ноутбуке.
Локальный бэкенд допускает несколько серверов одновременно на разных портах — по одному на проект или инструментарий. Запуск без флагов поднимает полный стек на одном порту; раздельный запуск нужен, когда бэкендов несколько или фронтенд и бэкенды живут в разных процессах. Для macOS и Linux документация упоминает именованный том Docker для настроек, секретов и диалогов и монтирование проектов в /projects. Для Docker-варианта Agent Canvas README требует Docker Desktop на macOS и Windows, а на Linux — Docker Engine или Docker Desktop. Установка без песочницы описана отдельно и не требует переносить на неё требования Docker. Настройка сокета из legacy local GUI относится к прежнему приложению; для Canvas используйте актуальный раздел README.
Agent Canvas запускает открытый агент OpenHands из коробки и умеет работать со сторонними агентами: Claude Code, Codex, Gemini CLI, Pi, OpenCode, а также любым агентом, совместимым с ACP. Это меняет постановку задачи: среда одна, исполнитель переключается.
| Сценарий | Где живёт бэкенд | Что это даёт |
|---|---|---|
| Личные задачи | ноутбук | быстрый доступ к локальным файлам |
| Командное ревью | общий Agent Server | один фронтенд на несколько исполнителей |
| Долгие задачи | сервер в облаке | работа продолжается при выключенном ноутбуке |
| Несколько проектов | отдельные процессы и порты | раздельные подключения; изоляцию файлов и прав задаёт среда |
Случай, где подход не решает задачу
Возьмём задачу, где нужен контекст за пределами файла. Формула скидки исправляется в calc.py, но правило округления задано в другом модуле, а порядок применения скидок — в конфигурации, которой нет в области работ. Агент может привести calc.py к локальному требованию и пройти три эталона, сохранив ошибку интеграции с другими правилами продукта. Ограниченное задание здесь работает как надо: оно честно показывает, что результат верен внутри области и недостаточен снаружи.
Второй случай — задача, требующая внешних данных. Если правильный ответ зависит от актуальной схемы API или состояния внешнего сервиса, изолированная среда с запретом сети даёт агенту только то, что лежит в файлах. Он либо остановится, либо начнёт угадывать. Оба исхода требуют ручной проверки.
Третий случай — правки, затрагивающие много файлов. Задание «приведи проект в порядок» не имеет эталона приёмки: непонятно, что считать готовым результатом. Здесь помогает дробление на задачи с одним проверяемым изменением.
Универсального улучшения от подключения агента не следует. Выигрыш появляется там, где задачу можно ограничить, а результат — проверить diff и тестами.
Модель под агентом и границы переноса
Mistral AI в историческом анонсе Devstral описывает модель для задач программной инженерии, созданную в сотрудничестве с All Hands AI и выпущенную под лицензией Apache 2.0. Там же сказано, что модель работает поверх каркасов вроде OpenHands или SWE-Agent, которые задают интерфейс между моделью и тестами. Заявленный результат — 46.8% на SWE-Bench Verified, набор из 500 реальных GitHub-issue, отобранных вручную; при оценке в том же каркасе OpenHands модель обходит более крупные открытые модели. Для локального запуска указана одна RTX 4090 или Mac с 32 ГБ памяти, В анонсе также назван API-идентификатор devstral-small-2505. Это описание конкретного выпуска; доступность и тарифы здесь не проверялись.
Эти числа относятся к конкретной модели и конкретному каркасу. Переносить их на другую модель, другую версию или другой каркас нельзя: каркас задаёт интерфейс, и смена интерфейса меняет поведение. То же касается инфраструктурных деталей: версии Node.js и Agent Canvas, упомянутые в документации DigitalOcean для образа 1-Click App, относятся к этому образу и не описывают локальную установку. Ключи и переменные окружения, названные в одном руководстве, принадлежат его владельцу.
Практический вывод для выбора модели: сначала фиксируйте каркас и задачу, затем сравнивайте модели внутри одного каркаса. Сравнение результатов из разных каркасов даёт смешанную картину.
Частые вопросы
Чем Agent Canvas отличается от SDK?
Agent Canvas — браузерный клиент и центр управления диалогами, который подключается к бэкендам Agent Server. SDK — Python-библиотека для сборки агентов, работающих с кодом; в том же репозитории лежит Agent Server с REST и WebSocket API. Это разные слои одной платформы.
Можно ли запустить OpenHands локально и в облаке одновременно?
Документация на GitHub описывает подключение нескольких бэкендов к одному фронтенду Agent Canvas. Локальный запуск идёт по умолчанию, а бэкенды могут жить в контейнерах, на виртуальных машинах, в инфраструктуре компании, в Cloud или Enterprise. Переключение между средами выполняется из одного интерфейса.
Как проверить, что агент не вышел за область работ?
Сначала смотрите git status --short и git diff --stat: затронуты должны быть только файлы из задания. Прочитайте diff и отдельно новые файлы, которые ещё не отслеживаются Git, затем сверьте формулу с требованием. После этого запускайте тесты и проверяйте журнал инструментов на сетевые вызовы и коммиты.
Что делать, если тесты зелёные, а diff шире задания?
Возвращать работу на доработку. Зелёные тесты подтверждают фактическую правильность на эталонах и не подтверждают структурную корректность. Обновление зависимостей или правка UI — нарушение области, и такое выполнение не принимается.
Подходит ли OpenHands для задач без чёткого эталона?
Для задач вида «приведи проект в порядок» эталон приёмки отсутствует, и проверить результат нечем. Подход работает там, где задачу можно ограничить файлами и сформулировать проверяемые эталоны. Крупные задачи дробятся на шаги с одним проверяемым изменением.