AI-разработка

Что такое Agent Harness у AI Coding Agent: Model, Harness, Tools и JSON State (2026)

Около 16 мин

Текст про DeepSeek описывал один продуктовый хост. Здесь только четыре общих слоя: Model, Harness, Tools, JSON State. Модель заполняет аргументы. Хозяин крутит цикл. Инструменты проходят Schema. Состояние можно проиграть.

Перед чтением

Слой Что запирает Кто исполняет
Model tool_use / arguments Модель заполняет JSON; побочные эффекты не гоняет
Harness цикл / права / сжатие Хозяин собирает контекст, затем исполняет
Tools inputSchema Schema — дверь; хозяин затем вызывает
State session / turn / JSONL Не восстановить — не состояние

Четыре слоя — объекты. Промпт — не архитектура.

Harness — это цикл, не модель

Coding Agent 2026 выглядит как «одна модель правит репозиторий». Разберите — получите четыре объекта. Модель выдаёт только следующее действие JSON. Harness грузит контекст, проверяет Schema, оценивает права, гоняет инструменты, пишет результаты обратно и сжимает историю, когда окно заполняется. Без этого цикла модель — чат. Официальный цикл Claude Code — тот же факт: принять промпт, оценить, выполнить инструменты, оценить снова, пока нет вызовов. Codex пишет непрерывность в Thread и запись сессии. Cursor тоже цикл хозяина. Модель диск не трогает.

  • Model: заполняет lookup_order и A-1042. Сокет не видит и процесс не порождает.
  • Harness: системный промпт, таблица инструментов, права, сжатие, бюджет, max_turns. Это состояние хозяина, не веса модели.
  • Tools и State: у инструментов есть Schema. У сессии есть проверяемый JSON. Текст чата — не состояние.

Как встроенные инструменты заполняют JSON: AI Coding Agent и JSON-вызовы инструментов. Скачок MCP: Как Coding Agent вызывает MCP. Почему Schema — дверь: Зачем ИИ нужен JSON Schema. Плагинный хост одного продукта: Текст про DeepSeek Harness. Этот текст тот продукт не пересказывает. Только складывает четыре слоя.

Слой один: модель только заполняет JSON

Модель видит таблицу инструментов хозяина и сообщения до сих пор. Выход — текст, вызов инструмента или оба. Вымышленный поиск — без настоящих секретов:

{
  "type": "tool_use",
  "id": "call_3c91",
  "name": "lookup_order",
  "input": { "order_id": "A-1042" }
}

Этот объект не HTTP и не MCP tools/call. Модель говорит хозяину «найди A-1042». Хозяин проверяет форму и разрешает или стопорит. Считать модель исполнителем — пропустить этот скачок.

Слой два: Harness крутит цикл

Сессия — машина состояний, не одно дополнение. Официальный цикл умещается в один объект: неизменны имя модели и таблица инструментов; изменчивы число сообщений, ожидающий инструмент, бюджет. Ход 2 из 8 считает хозяин. Модель дневник не ведёт:

{
  "session_id": "sess_7f2a",
  "turn": 2,
  "max_turns": 8,
  "immutable": {
    "model": "coding-agent",
    "tools": ["lookup_order", "Read", "Bash"]
  },
  "mutable": {
    "messages": 6,
    "pending_tool": "lookup_order",
    "budget_tokens": 128000
  }
}

Один ход Claude Code: модель выдаёт ответ с инструментами, хозяин исполняет, пишет tool_result обратно и спрашивает снова. Без вызовов цикл кончается и отдаёт расход плюс session_id. Хуки могут перехватить до исполнения. Codex после одобрения выбирает песочницу и тогда исполняет. Как писать права правилами: Модель прав Coding Agent. Harness вызывает права. Он не есть права.

Слой три: Tools проходят Schema

Таблица инструментов — меню модели. В каждой строке имя, описание и JSON Schema. Широкий object провоцирует выдуманные ключи. Поиск не несёт полей возврата:

