SavePearlHarbor

Что такое Harness? Полный разбор на примере Claude Code, OpenAI и LangChain

—

от автора

admin

Глубокий разбор того, что на самом деле строят Anthropic, OpenAI, Perplexity и LangChain. Оркестрационный цикл, инструменты, память, управление контекстом — и всё остальное, что превращает stateless LLM в работающего агента.

Допустим, вы собрали чатбот. Может, даже прикрутили ReAct-цикл с несколькими инструментами. На демо работает. Но стоит попробовать сделать что-то production-grade — и всё начинает сыпаться: модель забывает, что делала три шага назад, вызовы инструментов падают без ошибок, контекстное окно забивается мусором.

Проблема не в модели. Проблема во всём, что её окружает.

LangChain это доказал: изменив только инфраструктуру вокруг LLM (та же модель, те же веса), они поднялись с позиции за пределами топ-30 на 5-е место в TerminalBench 2.0. В отдельном исследовательском проекте LLM оптимизировал саму инфраструктуру и достиг 76,4% pass rate, превзойдя системы, спроектированные вручную.

У этой инфраструктуры теперь есть название: agent harness (агентный харнесс).

Если статья понравится — приглашаю в канал AI for Devs. Каждый день публикую похожие материалы: модели, агенты, практические кейсы и новости из мира AI.

Что такое agent harness?

Термин формализовали в начале 2026 года, но концепция существовала задолго до этого. Харнесс — это полная программная инфраструктура, обёртывающая LLM: оркестрационный цикл, инструменты, память, управление контекстом, персистентность состояния, обработка ошибок и ограничения. В документации Claude Code Anthropic формулирует это прямо: SDK — это «агентный харнесс, на котором работает Claude Code». Команда Codex в OpenAI использует ту же формулировку, прямо приравнивая понятия «agent» и «harness» к не-модельной инфраструктуре, которая делает LLM полезным.

Мне понравилась каноническая формула от Vivek Trivedy из LangChain: «Если ты не модель — ты харнесс».

Вот различие, которое многих сбивает с толку. «Агент» — это результирующее поведение: целенаправленная, использующая инструменты, самокорректирующаяся сущность, с которой взаимодействует пользователь. Харнесс — это механизм, производящий это поведение. Когда кто-то говорит «я построил агента» — значит, он построил харнесс и направил его на модель.

Beren Millidge точно сформулировал эту аналогию в эссе 2023 года «Scaffolded LLMs as Natural Language Computers». Голая LLM — это CPU без RAM, без диска и без I/O. Контекстное окно выступает как RAM (быстрая, но ограниченная). Внешние базы данных — как дисковое хранилище (большое, но медленное). Интеграции с инструментами — как драйверы устройств. Харнесс — это операционная система. Как написал Millidge: «Мы заново изобрели архитектуру фон Неймана» — потому что это естественная абстракция для любой вычислительной системы.

Три уровня инжиниринга

Три концентрических уровня окружают модель:

  • Prompt engineering — формирует инструкции, которые модель получает.

  • Context engineering — управляет тем, что модель видит и когда.

  • Harness engineering — включает оба предыдущих плюс всю прикладную инфраструктуру: оркестрацию инструментов, персистентность состояния, восстановление после ошибок, циклы верификации, обеспечение безопасности и управление жизненным циклом.

Харнесс — это не обёртка вокруг промпта. Это полная система, которая делает автономное агентное поведение возможным.

12 компонентов production-харнесса

Анализируя подходы Anthropic, OpenAI, LangChain и сообщества практиков, можно выделить двенадцать отдельных компонентов production-харнесса.

1. Оркестрационный цикл

Это сердцебиение системы. Реализует цикл Thought-Action-Observation (TAO), также известный как ReAct loop. Цикл работает так: собрать промпт → вызвать LLM → распарсить вывод → выполнить вызовы инструментов → передать результаты обратно → повторить до завершения.

