Внутреннее устройство Harness-агентов: разбор исходников Codex, OpenCode, Pi и собственных решений

Внутреннее устройство Harness-агентов: разбор исходников Codex, OpenCode, Pi и собственных решений

Разработка Harness-агентов — это одна из самых горячих тем в DevOps и AI-инженерии 2026 года. Harness-агент (Harness AI Agent) — это автономный программный компонент, который выполняет задачи в CI/CD-пайплайнах, управляет инфраструктурой, анализирует логи и принимает решения на основе машинного обучения. В отличие от обычных скриптов, Harness-агент способен адаптироваться к изменяющимся условиям, самообучаться и взаимодействовать с другими агентами.

Недавно на Хабре вышла статья, в которой автор подробно разобрал исходный код четырёх популярных Harness-агентов: Codex, OpenCode, Pi и собственного решения. Я внимательно изучил этот материал и хочу поделиться ключевыми выводами, архитектурными особенностями и практическими уроками, которые можно извлечь из этого анализа.

Почему Harness-агенты стали мейнстримом в 2026 году?

Традиционные CI/CD-системы (Jenkins, GitLab CI, GitHub Actions) работают по принципу «заранее написанный скрипт — фиксированный результат». Но современные проекты требуют гибкости: инфраструктура меняется ежедневно, появляются новые уязвимости, а команды хотят автоматизировать не только сборку, но и мониторинг, инцидент-менеджмент, оптимизацию затрат на облако.

Harness-агенты решают эти задачи, потому что:
- Адаптивность: агент может перепланировать задачи при сбое, не останавливая пайплайн.
- Самообучение: агент анализирует историю выполнения и улучшает свои алгоритмы.
- Интеграция: агенты легко подключаются к Kubernetes, Terraform, Prometheus, ArgoCD и другим инструментам.
- Безопасность: агенты могут проверять код на уязвимости прямо во время сборки.

В статье на Хабре автор разобрал четыре реализации. Давайте посмотрим, чем они отличаются.

1. Codex: агент-трансформер для анализа кода

Codex — это Harness-агент, специализирующийся на статическом анализе кода и автоматическом рефакторинге. Он построен на архитектуре transformer и использует модель, обученную на миллионах open-source репозиториев.

Ключевые особенности из исходников:

• Модуль токенизации: Codex разбивает код на токены не по пробелам, а по синтаксическим конструкциям (функции, классы, циклы). Это позволяет модели лучше понимать контекст.
• Граф зависимостей: агент строит граф вызовов между функциями, чтобы определять «узкие места» и предлагать оптимизации.
• Механизм внимания (attention): в исходниках автор обнаружил кастомную реализацию attention, которая фокусируется на ошибках компиляции и предупреждениях линтера.

Пример из кода (упрощённо):

def analyze_code(file_path):
    tokens = tokenize_by_syntax(file_path)
    ast = build_ast(tokens)
    graph = build_call_graph(ast)
    issues = attention_model(graph)
    return generate_fixes(issues)

Практический вывод: если вы пишете собственного агента для анализа кода, стоит начинать не с нейросети, а с построения AST-дерева и графа зависимостей. Это даёт 80% результата при 20% усилий.

Ограничения Codex:

• Агент работает только с Python и JavaScript (другие языки не поддерживаются).
• Высокие требования к памяти (более 8 ГБ на один инстанс).
• Не умеет выполнять код — только анализировать.

2. OpenCode: агент с открытым исходным кодом для CI/CD

OpenCode — это полностью open-source Harness-агент, который можно развернуть в собственном кластере Kubernetes. Его исходный код опубликован на GitHub, и автор статьи детально его разобрал.

Архитектура OpenCode:

OpenCode состоит из трёх микросервисов:
1. Orchestrator — принимает задачи от пользователя, разбивает их на подзадачи и распределяет между worker'ами.
2. Worker — выполняет конкретные действия (запуск скриптов, применение Terraform, проверка линтером).
3. Memory Store — хранит историю выполнения, ошибки и контекст для обучения.

