Продвинутый

affaan-m/ECC: Agent Harness Performance for Claude

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

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

affaan-m/ECC: Agent Harness Performance for Claude

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

Архитектура и принципы работы agent harness

General concept

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

Основная идея — разделить responsibilities:

  • Core engine — оркестрация запросов, управление памятью и контекстом.
  • Agent plugins — конкретные навыки (поиск, анализ, генерация кода).
  • Security layer — ограничение прав, аудит действий, изоляция процессов.

Пример запуска простого агента, который суммирует числа из файла:

bash
ecc run agent \
  --config ./agent_config.yaml \
  --prompt "Суммировать все числа в файле numbers.txt"

Команда читает конфиг, инициализирует память, проверяет наличие нужных инструментов и передаёт запрос агенту.

Для сравнения с другими решениями см. Оптимизация ИИ‑агентов с помощью системы ECC.

Modular structure

Core engine

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

yaml
# core.yaml
memory:
  type: file
  path: ./memory.bin
  max_size_mb: 512
orchestrator:
  timeout_sec: 30
  retry_attempts: 3
  • Почему так: файловый тип памяти позволяет быстро сохранять/загружать состояние без лишних зависимостей, а ограничение по размеру предотвращает переполнение ОЗУ на домашних серверах.

Agent plugins

Каждый плагин реализует интерфейс AgentSkill. Пример плагина для работы с файловой системой:

python
# file_agent.py
class FileAgent(AgentSkill):
    def __init__(self, sandbox_path: str):
        self.sandbox = sandbox_path

    async def execute(self, request: Request) -> Response:
        # безопасный доступ только к директории sandbox
        if not request.path.startswith(self.sandbox):
            raise PermissionError("выход за пределы sandbox")
        # дальнейшая логика...
  • Ключевой момент: каждый плагин работает в изолированном контейнере (docker — non‑root, read‑only FS). Это снижает риск эксплуатации уязвимостей.

Security layer

Включает проверку прав, аудит действий и ограничение сетевого доступа.

bash
# пример правила iptables для агента
iptables -A OUTPUT -p tcp --dport 8080 -m owner --uid-owner ecc_user -j ACCEPT
iptables -A OUTPUT -p tcp --dport 8080 -j DROP
  • Почему важно: даже если плагин получит вредоносный запрос, ограниченный сетевой доступ и обязательная проверка UID предотвращают несанкционированные внешние соединения.

Связь с другими решениями

Идея модульного подхода перекликается с подходом в DietrichGebert/ponytail: AI‑agent like the lazy senior dev — каждый «ленивый» разработчик получает готовый набор инструментов, а не пишет всё с нуля.

Также принцип разделения ответственности отражен в Orca: запуск флота AI‑агентов с собственной подпиской — оркестрация большого количества агентов через единый контроллер.


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

  • Оценить текущий объём памяти и при необходимости увеличить max_size_mb в core.yaml.
  • Создать изолированный контейнер для каждого плагина (docker run --rm -u ecc_user).
  • Протестировать правила iptables в staging‑окружении, убедиться в отсутствии утечек.
  • Подключить мониторинг (Prometheus + Grafana) для сбора метрик engine‑latency и memory_usage.
  • Рассмотреть интеграцию с Wazuh для аудита действий агента.

Навыки, память и контекст

Интеллектуальные навыки

Агент‑харнесс ECC предоставляет набор готовых навыков, которые можно включать или отключать в зависимости от задачи.
Каждый навык – это отдельный процесс, который получает контекст из окна max_context_tokens и взаимодействует с моделью через API.

Типичный набор навыков

yaml
skills:
  - search          # поиск в интернете через DuckDuckGo
  - python_repl     # интерактивный Python‑интерпретатор
  - file_browse     # чтение/запись файлов в контейнере
  - calculator      # простейшие арифметические операции

Как включить навык

bash
export ECC_SKILL=python_repl   # включаем Python‑REPL
docker run -e ECC_SKILL=python_repl affaan-m/ecc:latest

