affaan-m/ECC: Agent Harness Performance Optimization
The agent harness performance optimization system for Claude Code, Codex, Opencode, Cursor. Skills, instincts, memory, security, research‑first development.
Core Architecture and Key Components
Core Architecture and Key Components
Agent Skill Execution Model
Агентный харнесс выполняет набор навыков (skills) в виде отдельных шагов, каждый из которых изолирован в контейнере с ограниченными ресурсами. Это позволяет гарантировать безопасность и стабильность выполнения даже при работе с потенциально тяжёлыми задачами.
yamlskill:
name: "Deploy service"
entry: "docker run -d --name my-service myimage:latest"
timeout: 300
resources:
cpu: 1
memory: 512M
filesystem: read-only
security:
seccomp_profile: "docker/default"
user: "non-root"
- Изоляция – каждый skill запускается в отдельном контейнере, используя non‑root пользователя и read‑only файловую систему.
- Ограничения – задаются через
resources(CPU, memory) иtimeout. - Запуск – skill вызывается через CLI‑утилиту
orcacli:
bashorcacli skill run "Deploy service"
При отсутствии ограничения памяти типичная ошибка выглядит так: агент «съел» 80 % RAM сервера и привёл к OOM‑kill других подов. Поэтому рекомендуется явно указывать memory и cpu в конфиге навыка, а перед запуском в production проверить лимиты cgroup.
Для управления несколькими агентами см. Управление fleet-агентами разработки с Orca.
Memory Management Strategies
Харнесс использует несколько стратегий управления памятью, которые можно настроить per‑agent:
- Лимиты памяти на уровне контейнера – задаются при запуске Docker‑контейнера (
--memory,--memory-swap). - Конфигурационный файл агента – в YAML/JSON указываются
memory_limit_mb,swap_limit_mb,cache_ttl_seconds.
json{
"memory_limit_mb": 1024,
"swap_limit_mb": 256,
"cache_ttl_seconds": 3600
}
- cgroup‑государственные лимиты – позволяют изолировать память агента от других процессов хоста.
- Политика очистки кэша – кэш, используемый навыками, автоматически очищается после
cache_ttl_seconds.
Пример запуска агента с заданными лимитами:
bashdocker run -d \ --name agent-1 \ --memory=1g \ --memory-swap=1.5g \ --cpus=2 \ my/agent-harness:latest
На практике я видел случай, когда агент без ограничения памяти съел 80 % RAM сервера и привёл к падению других подов. Поэтому настоятельно рекомендуется задавать memory_limit_mb в конфиге агента и проверять cgroup‑лимиты перед запуском в production.
Для более детального управления ИИ‑агентами с помощью Orca см. Управление ИИ-агентами с помощью Orca.
Performance Tuning and Optimization
### Instinct-Based Decision Paths
Агент‑харнесс использует набор «инстинктов», которые определяют, какой инструмент или подпроцесс выбрать в текущем контексте. Правильная настройка этих инстинктов существенно повышает пропускную способность и уменьшает задержки.
Типичный инстинкт – это функция, которая проверяет наличие нужного ресурса, наличие кэша или наличие предварительно выполненного запроса.
yaml# ~/.config/ecc/instincts.yaml
instincts:
- name: "http_client"
condition: "request.method == 'GET' and cache.exists"
priority: 10
- name: "shell_executor"
condition: "request.cmd != '' and os.path.exists('/usr/bin/bash')"
priority: 8
- name: "fallback_api"
condition: "True"
priority: 1
Пример использования – запуск запроса через CLI:
bashecc run --instinct http_client https://api.example.com/query
Если инстинкт не срабатывает, хард‑кейс переходит к следующему в списке. Поэтому важно, чтобы условия были точными и приоритеты отражали реальную нагрузку.
Важно: перед изменением инстинктов всегда проверяйте текущие логи, иначе можно получить «бесконечный цикл» запросов.
Проверка логов в Orca показывает, как быстро находить падения инстинктов в fleet‑агентах.
### Resource Allocation and Profiling
Оптимизация производительности требует корректного распределения ресурсов (CPU, память, I/O) и систематического профилирования. Ниже – проверенные подходы, используемые в продакшене.
1. Ограничение ресурсов через cgroup
При запуске агента в Docker удобно задавать лимиты:
bashdocker run -d \
--name ecc_agent \
--cpus="2.5" \
--memory="4g" \
--memory-swap="6g" \
--pids-limit=100 \
-v $HOME/.ecc/config:/etc/ecc \
ecc-image:latest
Почему это работает: ограничение количества CPU‑ядров и объёма памяти предотвращает «залипание» процесса в случае утечки или DDoS‑атаки.
2. Профилирование с perf и flamegraph
Для выявления «узких мест» в пути исполнения используйте perf:
bash# Запуск профилирования в фоне
perf record -g -p $(pgrep -f ecc-agent)
# После 30 секунд сбора данных – генерируем flamegraph
perf script | ./stackcollapse-perf.pl > out.perf.gz
./flamegraph.pl out.perf.gz > ecc_flamegraph.svg
Открыв ecc_flamegraph.svg, видно, какие функции вызываются чаще всего. Если видите, что http_client.request занимает 70 % времени, значит, стоит пересмотреть кэш или использовать более лёгкий HTTP‑клиент.
3. Мониторинг в реальном времени
Для постоянного контроля загрузки используйте orca monitor (часть Orca‑suite). Пример команды:
bashorca monitor --agent ecc_agent --interval 5 --output json > /var/log/ecc/monitor.log
Данный журнал можно подключить к Grafana‑дашборду, чтобы видеть нагрузку по CPU, памяти и I/O в режиме реального времени.
Рекомендация: периодически (раз в неделю) пересматривайте профили и корректируйте лимиты, особенно после добавления новых инстинктов.
Подробный гайд по управлению fleet‑агентами описывает, как автоматизировать эти шаги в CI/CD pipeline.
Итоги
- Инстинкты – ядро принятия решений; настройте их в
instincts.yaml, проверяйте приоритеты и условия. - Ресурсы – ограничивайте через Docker‑cgroup, используйте
perfи flamegraph для профилирования, аorca monitor– для онлайн‑контроля.
Следуя этим практикам, вы сможете поддерживать высокий уровень отзывчивости agent harness‑а и минимизировать задержки в работе с Claude Code, Codex, Opencode и Cursor.
Security, Access Control, and Isolation
Secure Execution Environments
Для запуска агентов требуется строгая изоляция – это базовый уровень защиты с точки зрения безопасности.
Пользовательский контекст
- Запускайте процесс от имени non‑root пользователя.
- Ограничьте набор возможностей ядра через seccomp‑профиль.
- Делайте файловую систему read‑only, кроме директории, где агент пишет логи.
Пример запуска Docker‑контейнера
bashdocker run -d \
--name agent_harness \
--user 65534:65534 \ # non‑root UID/GID
--read-only \ # read‑only FS
--tmpfs /run \ # временный том для runtime‑данных
--security-opt seccomp=seccomp.json \ # профиль seccomp (см. ниже)
-v /var/log/agent_harness:/var/log/agent_harness \ # лог‑директория
affaan-m/ecc:latest
seccomp.json (минимальный набор системных вызовов)
json{
"defaultAction": "SCMP_ACT_ERRNO",
"syscalls": [
{ "name": "execve", "action": "SCMP_ACT_ALLOW" },
{ "name": "openat", "action": "SCMP_ACT_ALLOW" },
{ "name": "write", "action": "SCMP_ACT_ALLOW" },
{ "name": "read", "action": "SCMP_ACT_ALLOW" },
{ "name": "exit", "action": "SCMP_ACT_ALLOW" },
{ "name": "socket", "action": "SCMP_ACT_ALLOW" },
{ "name": "bind", "action": "SCMP_ACT_ALLOW" },
{ "name": "listen", "action": "SCMP_ACT_ALLOW" },
{ "name": "accept", "action": "SCMP_ACT_ALLOW" }
]
}
Ссылка на общую концепцию изоляции: Управление fleet‑агентами разработки с Orca.
Важно: Never run the agent harness in privileged mode — это открывает путь к полной компрометации системы.
Audit Logging and Threat Detection
Полный аудит действий агента позволяет быстро обнаружить аномальные запросы и предотвратить эксплуатацию.
Системный аудит (auditd)
bash# Запись всех execve, где запускается бинарник агента
auditctl -a always,exit -F arch=b64 -S execve -F exe=/usr/local/bin/agent_harness
# Мониторинг сетевых соединений TCP/UNIX
auditctl -a always,exit -F arch=b64 -S connect -F a0 = 0x2 # AF_INET
auditctl -a always,exit -F arch=b64 -S connect -F a0 = 0x10 # AF_UNIX
Journald (persistent logs)
bashmkdir -p /var/log/journal
systemd-journald --storage=persistent
Интеграция с Wazuh (пример правила)
xml<rule id="100100" level="7">
<if_sid>530</if_sid>
<match>syscheck</match>
<description>Agent Harness execution detected</description>
<group>syscheck</group>
</rule>
Falco (runtime detection)
yaml- rule: Unexpected privileged container exec
desc: Detect execve from non‑root user inside container
condition: container and not user=0 and syscall=execve
output: "Privileged exec (user=%user.name command=%proc.cmdline)"
priority: WARNING
Ссылка на методику аудита: AI‑агент как ленивый senior dev: код без усилий.
Рекомендации
- рекомендуется отправлять логи агента в удалённый syslog‑сервер по TLS (например, rsyslog + TLS).
- настоятельно рекомендуется включать auditd и Falco в baseline‑конфигурацию всех production‑узлов.
- категорически не рекомендуется отключать аудит после инцидента — сохранение полной цепочки событий критично для расследования.
Совет от greyhat: Перед включением любого нового модуля в production‑окружение проверяйте, что все связанные процессы находятся в отдельном namespace и не имеют доступа к глобальным сетевым интерфейсам. Это уменьшит поверхность атаки в случае компрометации.
Research‑First Development and Continuous Improvement
Research‑First Development and Continuous Improvement
Empirical Testing Frameworks
Для оценки реальной производительности агента harness’а применяется набор эмпирических тестов, которые имитируют типичные сценарии работы разработчиков. Каждый тест измеряется в количестве токенов, времени выполнения и нагрузки на CPU.
bash# Запуск базового бенчмарка (cloudeval)
docker run --rm -v $(pwd)/tests:/tests ghcr.io/anthropic/cloudeval \
--config /tests/benchmark.yaml \
--output /tests/results.json
yaml# benchmark.yaml – пример конфигурации теста
model: claude-3-sonnet
tasks:
- name: "code-completion"
prompt: "Write a function that sorts a list in Python."
timeout: 30s
- name: "reasoning"
prompt: "Explain the difference between TCP and UDP."
timeout: 45s
metrics:
- tokens_generated
- latency_ms
- cpu_usage_percent
Тесты запускаются в контейнере, чтобы исключить влияние внешних факторов. После каждой итерации результаты сохраняются в JSON‑файл, который затем анализируется с помощью скрипта analyze_results.py.
python# analyze_results.py – базовый скрипт анализа
import json, sys
data = json.load(open(sys.argv[1]))
print(f"Средняя задержка: {sum(t['latency_ms'] for t in data)/len(data):.1f} ms")
print(f"Токенов: {sum(t['tokens_generated'] for t in data)}")
Важно: результаты тестов фиксируются в репозитории, чтобы обеспечить воспроизводимость.
Feedback Loops and Versioning
Обратная связь от инженеров и автоматизированных систем интегрируется в процесс разработки через CI/CD‑конвейер и систему контроля версий. Каждый коммит проходит проверку качества (lint), а изменения в конфигурациях агента попадают в отдельный ветвление release/x.y.
yaml# .github/workflows/agent-ci.yml – пример CI‑pipeline
name: Agent CI
on:
push:
branches: [ main, release/* ]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build Docker image
run: docker build -t agent-harness:${{ github.sha }} .
- name: Run empirical tests
run: |
docker run --rm -v ${{ github.workspace }}/tests:/tests \
ghcr.io/anthropic/cloudeval --config /tests/benchmark.yaml
- name: Lint configuration
run: yamllint -c .yamllint.yaml .
Версионирование реализовано через Git‑теги в формате vX.Y.Z. Теги автоматически создаются после успешного прохождения всех тестов и публикации Docker‑образа.
bash# Создание тега и пуш в удалённый репозиторий
git tag -a v1.2.0 -m "Stable release with improved token efficiency"
git push origin v1.2.0
Для сбора обратной связи от пользователей используется система Issue‑Tracker, где каждый репорты автоматически привязывается к соответствующей версии через метку version.
Рекомендация: перед тем как зафиксировать новую версию, проверьте, что все эмпирические тесты прошли без регрессий. Если обнаружены отклонения, откатитесь к предыдущей версии и проведите дополнительный анализ.
Управление fleet-агентами разработки с Orca
affaan-m/ECC: Agent Harness Performance Optimization
Управление ИИ-агентами с помощью Orca
AI‑агент как ленивый senior dev: код без усилий
Часто задаваемые вопросы
Как правильно задавать лимиты памяти и CPU для skill в production‑среде?
Рекомендуется явно указывать memory_limit_mb и cpu в конфигурации навыка, а перед запуском в production проверять лимиты cgroup через docker stats или cgroupfs. Задайте небольшие запасы (например, 10‑15 % выше требуемого) чтобы избежать OOM‑kill при пиковых нагрузках. Не забывайте про swap_limit_mb, если ваш контейнер может использовать swap. При отсутствии ограничения агент может «съесть» большую часть RAM сервера и привести к аварийному завершению других подов.
Почему каждый skill запускается в отдельном контейнере с non‑root пользователем и read‑only файловой системой?
Изоляция в контейнере гарантирует, что один skill не сможет повлиять на другие процессы и не получит повышенные привилегии, что критично с точки зрения безопасности. Пользователь non-root исключает возможность escalation, а read‑only файловая система предотвращает изменение кода или данных во время выполнения. Эти меры снижают риск эксплуатации уязвимостей и повышают стабильность всей системы.
Что делать, если агент «съел» большую часть RAM и привёл к OOM‑kill?
Сразу проверьте логи агента и системные метрики (docker stats, kubectl top pod) чтобы понять, какой skill превысил лимит. Уменьшите memory_limit_mb или увеличьте swap_limit_mb, а также убедитесь, что в cgroup заданы корректные ограничения. При необходимости пересмотрите resources в YAML/JSON‑конфиге и протестируйте изменения в staging‑окружении перед применением в production.
Как отладить медленную работу skill, связанную с высоким потреблением CPU?
Профилирование CPU с помощью perf или htop внутри контейнера поможет локализовать «узкое место». Установите более строгий cpu‑лимит и timeout, чтобы предотвратить зависание и дать возможность системе завершить задачу. При необходимости разбейте сложную задачу на несколько более простых skill, чтобы каждый из них использовал меньше ресурсов. На практике я видел случай, когда избыточные sleep‑команды в skill приводили к 100 % CPU, и их удаление ускорило выполнение в два раза.