В исходниках автор нашёл интересный механизм rollback-агента: если worker завершился с ошибкой, Orchestrator автоматически запускает «чистый» worker на предыдущем коммите и сравнивает результаты. Это позволяет откатывать изменения без участия человека.

Пример конфигурации OpenCode (YAML):

tasks:
  - name: deploy-to-staging
    agent: opencode
    steps:
      - action: build
        image: node:20
      - action: test
        command: npm run test
      - action: deploy
        target: staging
    rollback:
      enabled: true
      strategy: previous_commit

Проблемы, которые вскрыл разбор:

• OpenCode использует устаревшую версию библиотеки для работы с Kubernetes (client-go v0.24), что может вызвать конфликты с современными кластерами.
• Отсутствует механизм проверки безопасности контейнеров перед запуском.
• Логирование реализовано через stdout, что усложняет интеграцию с централизованными системами (ELK, Splunk).

Тем не менее, OpenCode — отличная база для создания собственного агента, если вы готовы дорабатывать его под свои нужды.

3. Pi: агент-помощник для инцидент-менеджмента

Pi — это Harness-агент, предназначенный для автоматического реагирования на инциденты в production-среде. Он мониторит метрики (CPU, память, ошибки 5xx) и, при превышении порогов, выполняет действия: перезапуск сервисов, масштабирование, отправка уведомлений.

Что автор нашёл в исходниках Pi:

• Двухуровневая модель принятия решений:
• Первый уровень — правила if-then-else (быстрые, но жёсткие).
• Второй уровень — нейросеть, обученная на исторических инцидентах (медленная, но точная).
• Механизм «тихих часов» (quiet hours): агент не выполняет автоматические действия в заданные часы (например, 2-4 ночи), чтобы избежать случайных перезапусков.
• Интеграция с PagerDuty: Pi умеет создавать инциденты и эскалировать их, если не получил подтверждения от дежурного.

Пример из кода Pi:

def handle_incident(metric, threshold):
    if metric > threshold:
        if not is_quiet_hours():
            action = fast_rule_based(metric)
            if action is None:
                action = neural_network.predict(metric)
            execute_action(action)
        else:
            log_incident()
    else:
        return

Критические замечания:

• Модель нейросети была обучена на синтетических данных, поэтому в реальных условиях точность падает на 15-20%.
• Pi не проверяет, не вызвал ли инцидент сам агент (например, перезапуск сервиса, который был в норме).
• Отсутствует версионирование конфигураций — если агент обновился, старые правила теряются.

Тем не менее, идея двухуровневой системы (правила + ML) очень перспективна. Многие компании в 2026 году внедряют именно такой подход, потому что он сочетает скорость и гибкость.

4. Собственное решение автора: гибридный агент на основе RAG

Автор статьи не только разобрал чужие агенты, но и представил собственную разработку — гибридный Harness-агент, использующий RAG (Retrieval-Augmented Generation). Суть подхода: агент не обучается на всём коде заранее, а в реальном времени извлекает нужную информацию из базы знаний (документация, предыдущие инциденты, код репозитория).

Архитектура:

1. Retriever — ищет релевантные фрагменты в векторной БД (например, Qdrant).
2. Generator — использует LLM (GPT-4 или Llama 3) для генерации ответа/действия на основе найденных фрагментов.
3. Executor — выполняет действие в среде (bash, kubectl, API).

Пример запроса к агенту:

Пользователь: "Почему упал сервис payment после деплоя версии 2.3?"
Агент:
1. Ищет в векторной БД логи деплоя версии 2.3.
2. Находит, что был изменён конфиг базы данных.
3. Генерирует ответ: "Сервис упал из-за неверного connection string в конфиге. Рекомендую откатить конфиг до версии 2.2."

Плюсы подхода:

• Не требует дорогостоящего обучения модели под конкретный проект.
• Легко адаптируется к изменениям (достаточно обновить базу знаний).
• Прозрачность: можно посмотреть, какие фрагменты использовал агент для принятия решения.