Механически это часто просто while-цикл. Сложность живёт во всём, чем этот цикл управляет, а не в самом цикле. Anthropic описывает свой runtime как «тупой цикл», где вся интеллектуальность живёт в модели. Харнесс просто управляет итерациями.

2. Инструменты (Tools)

Инструменты — это руки агента. Они определяются как схемы (имя, описание, типы параметров), которые инжектируются в контекст LLM, чтобы модель знала, что доступно. Слой инструментов занимается регистрацией, валидацией схем, извлечением аргументов, изолированным выполнением, захватом результатов и форматированием их в наблюдения, читаемые LLM.

Claude Code предоставляет инструменты по шести категориям: файловые операции, поиск, выполнение, веб-доступ, анализ кода и запуск субагентов. Agents SDK OpenAI поддерживает function tools (через @function_tool), hosted tools (WebSearch, CodeInterpreter, FileSearch) и MCP-инструменты.

3. Память (Memory)

Память работает на нескольких временных масштабах. Краткосрочная память — это история диалога в рамках одной сессии. Долгосрочная память сохраняется между сессиями: Anthropic использует файлы проекта CLAUDE.mdи автогенерируемые файлы MEMORY.md; LangGraph использует JSON-хранилища с организацией по namespace; OpenAI поддерживает Sessions на основе SQLite или Redis.

Claude Code реализует трёхуровневую иерархию: легковесный индекс (~150 символов на запись, всегда загружен), детальные файлы по темам, подгружаемые по требованию, и сырые транскрипты, доступные только через поиск. Критический принцип проектирования: агент воспринимает собственную память как «подсказку» и верифицирует против актуального состояния перед тем, как действовать.

4. Управление контекстом (Context Management)

Здесь многие агенты молча деградируют. Ключевая проблема — context rot: производительность модели падает на 30%+ когда ключевой контент попадает в середину окна (исследование Chroma, подтверждённое находкой Stanford «Lost in the Middle»). Даже окна в миллион токенов страдают от деградации instruction-following по мере роста контекста.

Production-стратегии включают:

  • Compaction: суммаризация истории диалога при приближении к лимитам (Claude Code сохраняет архитектурные решения и нерешённые баги, выбрасывая избыточные выводы инструментов)

  • Observation masking: JetBrains’ Junie скрывает старые выводы инструментов, оставляя видимыми сами вызовы

  • Just-in-time retrieval: поддержка легковесных идентификаторов и динамическая загрузка данных (Claude Code использует grep, glob, head, tail вместо загрузки полных файлов)

  • Sub-agent delegation: каждый субагент исследует широко, но возвращает сжатые саммари на 1000–2000 токенов

Руководство Anthropic по context engineering формулирует цель: найти минимально возможный набор высокосигнальных токенов, который максимизирует вероятность желаемого результата.

5. Конструирование промпта (Prompt Construction)

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

Codex OpenAI использует строгий стек приоритетов: системное сообщение под контролем сервера (наивысший приоритет), определения инструментов, инструкции разработчика, инструкции пользователя (каскадные файлы AGENTS.md, лимит 32 KiB), затем история диалога.

6. Парсинг вывода (Output Parsing)

Современные харнессы опираются на native tool calling, где модель возвращает структурированные объекты tool_calls, а не свободный текст, который нужно парсить. Харнесс проверяет: есть вызовы инструментов — выполнить и продолжить цикл. Нет вызовов — это финальный ответ.

Для структурированных выводов и OpenAI, и LangChain поддерживают constrained responses через Pydantic-модели. Устаревшие подходы вроде RetryWithErrorOutputParser (который передаёт оригинальный промпт, неудачный completion и ошибку парсинга обратно в модель) остаются доступны для edge cases.

7. Управление состоянием (State Management)

LangGraph моделирует состояние как типизированные словари, проходящие через узлы графа, с редьюсерами для слияния обновлений. Чекпоинтинг происходит на границах super-step, что позволяет возобновлять работу после прерываний и делать time-travel debugging. OpenAI предлагает четыре взаимоисключающие стратегии: application memory, SDK sessions, server-side Conversations API или легковесное цепочечное previous_response_id. Claude Code идёт другим путём: git-коммиты как чекпоинты и progress-файлы как структурированные черновики.