Ограничения

  • Каждый навык добавляет собственный блок контекста, поэтому при включении нескольких навыков уменьшайте max_context_tokens.
  • В продакшн‑среде категорически не рекомендуется включать file_browse и python_repl без строгой проверки входных данных – это типичная ошибка, приводящая к remote‑code‑execution.

Оптимизация ИИ‑агентов с помощью системы ECC — подробный разбор того, как навыки влияют на потребление памяти.

Длинный контекст и память

ECC использует скользящее окно для хранения контекста. По умолчанию окно = 32 000 токенов, что позволяет работать с большими документами, но расходует значительную часть RAM.

Настройка размера контекста

bash
# Ограничиваем контекст до 8 К токенов
export ECC_MAX_CONTEXT=8192
docker run -e ECC_MAX_CONTEXT=8192 affaan-m/ecc:latest
json
{
  "max_context_tokens": 8192,
  "memory_limit_mb": 2048
}

Практические рекомендации

  • При работе с большими файлами (например, логами > 10 МБ) включайте file_browse и задавайте max_context_tokens ≈ 16 000, иначе модель будет «терять» часть данных.
  • Для экономии памяти используйте квантование модели (--quantize int8) – это уменьшает потребление RAM без заметной потери качества.

DietrichGebert/ponytail: AI‑agent like the lazy senior dev — примеры эффективного использования длинного контекста в реальных задачах.

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

Запуск флота AI‑агентов с Orca — дополнительные приёмы снижения нагрузки на память.

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

  • Оцените текущий объём контекста в ваших сценариях (токены ≈ ¾ от количества символов).
  • Установите ECC_MAX_CONTEXT не выше 16 000 токенов, если нет необходимости в полной длине документа.
  • Отключайте неиспользуемые навыки (ECC_SKILL=none) в production‑среде.
  • Применяйте квантование модели (--quantize int8) для экономии RAM.
  • Регулярно проверяйте потребление памяти (top, htop) и корректируйте memory_limit_mb.

Следуя этим рекомендациям, вы сможете поддерживать высокий уровень производительности агентов без риска перерасхода памяти и падения сервиса.

Безопасность и аудит

Уровни изоляции

Для защиты agent‑harness от влияния внешних факторов применяются несколько уровней изоляции.
Сначала запускаем контейнер в отдельном пользовательском нейспейсе, чтобы процесс не имел привилегий root в хосте.

bash
docker run -d \
  --name claude-agent \
  --user 1001:1001 \
  --read-only \
  --security-opt no-new-privileges:true \
  --security-opt seccomp=./seccomp.json \
  affaan-m/ecc:latest
  • --user – задаёт UID/GID, не совпадающие с root.
  • --read-only – делает файловую систему только для чтения, исключая запись в корень.
  • --security-opt no-new-privileges – запрещает процессу получать новые привилегии через setuid.
  • seccomp.json – профиль, ограничивающий системные вызовы (пример ниже).

Типичная ошибка – запуск контейнера без --read-only и без ограничения возможностей, что позволяет агенту модифицировать хост‑систему.

На практике я видел случай, когда агент, запущенный без --security-opt no-new-privileges, получил доступ к /proc и смог изменить параметры ядра, что привело к эскалации привилегий.

Для сетевой изоляции используем nftables, открывая только необходимый порт (например, 8443 для TLS‑соединений).

bash
# /etc/nftables.conf
#!/usr/sbin/nft -f

flush ruleset

table inet filter {
    chain input {
        type filter hook input priority 0; policy drop;
        iif "lo" accept
        ct state established,related accept
        tcp dport 8443 ct state new accept
        # разрешаем только TLS‑трафик
    }
}

После изменения правил проверяем их через nft list ruleset.

В контексте оптимизации агентов полезен материал Оптимизация ИИ-агентов с помощью системы ECC, где рассматриваются ограничения ресурсов и их влияние на безопасность.

Логирование и мониторинг

Централизованное логирование позволяет быстро реагировать на инциденты.
Рекомендуется использовать journald в сочетании с auditd для фиксации системных вызовов контейнеров.

bash
# Пример правила auditd для отслеживания изменений в конфигурации Docker
-a always,exit -F arch=b64 -S chmod -S fchmodat -S fchmod -k docker_config
-a always,exit -F arch=b64 -S openat -S open -S openat2 -k docker_file_access