Минусы:

• Задержка: на поиск и генерацию уходит 2-5 секунд (против 0.1 секунды у правил).
• Зависимость от качества базы знаний: если документация устарела, агент будет выдавать неверные рекомендации.
• Высокие затраты на LLM (каждый запрос стоит денег).

Сравнительная таблица агентов

Практические уроки для разработчиков Harness-агентов

На основе разбора исходников можно сформулировать несколько практических рекомендаций:

1. Начинайте с правил, добавляйте ML позже

Автор статьи отмечает, что во всех агентах (кроме гибридного) основа — это правила if-then-else. Нейросеть используется только для сложных случаев. Не пытайтесь сразу обучить модель — сначала напишите детерминированные сценарии для 80% ситуаций.

2. Используйте векторные БД для контекста

Даже если вы не строите полноценный RAG-агент, храните историю выполнения и логи в векторной базе (Qdrant, Milvus, Weaviate). Это позволит агенту «вспоминать» прошлые ошибки и не повторять их.

3. Внедрите механизм rollback

Как показывает пример OpenCode, автоматический откат при ошибке — критически важная функция. Без неё агент может «уронить» production случайным действием. Реализуйте хотя бы простой rollback к предыдущему стабильному состоянию.

4. Тестируйте агента на синтетических данных, но проверяйте на реальных

Pi показал, что синтетические данные не отражают всей сложности реальных инцидентов. Используйте исторические данные из production для обучения, а синтетику — только для начальной настройки.

5. Не забывайте про безопасность

Ни один из разобранных агентов не имеет встроенной проверки команд на безопасность. Если агент выполняет bash-скрипты или применяет Terraform, убедитесь, что он не может случайно выполнить опасную операцию (например, rm -rf /). Используйте sandbox-окружение.

Как внедрить Harness-агента в существующий пайплайн?

Допустим, вы хотите добавить агента в свой CI/CD на базе GitLab CI или GitHub Actions. Вот минимальный план:

1. Определите задачу: что агент будет делать? (анализ кода, автоматический деплой, мониторинг)
2. Выберите базовую архитектуру: если задача простая — возьмите OpenCode и доработайте. Если сложная — рассмотрите гибридный RAG-подход.
3. Разверните агента: используйте Docker или Kubernetes. Убедитесь, что агент имеет доступ к необходимым API (GitHub, Kubernetes, базы данных).
4. Настройте правила: напишите первые сценарии (если ошибка компиляции — остановить пайплайн; если тесты упали — отправить уведомление).
5. Добавьте обучение: собирайте логи выполнения, размечайте успешные и неуспешные действия, обучайте модель.
6. Тестируйте в staging: запустите агента на тестовой среде, проверьте, что он не делает ничего лишнего.
7. Постепенно внедряйте в production: начните с действий, которые не могут навредить (например, отправка уведомлений), затем переходите к автоматическим исправлениям.

Заключение

Разбор исходников Codex, OpenCode, Pi и гибридного агента показал, что Harness-агенты — это не магия, а инженерная работа, сочетающая классические правила, микросервисную архитектуру и машинное обучение. Каждый из подходов имеет свои сильные и слабые стороны, и выбор зависит от конкретной задачи.

Главный вывод: не пытайтесь построить универсального агента сразу. Начните с малого — автоматизируйте одну рутинную задачу, используя открытые компоненты (OpenCode, Qdrant, LLM). Со временем вы сможете расширить функциональность и адаптировать агента под свои нужды.

Для тех, кто хочет глубже изучить тему, рекомендую прочитать оригинальную статью на Хабре — там автор приводит фрагменты кода и подробные комментарии к каждому агенту. Это отличная база для собственных экспериментов.

Источник

Статья подготовлена на основе анализа исходного кода, опубликованного в открытых источниках. Все упомянутые инструменты и библиотеки актуальны на июль 2026 года.