8. Обработка ошибок (Error Handling)

Вот почему это важно: процесс из 10 шагов с 99% успехом на каждом имеет лишь ~90,4% сквозного успеха. Ошибки накапливаются быстро.

LangGraph различает четыре типа ошибок: транзиентные (retry с backoff), LLM-recoverable (вернуть ошибку как ToolMessage, чтобы модель могла скорректироваться), исправляемые пользователем (прервать для ввода человека) и неожиданные (пробросить для отладки). Anthropic перехватывает сбои внутри обработчиков инструментов и возвращает их как результаты с ошибкой, чтобы цикл продолжал работу. Production-харнесс Stripe ограничивает количество попыток retry двумя.

9. Ограничители и безопасность (Guardrails and Safety)

SDK OpenAI реализует три уровня: input guardrails (запускаются на первом агенте), output guardrails (запускаются на финальном выводе) и tool guardrails (запускаются при каждом вызове инструмента). Механизм «tripwire» немедленно останавливает агента при срабатывании.

Anthropic архитектурно разделяет enforcement разрешений от reasoning модели. Модель решает, что попытаться сделать; система инструментов решает, что разрешено. Claude Code независимо контролирует ~40 дискретных возможностей инструментов с тремя стадиями: установление доверия при загрузке проекта, проверка разрешений перед каждым вызовом инструмента и явное подтверждение пользователя для высокорисковых операций.

10. Циклы верификации (Verification Loops)

Это то, что отделяет игрушечные демо от production-агентов. Anthropic рекомендует три подхода: rules-based feedback (тесты, линтеры, type checkers), visual feedback (скриншоты через Playwright для UI-задач) и LLM-as-judge (отдельный субагент оценивает вывод).

Boris Cherny, создатель Claude Code, отметил, что возможность верифицировать свою работу улучшает качество модели в 2–3 раза.

11. Оркестрация субагентов (Subagent Orchestration)

Claude Code поддерживает три модели выполнения: Fork (байт-идентичная копия родительского контекста), Teammate (отдельная панель терминала с файловой коммуникацией через mailbox) и Worktree (отдельный git worktree, изолированная ветка на агента). Agents SDK OpenAI поддерживает agents-as-tools (специалист решает ограниченную подзадачу) и handoffs (специалист берёт полный контроль). LangGraph реализует субагентов как вложенные графы состояний.

Цикл в действии: пошаговый разбор

Теперь, зная компоненты, проследим, как они работают вместе в одном цикле.

  1. Шаг 1 (сборка промпта): харнесс конструирует полный ввод: системный промпт + схемы инструментов + файлы памяти + история диалога + текущее сообщение пользователя. Важный контекст позиционируется в начале и конце промпта (следствие из «Lost in the Middle»).

  2. Шаг 2 (инференс LLM): собранный промпт уходит в model API. Модель генерирует выходные токены: текст, запросы на вызов инструментов или и то и другое.

  3. Шаг 3 (классификация вывода): если модель сгенерировала текст без вызовов инструментов — цикл завершается. Если запрошены вызовы — переходим к выполнению. Если запрошен handoff — обновляем текущего агента и перезапускаем.

  4. Шаг 4 (выполнение инструментов): для каждого вызова инструмента харнесс валидирует аргументы, проверяет разрешения, выполняет в изолированной среде и захватывает результаты. Read-only операции могут выполняться параллельно; мутирующие операции — последовательно.

  5. Шаг 5 (упаковка результатов): результаты инструментов форматируются как сообщения, читаемые LLM. Ошибки перехватываются и возвращаются как результаты с ошибкой, чтобы модель могла самокорректироваться.

  6. Шаг 6 (обновление контекста): результаты добавляются к истории диалога. При приближении к лимиту контекстного окна харнесс запускает compaction.

  7. Шаг 7 (цикл): вернуться к шагу 1. Повторять до завершения.

