005. 2026-04-21 - The Anatomy of an Agent Harness

📄 Анатомия каркаса агентной системы (The Anatomy of an Agent Harness)

Краткий обзор

Статья объясняет, что реальная сила AI-агентов лежит не только в модели, а в инфраструктуре вокруг неё: цикле оркестрации, инструментах, памяти, управлении контекстом, проверках и безопасном исполнении. Автор показывает, почему продакшен-агент - это прежде всего инженерия agent harness, и разбирает 12 обязательных компонентов такой системы.

🔗 Оригинал: Пост и тред Akshay Pachaar в X)

---

🏛️ Ключевые идеи

• Агент = поведение, Harness = инфраструктура: агентность возникает как эффект правильно собранной системы вокруг LLM, а не “из коробки” модели.
• Главная формула: “If you’re not the model, you’re the harness.” Всё, что не веса модели, - это инженерный контур исполнения.
• Контекст - дефицитный ресурс: даже большие окна деградируют по качеству; выигрывает не “больше токенов”, а “выше сигнал”.
• Качество даёт цикл верификации: тесты, линтеры, визуальные проверки и judge-агенты повышают итоговую надёжность в разы.
• Производительность решает архитектура окружения: одинаковые модели могут давать сильно разный результат из-за различий в harness.

---

💡 Где использовать (Use Cases)

• AI coding agents: IDE/CLI-агенты для рефакторинга, поиска по коду, запуска команд и автопроверки изменений.
• Внутренние copilot-платформы: корпоративные помощники с управляемым доступом к данным и инструментам.
• Автономные workflow-боты: многошаговые процессы с долгой памятью, ручными подтверждениями и recover после ошибок.
• Мультиагентные пайплайны: разделение на специалистов только там, где один агент перегружен инструментами/ролями.

---

🛠️ Технический разбор

Автор выделяет 12 компонентов production-harness:

1. Цикл оркестрации (Orchestration Loop): prompt -> LLM -> tool calls -> observations -> repeat.
2. Инструменты (Tools): схемы, валидация аргументов, sandbox, нормализация результатов.
3. Память (Memory): short-term (сессия) + long-term (CLAUDE.md, MEMORY.md, stores, session backends).
4. Управление контекстом (Context Management): compaction, masking, JIT retrieval, делегирование subagents.
5. Сборка промпта (Prompt Construction): иерархия приоритетов: system/tool/developer/user/history.
6. Парсинг выхода (Output Parsing): нативные tool_calls, schema-constrained outputs.
7. Управление состоянием (State Management): checkpoints, resume, structured scratchpads.
8. Обработка ошибок (Error Handling): transient/recoverable/user-fixable/unexpected + ограничение retries.
9. Guardrails и безопасность: input/output/tool guardrails, tripwire, permission gates.
10. Петли верификации (Verification Loops): deterministic checks + inferential checks.
11. Оркестрация субагентов: fork/teammate/worktree, handoffs, nested graphs.
12. Жизненный цикл выполнения: условия завершения, лимиты шагов/токенов, interruption-safe flow.

The Loop in Motion: пошаговый walkthrough

Шаг 1. Prompt Assembly (сбор входа)
Harness собирает полный контекст в фиксированном порядке: system prompt -> tool schemas -> memory -> history -> user message. Критически важный контент ставится в начало и конец промпта, чтобы снизить эффект “Lost in the Middle”.

Шаг 2. LLM Inference (вызов модели)
Собранный контекст отправляется в API модели. На выходе может быть:

• обычный текстовый ответ;
• tool_calls;
• комбинация текста и вызовов инструментов;
• сигнал handoff на другого агента.

Шаг 3. Output Classification (маршрутизация ответа)
Harness классифицирует результат:

• если только текст без tool_calls -> кандидат на финальный ответ;
• если есть tool_calls -> переход к исполнению инструментов;
• если handoff -> смена активного агента и перезапуск цикла.

Шаг 4. Tool Execution (исполнение инструментов)
Для каждого вызова выполняются проверки: схема аргументов, права доступа, sandbox-политика, лимиты.
Read-only операции можно запускать параллельно, mutating-операции обычно идут последовательно.

Шаг 5. Result Packaging (упаковка наблюдений)
Результаты инструментов (включая ошибки) переводятся в структурированный формат, который модель может “прочитать” в следующем ходе. Ошибка не ломает цикл, а становится входом для self-correction.

Шаг 6. Context Update (обновление контекста)
Новые наблюдения добавляются в историю. При приближении к лимиту токенов включаются механики compaction: сжатие истории, маскирование старых outputs, выборочная подгрузка данных по идентификаторам.

Шаг 7. Loop / Termination Check (повтор и остановка)
Система возвращается к шагу 1 и повторяет цикл до выполнения одного из условий завершения:

• финальный ответ без tool_calls;
• исчерпан лимит шагов/токенов;
• сработал guardrail/tripwire;
• пользователь прервал задачу;
• модель вернула safety refusal.

Для длинных задач: двухфазный режим

Для задач, не вмещающихся в одно контекстное окно, полезен паттерн из статьи:

