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 — ограничение прав, аудит действий, изоляция процессов.
Пример запуска простого агента, который суммирует числа из файла:
bashecc 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.
Типичный набор навыков
yamlskills:
- search # поиск в интернете через DuckDuckGo
- python_repl # интерактивный Python‑интерпретатор
- file_browse # чтение/запись файлов в контейнере
- calculator # простейшие арифметические операции
Как включить навык
bashexport 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 в хосте.
bashdocker 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. Пример конфигурации скрейпа:
yamlscrape_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, количество ошибок) и реагировать на аномалии в реальном времени.
Подходы:
- Экспорт метрик в Prometheus – простой способ, не требующий отдельного сервиса.
- Loki + Grafana – удобно, если уже используете ELK‑стек.
- 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.