Условия завершения многоуровневые: модель сгенерировала ответ без вызовов инструментов, превышен лимит ходов, исчерпан бюджет токенов, сработал tripwire, пользователь прервал или вернулся safety refusal. Простой вопрос может занять 1–2 итерации. Сложный рефакторинг способен выстроить десятки вызовов инструментов за множество итераций.

Для долгосрочных задач, охватывающих несколько контекстных окон, Anthropic разработал двухфазный паттерн «Ralph Loop»: Initializer Agent настраивает окружение (init-скрипт, progress-файл, список фич, первоначальный git-коммит), затем Coding Agent в каждой последующей сессии читает git-логи и progress-файлы для ориентации, выбирает незавершённую фичу с наивысшим приоритетом, работает над ней, коммитит и пишет саммари. Файловая система обеспечивает преемственность между контекстными окнами.

Как реальные фреймворки реализуют этот паттерн

Claude Agent SDK от Anthropic открывает харнесс через единственную функцию query(), которая создаёт агентный цикл и возвращает async-итератор стримящих сообщений. Runtime — «тупой цикл». Вся интеллектуальность живёт в модели. Claude Code использует цикл Gather-Act-Verify: собрать контекст (поиск по файлам, чтение кода), совершить действие (редактировать файлы, запускать команды), верифицировать результаты (запустить тесты, проверить вывод), повторить.

Agents SDK OpenAI реализует харнесс через класс Runner с тремя режимами: async, sync и streamed. SDK «code-first»: логика рабочего процесса выражается на нативном Python, а не в графовых DSL. Харнесс Codex расширяет это трёхслойной архитектурой: Codex Core (код агента + runtime), App Server (двунаправленный JSON-RPC API) и клиентские интерфейсы (CLI, VS Code, веб-приложение). Все интерфейсы используют одинаковый харнесс — поэтому «модели Codex лучше ощущаются на интерфейсах Codex, чем в обычном чат-окне».

LangGraph моделирует харнесс как явный граф состояний. Два узла (llm_call и tool_node), соединённые условным ребром: есть вызовы инструментов — маршрутизировать в tool_node; нет — маршрутизировать в END. LangGraph эволюционировал из AgentExecutor LangChain, который был deprecated в v0.2 из-за сложности расширения и отсутствия поддержки мультиагентности. Deep Agents LangChain явно используют термин «agent harness»: встроенные инструменты, планирование (инструмент write_todos), файловые системы для управления контекстом, запуск субагентов и персистентная память.

CrewAI реализует ролевую мультиагентную архитектуру: Agent (харнесс вокруг LLM, определяемый ролью, целью, предысторией и инструментами), Task (единица работы) и Crew (коллекция агентов). Слой Flows добавляет «детерминированный скелет с интеллектуальностью там, где это нужно», управляя маршрутизацией и валидацией, пока Crews обеспечивают автономное взаимодействие.

AutoGen (эволюционирует в Microsoft Agent Framework) первыми реализовали conversation-driven оркестрацию. Его трёхслойная архитектура (Core, AgentChat, Extensions) поддерживает пять паттернов оркестрации: sequential, concurrent (fan-out/fan-in), group chat, handoff и magentic (менеджер-агент ведёт динамический task ledger, координируя специалистов).

Метафора строительных лесов

Метафора строительных лесов не декоративна. Она точна. Строительные леса — временная инфраструктура, позволяющая рабочим строить то, до чего они иначе не доберутся. Сами они ничего не строят. Но без них рабочие не доберутся до верхних этажей.

Ключевое наблюдение: леса убирают, когда здание готово. По мере улучшения моделей сложность харнесса должна снижаться. Manus перестраивали пять раз за шесть месяцев, каждый раз убирая сложность. Сложные определения инструментов стали общим выполнением shell-команд. «Управляющие агенты» стали простыми структурированными handoff’ами.

Это указывает на принцип ко-эволюции: модели теперь проходят post-training со специфическими харнессами в цикле. Модель Claude Code научилась использовать конкретный харнесс, на котором её обучали. Изменение реализаций инструментов может деградировать производительность из-за этой тесной связи.