Логи собираются в центральный Loki‑инстанс, где можно построить запросы в реальном времени.

promql
{job="docker-container"} | json |~ "error|fail|panic"

Для мониторинга нагрузки и отклика агентов удобно использовать Prometheus + Grafana. Пример конфигурации скрейпа:

yaml
scrape_configs:
  - job_name: 'ecc-agent'
    static_configs:
      - targets: ['10.0.0.5:9100']

Fail2ban может блокировать IP‑адреса, которые слишком часто идут в логах как подозрительные. Пример фильтра:

ini
[Definition]
failregex = ^.*\s+Failed to authenticate.*\s+from <HOST>.*$
ignoreregex =

На практике я видел случай, когда агрессивный сканер попытался brute‑force SSH‑ключи, используемые агентом для доступа к репозиторию; Fail2ban заблокировал его через 5 минут, что предотвратило дальнейшие попытки.

Для аудита соответствия требованиям (PCI‑DSS, NIST) удобно подключить Wazuh. Он автоматически проверяет наличие seccomp‑профиля, read‑only файлой системы и корректные настройки nftables.

Список дальнейших действий (чек‑лист) после внедрения изоляции и мониторинга:

  • Проверить, что контейнер запущен с --read-only и --security-opt no-new-privileges.
  • Убедиться, что seccomp‑профиль загружен и не пустой.
  • Проверить правила nftables (nft list ruleset).
  • Включить auditd и убедиться, что правила записывают события в /var/log/audit/audit.log.
  • Настроить Loki‑пipeline для фильтрации ошибок и паник.
  • Подключить Prometheus‑метрики в Grafana‑дашборд.
  • Запустить Fail2ban с актуальными фильтрами.
  • Провести аудит через Wazuh и устранить выявленные отклонения.

Следуя этим рекомендациям, вы создадите надёжную изоляцию и прозрачное логирование, что критически важно для безопасной работы agent‑harness в production‑среде.

Интеграция в CI/CD и DevOps

### CI/CD пайплайны

Интегрировать agent harness в CI/CD‑процесс позволяет проверять производительность, потребление памяти и безопасность каждого изменения перед тем, как оно попадёт в продакшн.

Ключевые моменты:

  • Тесты должны запускаться в изолированном окружении, без доступа к секретным данным.
  • При неудаче пайплайн должен завершиться ошибкой — это предотвращает развёртывание регрессий.
  • Рекомендуется использовать кэш зависимостей и матрицу тестов для разных моделей (Claude, Claude‑Code, Opencode).
yaml
# .github/workflows/agent-harness.yml
name: Agent Harness CI

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        model: [ claude, claude-code, opencode ]
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run harness tests
        run: |
          python -m ecc.run_tests \
            --model ${{ matrix.model }} \
            --timeout 300 \
            --max-memory 4096MiB
        # При превышении таймаута или памяти тест падает, CI считается неуспешным

Важно: не запускайте тесты с привилегированными контейнерами в production‑окружении. Используйте отдельный namespace или sandbox‑контейнер.

Оптимизация ИИ‑агентов с помощью системы ECC — подробный разбор, как правильно настроить такие пайплайны в домашних серверах.


Автоматический мониторинг

Для поддержания стабильности агентов в CI/CD и DevOps‑окружениях требуется собирать метрики (latency, CPU/Memory, количество ошибок) и реагировать на аномалии в реальном времени.

Подходы:

  1. Экспорт метрик в Prometheus – простой способ, не требующий отдельного сервиса.
  2. Loki + Grafana – удобно, если уже используете ELK‑стек.
  3. CrowdSec/Fail2ban – блокировать IP‑адреса, генерирующие подозрительные запросы от агентов.

Пример экспорта метрик (Python)

python
# metrics.py
from prometheus_client import Counter, Gauge, start_http_server

# Счётчики
requests_total = Counter('agent_requests_total', 'Общее количество запросов к агенту')
errors_total = Counter('agent_errors_total', 'Количество ошибочных запросов')

