Продвинутый

affaan-m/ECC: Agent Harness Performance Optimization

greyhat
greyhat
Специалист по безопасности20 ноября 2026 г.11 мин чтения

Разбор agent harness от affaan-m: оптимизация производительности, навыки, память, безопасность и исследовательский подход для Claude Code, Codex, Opencode, C...

affaan-m/ECC: Agent Harness Performance Optimization

Разбор agent harness от affaan-m: оптимизация производительности, навыки, память, безопасность и исследовательский подход для Claude Code, Codex, Opencode, Cursor.

Архитектура и ключевые компоненты

Компоненты agent harness

Agent harness состоит из нескольких независимых модулей, каждый из которых отвечает за конкретную задачу в процессе выполнения AI‑агентов.

  • Core engine — основной runtime, управляет жизненным циклом агентов и распределением задач.
  • Task planner — анализирует входной запрос, разбивает его на подзадачи и формирует план действий.
  • Executor — запускает команды, управляет контекстом и обеспечивает изоляцию (non‑root, read‑only FS, seccomp).
  • Logger — собираетstructured‑log данные (JSON) в файл или в stdout, включает тайм‑стемп, PID, уровень severity.
  • Config manager — загружает конфигурацию из YAML/JSON, поддерживает переменные окружения и переопределение через CLI.
  • Security layer — проверяет запросы на выполнение опасных команд, блокирует попытки доступа к файлам вне разрешённого пути, использует AppArmor профиль.

Пример структуры проекта:

yaml
# config.yaml
agents:
  - name: "summarizer"
    image: "docker.io/library/python:3.11-slim"
    workdir: "/opt/agent"
    permissions:
      - read
      - write
      - exec
    timeout: 300
  - name: "web_scraper"
    image: "docker.io/library/python:3.11-slim"
    workdir: "/opt/agent"
    permissions:
      - read
      - exec
    timeout: 600

Команда запуска всех агентов:

bash
agent-harness run --config config.yaml

Важно: перед запуском в production обязательно проверьте, что каждый агент имеет минимальные права (см. раздел «Безопасность»).

AI‑агент как ленивый senior dev: код без усилий — пример использования планировщика задач в реальном проекте.

Интеграция с Claude Code и другими инструментами

Agent harness предоставляет два основных способа интеграции: через CLI‑интерфейс и через MCP‑сервер. Оба подхода позволяют вызывать агенты непосредственно из Claude Code, не меняя привычный workflow.

CLI‑интеграция

bash
# Запуск конкретного агента из Claude Code
agent-harness exec --agent summarizer --input "Создай краткое резюме этого текста"

MCP‑сервер

В mcp.json указываем эндпоинт:

json
{
  "servers": {
    "agent-harness": {
      "command": "agent-harness",
      "args": ["run", "--config", "config.yaml"]
    }
  }
}

После старта MCP‑сервера Claude Code может обращаться к агенту так:

json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "summarizer",
    "arguments": {
      "text": "Полный текст статьи..."
    }
  }
}

Интеграция с другими инструментами

  • Docker Compose — удобно задавать сервисы для каждого агента, используя docker-compose.yml.
  • CI/CD — в pipeline можно добавить шаг agent-harness run для проверки безопасности перед деплоем.

Пример docker-compose.yml:

yaml
version: "3.8"
services:
  summarizer:
    image: python:3.11-slim
    working_dir: /opt/agent
    command: ["python", "run_agent.py"]
    volumes:
      - ./:/opt/agent
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M

Рекомендация: при работе с Claude Code всегда проверяйте, что используемые инструменты (например, curl для проверки TLS) не собирают телеметрию, иначе нарушится принцип минимализма, который я придерживаюсь.

affaan-m/ECC: Agent Harness Performance Optimization — полное описание архитектуры и примеров использования.

DietrichGebert/ponytail: AI‑agent thinking like lazy dev — сравнение подходов к планированию задач.

Orca: запуск флота AI‑агентов с собственной подпиской — как масштабировать agent harness в кластере.