{
  "name": "lookup_order",
  "description": "Look up an order by ID. Confirm before any refund.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

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

{
  "type": "tool_result",
  "tool_use_id": "call_3c91",
  "content": "{\"order_id\":\"A-1042\",\"status\":\"paid\"}"
}

Слой четыре: JSON State можно проиграть

Состояние — не «о чём только что говорили». Состояние — сообщения, результаты инструментов, номер сессии, границы сжатия. Codex дописывает сессию JSONL и собирает её при resume. Одна строка должна указывать на один поиск:

{"ts":"2026-09-28T01:12:04.221Z","type":"tool_result","id":"call_3c91","name":"lookup_order","ok":true,"order_id":"A-1042"}

Контекст заполняется. Claude Code сжимает у предела автоматически и шлёт compact_boundary в поток. Ранние детали могут уйти в сводку. Корневой CLAUDE.md вводят снова, поэтому устойчивые правила живут в файле, не только в первом промпте. Сжатие — смена состояния, не тихая амнезия:

{
  "type": "system",
  "subtype": "compact_boundary",
  "session_id": "sess_7f2a"
}

Пять шагов к Harness, на который можно указать

Не начинайте с «поставить модель сильнее». Пишите объекты:

  1. Сначала список инструментов. У каждого Schema. additionalProperties: false. Инструмент без Schema модели не отдавать.
  2. Написать условие остановки. max_turns или бюджет. Открытые задачи вголую не гонять.
  3. Права писать правилами. Чтение поиска — allow. Запись — ask. Возврат — deny. «Одобрить всё» не дневной default.
  4. Посадить состояние в JSON. Хотя бы tool_use, tool_result, session_id. Сошлись id — цикл соединён.
  5. Сжатие считать событием. Compact значит: сводка заменила старые сообщения. Правила, которые должны выжить, лежат на диске.

Как Schema служит дверью: Agents API + JSON Schema. Этот текст требует лишь четыре слоя объектами, а побочные эффекты гоняет хозяин.

Разбирать агента — разложить четыре JSON

Большинство сбоев — таблица инструментов, права или состояние не сошлись. Не «модель недостаточно умна».

  • форматировать inputSchema и input. Смотреть дыры и лишние ключи.
  • извлечь JSONPath вытащить $.name, $.input.order_id, $.session_id.
  • JSON Diff успешной записи и отказа. Сначала Schema и правила, потом промпты.
  • Сверить, что call_3c91 один id на tool_use и tool_result.
  • JSONL сессии, токены и пути репозитория не клеить в публичный форматтер. JSONSort работает в браузере.

Когда все четыре объекта собираются по Schema, вы собираете архитектуру — не фразу «вроде правил файлы».

Частые ловушки

  • Считать Harness новой моделью. Модели меняются. Цикл, двери и состояние стабилизировать сначала. Кривые оценки начинаются здесь.
  • Называть архитектурой более длинный system prompt. Промпты сжимают. Таблицу инструментов, права и запись сессии — нет.
  • Пропустить Schema и исполнить. Harness владеет циклом. Вторую проверку не отменяет. Широкий object гонит выдуманные ключи в побочные эффекты.
  • Считать окно чата состоянием. Окно — отрисовка. Состояние — JSON. Resume читает запись, не снимок.
  • Считать сжатие не-событием. Официальные клиенты шлют границу. Вложенные правила могут вернуться только после повторного чтения файла.
  • Брать плагинные слова одного продукта за общие. dsh и Capability Seam — объекты той статьи. Общие четыре слоя — Model / Harness / Tools / State.

FAQ

Harness и Agent Framework — одно и то же?

Не один слой. Framework часто вяжет узлы в деловом репозитории. Harness — цикл хозяина: загрузить контекст, пройти двери, исполнить, сохранить состояние. Бизнес-агента на Harness писать можно. Два слоя не мешать.

Модель сама правит файлы?

Нет. Модель заполняет только JSON инструмента. Чтение, запись, Shell и MCP исполняет хозяин. Нет хозяина — нет смены репозитория.

JSON State обязан быть JSONL?

Нет. Codex держит JSONL сессии как авторитетную запись. Claude Code использует стенограммы и поток событий. Требование — восстановить по id, что видела модель, а не суффикс файла.

Сжатие выбрасывает Schema?

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

Переписывать Harness при смене модели?

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

Вывод

Архитектура Coding Agent — не «модель побольше». Model заполняет JSON. Harness крутит цикл. Tools проходят Schema. State можно проиграть.

Сначала напишите, в какой инструмент, какой ход и какую запись состояния попадёт A-1042. Указали на четыре объекта — Harness есть. Модели сменятся. Четыре слоя стабилизировать раньше.

Дальше читать

Журнал: Первая публикация