# Гибкие индикаторы
memory_usage = Gauge('agent_memory_usage_bytes', 'Текущее потребление памяти')
cpu_usage = Gauge('agent_cpu_usage_percent', 'Текущая загрузка CPU в %')

def inc_requests():
    requests_total.inc()

def inc_errors():
    errors_total.inc()

def set_memory(bytes_value):
    memory_usage.set(bytes_value)

def set_cpu(percent):
    cpu_usage.set(percent)

if __name__ == '__main__':
    start_http_server(8000)   # Prometheus будет scrapить http://<host>:8000/metrics

Интеграция в CI/CD:

  • Добавьте отдельный job, который периодически (например, каждые 5 минут) скрейпит метрики и отправляет алерты в Slack или Telegram‑бот (через webhook).
  • При превышении порогов (например, > 80 % CPU или > 4 GB памяти) пайплайн должен автоматически откатить изменения.
yaml
# Пример шага в GitHub Actions
      - name: Check agent health
        run: |
          curl -s http://localhost:8000/metrics | grep -E 'agent_memory_usage_bytes|agent_cpu_usage_percent' | \
          awk '$2+0 > 80 {exit 1}'
        # При ошибке job завершится с кодом 1 → откат в PR

Защита от злоупотреблений

  • Never запускайте не проверенные агенты в production‑контейнере без ограничения ресурсов (--memory, --cpus).
  • Категорически не рекомендуется использовать privileged: true в Docker‑композициях.
yaml
# docker‑compose.example.yml ( безопасный вариант )
version: "3.9"
services:
  agent-harness:
    image: ghcr.io/affaan-m/ecc:latest
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 2G
    security_opt:
      - no-new-privileges:true
    # Запуск в изолированном пользовательском неймспейсе
    user: "1000:1000"

Запуск флота AI‑агентов с Orca — пример, как масштабировать и мониторить множество агентов в одном кластере, включая автоматический сбор метрик и оповещения.


Чек‑лист для CI/CD + мониторинга

  • Пайплайн запускает ecc.run_tests с ограничением памяти и таймаутом.
  • Метрики экспортируются в Prometheus (порт 8000 или аналогичный).
  • Аллерты настроены на превышение CPU > 80 % или памяти > 4 GB.
  • Docker‑/K8s‑манифесты ограничивают ресурсы (limits, requests).
  • Используются не‑privileged контейнеры и no-new-privileges.
  • Все конфиги проверены на соответствие правилам русской типографии (quotes «», dash —).

Следуя этим рекомендациям, вы обеспечите надёжную интеграцию agent harness в CI/CD и DevOps‑процессы, а также будете быстро реагировать на любые отклонения в поведении агентов.

Часто задаваемые вопросы

Как agent harness влияет на производительность AI‑агентов по сравнению с другими решениями?

Agent harness повышает производительность за счёт уменьшения накладных расходов на обработку запросов и оптимизированного управления контекстом. Встроенный core engine минимизирует сериализацию и передачу данных, что приводит к снижению латентности по сравнению с более тяжёлыми фреймворками. На практике при одинаковом объёме токенов latency падает на 15‑20 %.

Какие требования предъявляются к памяти и как её тип влияет на скорость работы?

Для памяти рекомендуется использовать файловый тип с ограничением размера, например 512 МБ, что позволяет быстро сохранять и загружать состояние без переполнения ОЗУ на домашних серверах. Файловый тип избегает дополнительных зависимостей и ускоряет I/O‑операции, особенно при частом сохранении контекста. При превышении указанного лимита может произойти падение производительности из‑за частого свопинга.

Как обеспечивается безопасность выполнения агентов и какие ограничения устанавливаются на их права?

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

Можно ли использовать agent harness с другими моделями, кроме Claude (например, Codex, Opencode, Cursor)?

Agent harness изначально поддерживает любые модели, для которых доступен соответствующий skill‑плагин, включая Codex, Opencode и Cursor. Необходимо лишь адаптировать интерфейс AgentSkill и указать нужные инструменты в конфигурации. При правильной настройке производительность и безопасность остаются на уровне, сопоставимом с работой с Claude.

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

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