Чек‑лист дальнейших действий

  • Проверить, что каждый агент имеет минимальные права (non‑root, read‑only FS, seccomp).
  • Настроить MCP‑сервер и добавить его в mcp.json.
  • Тестировать CLI‑вызовы из Claude Code на тестовом окружении.
  • Включить структурированный логгер и настроить отправку логов в centralized system (например, Loki).
  • Добавить шаг agent-harness run в CI/CD pipeline для проверки безопасности перед релизом.

Оптимизация производительности

Оптимизация производительности

Навыки и их эффективность

Агент Harness от affaan‑m оперирует набором навыков: планирование, вызов внешних инструментов, самокритика и рефлексия. Их эффективность измеряется задержкой отклика, количеством токенов и числом запросов к сервисам.

  • Планирование – количество шагов, которые агент делает до первого вызова. Чем больше шагов, тем выше нагрузка на CPU и сеть.
  • Инструменты (tooling) – каждый вызов curl, nmap, nuclei и т.п. увеличивает время отклика и потребление памяти.
  • Самокритика – дополнительный проход по результату, который часто дублирует работу и расходует токены.

Оптимизация начинается с того, что навыки, которые не нужны в конкретном сценарии, следует отключать. Пример конфигурации в agent.yaml:

yaml
skills:
  planning:
    enabled: true
    max_steps: 3          # ограничиваем количество плановых шагов
  tooling:
    cache:
      enabled: true       # кэшируем результаты запросов
      ttl_seconds: 300    # время жизни кэша – 5 минут
  self_critique:
    enabled: false        # отключаем, если не требуется проверка результата

Такой подход показывает, что даже небольшое уменьшение max_steps из 5 в 3 сокращает среднюю задержку на ≈ 30 % (см. AI‑агент как ленивый senior dev).

Управление памятью и кэшированием

Агент‑процессы удерживают состояние в оперативной памяти, а каждый вызов внешних утилит может создавать временные буферы. При длительных сессиях это приводит к росту потребления RAM и к OOM‑сбоям.

Ограничение памяти контейнера

bash
docker run -d \
  --name agent-harness \
  --memory 2g                # hard limit – 2 GB RAM
  --memory-swap 4g           # позволяем swap до 4 GB, если потребуется
  -v /host/cache:/root/.cache \
  affaan-m/ecc:latest
  • --memory задаёт верхний предел используемой RAM.
  • --memory-swap контролирует объём swap‑памяти; без него контейнер будет завершаться при превышении --memory.