• Initializer Agent: инициализирует окружение, прогресс-файлы, baseline commit, список фич.
• Coding Agent: в следующих сессиях читает прогресс/логи, берёт приоритетную незавершённую задачу, вносит изменения, фиксирует результат и обновляет summary.

How Real Frameworks Implement the Pattern

Anthropic (Claude Agent SDK / Claude Code)

• Модель исполнения: query() поднимает агентный runtime и стримит события как async iterator.
• Философия: “dumb loop”, где интеллект в модели, а harness управляет ходами, инструментами и контекстом.
• Практический цикл: Gather -> Act -> Verify (собрал контекст, выполнил действие, проверил результат).

OpenAI (Agents SDK / Codex Harness)

• Точка входа: Runner (sync/async/stream), code-first orchestration без обязательного graph DSL.
• Инструменты: function tools, hosted tools, MCP-интеграции, плюс guardrails на разных уровнях.
• Архитектура Codex: единый harness для CLI/IDE/Web, за счёт чего поведение между интерфейсами консистентно.

LangGraph / LangChain

• Подход: явный state graph с узлами LLM/tool и условными переходами.
• Сильная сторона: контролируемый workflow, checkpoints, resume и “time-travel” отладка состояний.
• Эволюция: переход от AgentExecutor к более расширяемой graph-модели и deep-agent паттернам.

CrewAI

• Ролевая модель: Agent (роль + цели + инструменты), Task (единица работы), Crew (кооперация).
• Flows-слой даёт детерминированный backbone (маршрутизация/валидация), а агенты отвечают за автономию.

AutoGen / Microsoft Agent Framework

• Основа: conversation-driven orchestration между агентами-специалистами.
• Типовые паттерны: sequential, concurrent (fan-out/fan-in), group chat, handoff, manager-led coordination.

Вывод по фреймворкам
Разные экосистемы делают ставку на разную “толщину” harness: от тонкого loop-first подхода до graph-heavy оркестрации. Но базовый паттерн у всех один: контекст -> действие -> наблюдение -> проверка -> итерация.

Seven Decisions That Define Every Harness

Ниже 7 решений, которые в итоге определяют качество, стоимость и масштабируемость агентной системы:

1. Single-agent vs Multi-agent
   Начинать обычно лучше с одного сильного агента. Мультиагентность имеет смысл, когда есть перегруз инструментами или явно разделимые домены задач.

2. ReAct vs Plan-and-Execute
   ReAct гибче в неизвестной среде, но дороже по шагам. Plan-and-Execute быстрее и предсказуемее на задачах с понятной структурой.

3. Стратегия управления контекстом
   Варианты: очистка по времени, суммаризация диалога, masking наблюдений, структурированные заметки, делегирование subagents.

4. Дизайн verification loop
   Детерминированные проверки (tests/linters/types) дают строгую валидацию; inferential-проверки (LLM-as-judge) ловят смысловые дефекты.

5. Архитектура permissions и safety
   Более permissive режим ускоряет работу, но повышает риск. Более restrictive режим безопаснее, но добавляет friction и latency.

6. Стратегия скоупа инструментов
   Чем больше одновременно доступных tools, тем выше шум и шанс ошибочного выбора. Практика: давать минимально необходимый набор под текущий шаг.

7. Толщина harness (harness thickness)
   Что держать в модели, а что в коде оркестратора: тонкий harness опирается на интеллект модели; толстый harness делает поведение явным и контролируемым.

Практический ориентир: эти 7 решений стоит фиксировать явно в архитектурном документе, иначе система “дрейфует” в неуправляемый гибрид.

Практический тезис статьи

Продуктовая ценность AI-агента находится в том, как вы управляете ограничениями: контекстом, ошибками, правами, проверкой результата и восстановлением после сбоев.

# Упрощённый скелет цикла harness
def run_agent_harness(state):
    while not state.is_done():
        prompt = build_prompt(state)
        output = llm_infer(prompt)
        if output.tool_calls:
            results = execute_tools_safely(output.tool_calls)
            state = update_state(state, results)
            state = compact_context_if_needed(state)
            continue
        state = finalize(state, output.text)
    return state

---

⚖️ Плюсы и Минусы

👍 Плюсы	👎 Минусы
Повышает качество и воспроизводимость результата	Усложняет архитектуру и поддержку
Даёт управляемую безопасность и аудит действий	Требует дисциплины в проектировании инструментов и прав
Улучшает устойчивость к ошибкам и long-running задачам	Может увеличивать latency и стоимость инференса
Позволяет масштабировать от single-agent к multi-agent	Риск “переинженерить” систему раньше времени

---

🔗 Связи

• _Agentic Systems Index — системная карта агентных архитектур.
• _Frameworks Index — ориентир по LangChain, CrewAI, AutoGen и другим фреймворкам.
• _MCP Index — как подключать внешние инструменты и серверы к агентам.
• Инструкция по эксплуатации — прикладные рабочие процессы и операционные практики.
• _Glossary Index — термины по памяти, контексту, оркестрации и guardrails.

Теги: ai agents architecture contextengineering llmops