«Тест на будущее» для дизайна харнесса: если производительность растёт с более мощными моделями без добавления сложности харнесса — дизайн правильный.

Семь решений, определяющих каждый харнесс

Каждый архитектор харнесса сталкивается с семью выборами:

  1. Single-agent vs. multi-agent. И Anthropic, и OpenAI советуют: сначала максимизируйте одного агента. Мультиагентные системы добавляют накладные расходы (дополнительные LLM-вызовы для маршрутизации, потери контекста при handoff’ах). Разделять стоит только когда перегрузка инструментами превышает ~10 пересекающихся инструментов или есть явно разделённые домены задач.

  2. ReAct vs. plan-and-execute. ReAct перемежает рассуждение и действие на каждом шаге (гибко, но с более высокой стоимостью на шаг). Plan-and-execute разделяет планирование и исполнение. LLMCompiler сообщает об ускорении в 3,6x по сравнению с последовательным ReAct.

  3. Стратегия управления контекстным окном. Пять production-подходов: time-based clearing, conversation summarization, observation masking, structured note-taking и sub-agent delegation. Исследование ACON показало снижение токенов на 26–54% при сохранении точности 95%+ за счёт приоритизации reasoning traces над сырыми выводами инструментов.

  4. Дизайн цикла верификации. Вычислительная верификация (тесты, линтеры) обеспечивает детерминированную истину. Inferential verification (LLM-as-judge) ловит семантические проблемы, но добавляет latency. Команда Thoughtworks Мартина Фаулера разделяет это на guides (feedforward, направлять до действия) и sensors (feedback, наблюдать после действия).

  5. Архитектура разрешений и безопасности. Permissive (быстро, но рискованно — автоодобрение большинства действий) vs. restrictive (безопасно, но медленно — требует одобрения для каждого действия). Выбор зависит от контекста развёртывания.

  6. Стратегия скопинга инструментов. Больше инструментов часто означает худшую производительность. Vercel убрал 80% инструментов из v0 и получил лучшие результаты. Claude Code достигает 95% сокращения контекста через lazy loading. Принцип: открывать минимальный набор инструментов, нужный для текущего шага.

  7. Толщина харнесса. Сколько логики живёт в харнессе, а сколько в модели. Anthropic делает ставку на тонкие харнессы и улучшение модели. Граф-ориентированные фреймворки ставят на явный контроль. Anthropic регулярно удаляет шаги планирования из харнесса Claude Code, когда новые версии модели интернализируют эту возможность.

Харнесс — это и есть продукт

Два продукта, использующие одинаковые модели, могут демонстрировать кардинально разную производительность исключительно из-за дизайна харнесса. Данные TerminalBench убедительны: изменение только харнесса передвигало агентов на 20+ позиций в рейтинге.

Харнесс — нерешённая задача и некоммодитизированный слой. Именно здесь живёт сложный инжиниринг: управление контекстом как дефицитным ресурсом, проектирование циклов верификации, которые ловят сбои до их накопления, построение систем памяти, обеспечивающих преемственность без галлюцинаций, и архитектурные ставки на то, сколько скаффолдинга строить vs. сколько оставить модели.

Область движется к более тонким харнессам по мере улучшения моделей. Но сам харнесс никуда не денется. Даже самая мощная модель нуждается в чём-то, что управляет её контекстным окном, выполняет вызовы инструментов, сохраняет состояние и верифицирует работу.

Когда ваш агент в следующий раз даст сбой — не вините модель. Смотрите на харнесс.

Русскоязычное сообщество про AI в разработке

Друзья! Перевод этой статьи подготовила команда ТГК «AI for Devs» — канала, где мы рассказываем про AI-агентов, плагины для IDE, делимся практическими кейсами и свежими новостями из мира ИИ. Подписывайтесь, чтобы быть в курсе и ничего не упустить!

ссылка на оригинал статьи https://habr.com/ru/articles/1023316/