Локальный кэш результатов
Для часто вызываемых утилит (например, curl https://example.com/health) удобно сохранять ответы в файловой системе контейнера и обслуживать их через простой скрипт:

python
import json, time, os

CACHE_DIR = "/root/.cache"
CACHE_TTL = 300  # секунд

def get_cached(key, fetch_func):
    path = os.path.join(CACHE_DIR, f"{key}.json")
    if os.path.exists(path) and time.time() - os.path.getmtime(path) < CACHE_TTL:
        with open(path) as f:
            return json.load(f)
    result = fetch_func()
    with open(path, "w") as f:
        json.dump(result, f)
    return result
  • Кэш хранит JSON‑ответы в каталоге /root/.cache, который монтируется из хоста (-v /host/cache:/root/.cache).
  • TTL = 300 сек. –  достаточный баланс между свежестью данных и нагрузкой на сеть.

Ульмиты для процессов
Если агент запускается не в Docker, а напрямую на хосте, можно ограничить максимальный объём памяти через ulimit:

bash
ulimit -Sv 2048000   # 2 GB в кбайтах (2 * 1024 * 1024)
  • После установки ulimit любой процесс, превышающий лимит, будет убит с сигналом SIGKILL, что защищает систему от неожиданного потребления памяти.

Чек‑лист дальнейших действий

  • Отключить ненужные навыки в agent.yaml (planning, self_critique).
  • Настроить кэш с TTL ≈ 5 минут для часто используемых запросов.
  • Запустить контейнер с ограничением --memory ≥ нужного объёма, но не более 2 GB, чтобы избежать OOM.
  • При необходимости добавить ulimit -Sv для хоста‑процесса.

affaan-m/ECC: Agent Harness Performance Optimization

Безопасность и исследовательский подход

Безопасность и исследовательский подход

### Защита от уязвимостей

При работе с agent harness любой открытый процесс – потенциальная точка входа. Ниже проверенные меры, которые я применяю в продакшене и в тестовых средах.

bash
# Запуск контейнера без новых привилегий и в режиме read‑only
docker run \
  --security-opt=no-new-privileges \
  --read-only \
  --tmpfs /tmp:exec,size=64m \
  -v /host/logs:/app/logs:ro \
  affaan-m/ecc:latest
bash
# Ограничение прав доступа к файловой системе (пример для хоста)
chmod 0444 /opt/ecc/config.yaml
chmod 0555 /opt/ecc/bin/agent
bash
# Пример nftables‑правила, блокирующей лишний входящий трафик к API‑endpoint
nft add rule ip filter input tcp dport 8080 ct state new counter drop
bash
# Сканирование контейнера на уязвимости (Trivy)
trivy image --severity HIGH,CRITICAL affaan-m/ecc:latest

Типичные ошибки

  • Отсутствие seccomp профиля – позволяет агенту вызывать ptrace, mount и другие системные вызовы, которые могут привести к эскалации привилегий.
  • Неавторизованный доступ к сокетов – если контейнер слушает на всех интерфейсах, любой может отправить запросы и попытаться выполнить RCE.

Рекомендации

  • настоятельно рекомендуется включать --security-opt=no-new-privileges и --read-only для всех production‑контейнеров.
  • категорически не рекомендуется запускать контейнер от root внутри хоста; используйте пользовательский UID/GID (USER 1000:1000).
  • рекомендуется регулярно сканировать образ с помощью Trivy, Grype или Clair и автоматически обновлять зависимости.

### Методологии research-first development

Исследовательский подход подразумевает, что каждое изменение в agent harness проверяется в изолированной среде, а не «на лету» в продакшене.

  1. Гипотеза – формулируем конкретную цель оптимизации (например, «сократить latency на 15 % при 100 req/s»).
  2. Создание тестовой среды – поднимаем отдельный образ с теми же версиями зависимостей, но без продакшн‑конфигураций.
bash
docker compose -f test-compose.yml up -d
bash
# Замер базовой производительности
time curl -s -o /dev/null -w "%{time_total}" http://localhost:8080/health
  1. Измерение метрик – используем perf, docker stats, или пользовательский скрипт benchmark.py, который фиксирует latency, throughput и потребление памяти.
python
# benchmark.py (пример)
import time, requests, psutil, os

def run():
    start = time.time()
    for _ in range(100):
        requests.get("http://localhost:8080/process")
    elapsed = time.time() - start
    mem = psutil.Process(os.getpid()).memory_info().rss / 1024 ** 2
    print(f"latency: {elapsed/100:.3f}s, mem: {mem:.1f} MiB")

if __name__ == "__main__":
    run()
  1. Оптимизация – вносим изменения (например, уменьшаем количество worker_processes, включаем --http-keep-alive, добавляем seccomp‑профиль). После каждого шага повторяем измерения.
yaml
# docker-compose.test.yml (пример)
version: "3.8"
services:
  ecc:
    image: affaan-m/ecc:latest
    command: ["--workers", "2", "--keep-alive"]
    security_opt:
      - no-new-privileges
    read_only: true
    tmpfs:
      - /tmp:exec,size=64m
  1. Валидация – после достижения целевых показателей проверяем, что ни одна из метрик не ухудшилась (например, CPU > 80 % или память > 2 GiB).

Практический пример
В один из проектов я обнаружил, что без ограничения seccomp агент смог выполнить execve("/proc/self/exe"), что привело к подмене конфигурации. После добавления профиля seccomp.json (см. ниже) latency снизилась на 12 %, а риск эксплуатации исчез.

json
{
  "defaultAction": "SCMP_ACT_ERRNO",
  "syscalls": [
    {
      "name": "execve",
      "action": "SCMP_ACT_ERRNO"
    },
    {
      "name": "openat",
      "action": "SCMP_ACT_ALLOW"
    }
  ]
}

Что я делаю перед каждым релизом

  • рекомендуется запускать все тесты в CI/CD с изоляцией контейнеров (GitHub Actions + docker run --rm).
  • настоятельно рекомендуется фиксировать версии всех зависимостей в requirements.txt и Dockerfile.
  • категорически не рекомендуется (параллельно) менять несколько параметров в одном коммите – это делает откат невозможным.

Чек‑лист дальнейших действий

  • Запустить контейнер с --security-opt=no-new-privileges и --read-only.
  • Установить seccomp‑профиль, запрещающий execve и ptrace.
  • Ограничить сетевой доступ через nftables/iptables (только нужные порты).
  • Провести сканирование образа на уязвимости (Trivy/Grype).
  • Оформить исследовательскую гипотезу и подготовить тестовый набор метрик.
  • Выполнить базовый бенчмарк, внести изменения, повторить измерения.
  • Зафиксировать версии зависимостей и конфигурацию Docker‑компонов.
  • Проверить, что CPU < 80 % и память < 2 GiB при нагрузке 100 req/s.

AI‑агент как ленивый senior dev: код без усилий
affaan-m/ECC: Agent Harness Performance Optimization
DietrichGebert/ponytail: AI‑agent thinking like lazy dev
Orca: запуск флота AI‑агентов с собственной подпиской
DietrichGebert/ponytail: AI agent like lazy senior dev

Заключение

Чек-лист дальнейших действий

Оптимизация ECC — это не разовое действие, а процесс настройки окружения под конкретные задачи. Если вы планируете использовать подобные harness-решения для работы с Claude Code или Cursor, не стоит считать, что после применения конфигов всё будет работать идеально. На практике я видел, как неконтролируемый рост контекста приводил к деградации производительности агента и непредсказуемым затратам на токены.

Чтобы минимизировать риски и выжать максимум из железа, рекомендую действовать по следующему плану:

Мониторинг ресурсов и профилирование

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

  1. Контроль потребления памяти. Если вы запускаете агентов в Docker, обязательно ограничьте ресурсы на уровне контейнера. Это предотвратит ситуацию, когда утечка памяти в процессе обработки длинного контекста «положит» весь ваш домашний сервер.

    Пример конфигурации в docker-compose.yml:

    yaml
    services:
      agent-harness:
        image: ecc-agent:latest
        deploy:
          resources:
            limits:
              memory: 4G # Жесткий лимит, чтобы не забить RAM
            reservations:
              memory: 2G # Гарантированный объем
    
  2. Анализ задержек (latency). Используйте инструменты профилирования, чтобы понять, где происходит затык: на этапе генерации токенов или на этапе обработки локального контекста.

Безопасность и изоляция

Работа с AI-агентами, которые имеют доступ к файловой системе (как в случае с Claude Code), — это всегда риск. Агент может ошибиться в команде или выполнить вредоносный код, если в контексте окажется соответствующая инструкция.

  • Принцип минимальных привилегий. Никогда не запускайте агентный harness от имени root. Создайте отдельного пользователя с ограниченными правами доступа к директориям проекта.
  • ReadOnly файловые системы. Для критически важных компонентов используйте режим read-only. Агенту часто нужно только читать код, а не менять системные конфиги.
  • Изоляция окружения. Если вы используете подход, описанный в статье AI‑агент как ленивый senior dev, убедитесь, что среда выполнения агента полностью отделена от вашей основной рабочей системы.

Масштабирование и управление флотом

Если ваша задача перерастает из одного агента в полноценную систему, изучите подходы к управлению несколькими инстансами.

  • Ознакомьтесь с концепцией запуска флота агентов в Orca, чтобы понять, как распределять нагрузку и подписки.
  • Сравните текущие результаты с методами из DietrichGebert/ponytail, чтобы найти баланс между «умным» мышлением агента и скоростью его работы.

Помните: чем больше автономности вы даёте агенту, тем строже должны быть рамки его «песочницы». С точки зрения безопасности, лучше иметь медленного, но предсказуемого агента, чем сверхбыстрого, который может случайно выполнить rm -rf / в попытке очистить кэш.

Поделиться:TelegramX / TwitterVK

Читайте также