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
Команда запуска всех агентов:
bashagent-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:
yamlversion: "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:
yamlskills:
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‑сбоям.
Ограничение памяти контейнера
bashdocker 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) удобно сохранять ответы в файловой системе контейнера и обслуживать их через простой скрипт:
pythonimport 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:
bashulimit -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 проверяется в изолированной среде, а не «на лету» в продакшене.
- Гипотеза – формулируем конкретную цель оптимизации (например, «сократить latency на 15 % при 100 req/s»).
- Создание тестовой среды – поднимаем отдельный образ с теми же версиями зависимостей, но без продакшн‑конфигураций.
bashdocker compose -f test-compose.yml up -d
bash# Замер базовой производительности
time curl -s -o /dev/null -w "%{time_total}" http://localhost:8080/health
- Измерение метрик – используем
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()
- Оптимизация – вносим изменения (например, уменьшаем количество
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
- Валидация – после достижения целевых показателей проверяем, что ни одна из метрик не ухудшилась (например, 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, не стоит считать, что после применения конфигов всё будет работать идеально. На практике я видел, как неконтролируемый рост контекста приводил к деградации производительности агента и непредсказуемым затратам на токены.
Чтобы минимизировать риски и выжать максимум из железа, рекомендую действовать по следующему плану:
Мониторинг ресурсов и профилирование
Прежде чем внедрять агрессивные методы оптимизации памяти, нужно понять текущую точку отсчёта. Не делайте предположений о потреблении ресурсов — замеряйте их.
-
Контроль потребления памяти. Если вы запускаете агентов в Docker, обязательно ограничьте ресурсы на уровне контейнера. Это предотвратит ситуацию, когда утечка памяти в процессе обработки длинного контекста «положит» весь ваш домашний сервер.
Пример конфигурации в
docker-compose.yml:yamlservices: agent-harness: image: ecc-agent:latest deploy: resources: limits: memory: 4G # Жесткий лимит, чтобы не забить RAM reservations: memory: 2G # Гарантированный объем -
Анализ задержек (latency). Используйте инструменты профилирования, чтобы понять, где происходит затык: на этапе генерации токенов или на этапе обработки локального контекста.
Безопасность и изоляция
Работа с AI-агентами, которые имеют доступ к файловой системе (как в случае с Claude Code), — это всегда риск. Агент может ошибиться в команде или выполнить вредоносный код, если в контексте окажется соответствующая инструкция.
- Принцип минимальных привилегий. Никогда не запускайте агентный harness от имени
root. Создайте отдельного пользователя с ограниченными правами доступа к директориям проекта. - ReadOnly файловые системы. Для критически важных компонентов используйте режим
read-only. Агенту часто нужно только читать код, а не менять системные конфиги. - Изоляция окружения. Если вы используете подход, описанный в статье AI‑агент как ленивый senior dev, убедитесь, что среда выполнения агента полностью отделена от вашей основной рабочей системы.
Масштабирование и управление флотом
Если ваша задача перерастает из одного агента в полноценную систему, изучите подходы к управлению несколькими инстансами.
- Ознакомьтесь с концепцией запуска флота агентов в Orca, чтобы понять, как распределять нагрузку и подписки.
- Сравните текущие результаты с методами из DietrichGebert/ponytail, чтобы найти баланс между «умным» мышлением агента и скоростью его работы.
Помните: чем больше автономности вы даёте агенту, тем строже должны быть рамки его «песочницы». С точки зрения безопасности, лучше иметь медленного, но предсказуемого агента, чем сверхбыстрого, который может случайно выполнить rm -rf / в попытке очистить кэш.