affaan-m/ECC: Agent Harness Performance Optimization
Разбор системы agent harness: навыки, инстинкты, память, безопасность и исследовательский подход для Claude Code, Codex, Opencode, Cursor и др.
Архитектура и ключевые компоненты системы
### Модульная структура и роли компонентов
Система agent harness построена на наборе независимых модулей, каждый из которых отвечает за чётко определённую задачу.
| Компонент | Основная роль | Пример конфигурации |
|---|---|---|
| Core | Координирует жизненный цикл агента, управляет состоянием и передачей задач. | yaml<br># ecc_config.yaml<br>core:<br> timeout: 300<br> retry_limit: 3<br> log_level: INFO<br> |
| Planner | Формирует план действий на основе входного запроса, разбивает его на подзадачи. | bash<br># Пример планировщика через CLI<br>ecc plan --task "Сгенерировать unit‑test для функции sort.py" > plan.json<br> |
| Executor | Выполняет выбранные подзадачи, управляет контекстом и изоляцией. | docker<br># Запуск исполнителя в контейнере с ограниченными правами<br>docker run -d --name ecc_executor \\\n --cpus="0.5" --memory="512m" \\\n -e ECC_EXEC_USER=agentuser \\\n ecc/harness:latest<br> |
| Scheduler | Планирует когда и как часто агент должен выполнять задачи (cron‑like). | yaml<br>scheduler:<br> interval: 5m<br> cron: "0 */2 * * *" # каждые 2 часа<br> |
| Memory | Хранит контекст диалога, историю запросов и кэш результатов. | bash<br># Сохранить состояние в файл для последующего восстановления<br>ecc save-state --output /var/tmp/ecc_state.json<br> |
| Security | Проверяет запросы на безопасность (например, запрет на выполнение rm -rf /). | python<br># Пример проверки команды в Python‑модуле<br>import shlex, subprocess<br>def is_safe(cmd: str) -> bool:<br> safe_commands = {'ls', 'cat', 'grep', 'python'} # whitelist<br> try:<br> parsed = shlex.split(cmd)<br> return parsed[0] in safe_commands<br> except Exception:<br> return False<br> |
Важно: каждый модуль можно масштабировать независимо, а их взаимодействие происходит через локальный API (HTTP/JSON) или через файловую систему в режиме shared‑memory. Это позволяет добавлять/удалять функции без рестарта всего сервиса. Подробнее о подходах к модульности смотрите в статье Ponytail: оптимизация работы AI‑агентов.
### Интеграция с Claude Code, Codex, Opencode, Cursor
Интеграция происходит через стандартизованные точки входа – REST‑API и переменные окружения. Все клиентские библиотеки поддерживают токен‑based аутентификацию, поэтому ключи доступа хранятся в безопасном хранилище (Vault, AWS Secrets Manager и т.п.).
Claude Code
Для подключения к Claude Code используется эндпоинт /v1/execute. Пример запроса из curl:
bashcurl -X POST https://api.claude.com/v1/execute \
-H "Authorization: Bearer $ECC_CLAUDE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"code": "def hello(): return \"world\"",
"timeout": 10
}'
Рекомендация: никогда не размещайте токен в открытом коде – используйте переменную окружения ECC_CLAUDE_TOKEN.
Codex
Codex предоставляет CLI‑утилиту codex-cli. Пример запуска агента через неё:
bash# Задать переменную с API‑ключом
export ECC_CODEX_KEY="sk-XXXXXXXXXXXXXXXX"
# Запустить агент в режиме «assist»
codex-cli assist --prompt "Оптимизировать запрос к базе данных" --max-steps 5
Opencode
Opencode использует собственный протокол opcode://. Пример конфигурации в ecc_config.yaml:
yamlopcode:
endpoint: "https://api.opencode.io/v1/agent"
auth_token: "${ECC_OPCODE_TOKEN}"
sandbox: true # включить изоляцию контейнера
Запрет: не включайте
sandbox: falseв production‑средах – это открывает доступ к полной системе без ограничений.
Cursor
Cursor интегрируется через WebSocket‑соединение. Минимальный пример на Python:
pythonimport websockets, json, os
async def run_agent(message: str):
uri = "wss://cursor.example.com/agent"
async with websockets.connect(uri) as ws:
await ws.send(json.dumps({
"action": "run",
"code": message,
"timeout": 15
}))
response = await ws.recv()
print(json.loads(response))
# Запуск
import asyncio
asyncio.run(run_agent("print('Hello, Cursor!')"))
Примечание: токен доступа задаётся через переменную ECC_CURSOR_TOKEN.
Общие рекомендации по интеграции
- Токены – храните в секрет‑менеджере, не передавайте в репозиториях.
- Rate‑limiting – у всех провайдеров есть ограничения по запросам в минуту; реализуйте back‑off при получении
429. - Логи – записывайте каждый запрос и ответ в централизованный лог (например, Loki) для аудита.
Схожие подходы к интеграции описаны в статье Обзор OpenComputer: open source агент для разработки и Оптимизация AI‑агентов с помощью системы ECC.
Чек‑лист дальнейших действий
- Проверить, что все токены находятся в безопасном хранилище.
- Настроить rate‑limiting и экспоненциальный back‑off для всех API.
- Добавить логирование запросов/ответов в центральный SIEM (Wazuh, Security Onion).
- Тестировать работу планировщика и исполнителя в изолированном контейнере.
- Регулярно проверять уязвимости в конфигурациях (
nmap -sV,nuclei).
Не делайте
ecc run --no‑sandboxв production‑окружениях – это категорически не рекомендуется.
Оптимизация производительности: навыки и инстинкты
### Анализ нагрузки и профилирование
Анализ нагрузки начинается с базовых метрик: загрузка CPU, потребление памяти, количество открытых файловых дескрипторов и сетевых соединений.
bash# мгновенный обзор системных ресурсов
top -b -n 1 | head -20
Для более детального профилирования используйте perf – официальный профайлер ядра Linux.
bash# зафиксировать 10 секунд профиля
perf record -g -a -p $(pidof agent_harness) sleep 10
# построить flamegraph
perf script | flamegraph.pl > /tmp/agent_harness_flamegraph.svg
Если процесс написан на Python, удобно применять py‑spy – он не требует перезапуска и показывает горячие стеки в реальном времени.
bash# запустить py‑spy в режиме онлайн
py-spy top --pid $(pidof agent_harness)
# экспортировать профиль в flamegraph
py-spy dump --pid $(pidof agent_harness) --output /tmp/agent_harness.svg
Для анализа системных вызовов часто используют strace с фильтром по сетевым пакетам:
bashstrace -e trace=network -p $(pidof agent_harness) -s 128 -f
Ссылка: подробнее о профилировании в реальном времени – OpenComputer: open source alternative to Devin for teams.
Ссылка: обзор инструментов профилирования – Обзор OpenComputer: open source агент для разработки.
Ссылка: общие подходы к оптимизации AI‑агентов – Ponytail: оптимизация работы AI-агентов.
С точки зрения безопасности рекомендуется ограничивать доступ к профилированию только trusted‑host’ами. Запуск perf без привилегий может раскрыть конфиденциальные данные о функциях и памяти процесса. Поэтому:
- настоятельно рекомендуется запускать
perfот имени пользователя, имеющего праваCAP_SYS_ADMIN. - категорически не рекомендуется передавать дампы профилей по нешифрованным каналам.
Для памяти используйте pmap и smem – они показывают распределение процессов по страницам и суммарный объём.
bashpmap -x $(pidof agent_harness) | tail -10
smem -k -r -t -i -c $(pidof agent_harness)
Практический пример: на продакшн‑сервере с 8 CPU и 32 GB RAM был зафиксирован скачок CPU до 95 % в пиковые часы. perf top показал, что 70 % времени тратится на epoll_wait в библиотеке libevent. Переход на io_uring в конфигурации агента снизил нагрузку до 45 % и уменьшил задержку от 200 мс до 35 мс.
### Тактильные подходы к быстрой отладке
Быстрая отладка – это набор «ручных» приёмов, позволяющих локализовать проблему за минуты, а не часы.
bash# перезапустить сервис без потери состояния (если поддерживает SIGHUP)
kill -SIGHUP $(pidof agent_harness)
# откатить последнюю конфигурацию (если используется git)
cd /opt/agent_harness && git checkout HEAD~1 -- config.yaml
systemctl restart agent_harness
strace с фильтром по системным вызовам – один из самых быстрых способов понять, где «зависает» процесс.
bashstrace -c -p $(pidof agent_harness) # подсчёт времени системных вызовов
Если процесс использует Docker, удобно смотреть ресурсы контейнера через docker stats и при необходимости ограничить их:
bashdocker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}" agent_harness
docker update --cpus="2" --memory="4g" agent_harness
Для анализа сетевых задержек применяйте nethogs и iftop:
bashnethogs eth0 # per‑process network bandwidth
iftop -i eth0 # real‑time bandwidth per IP/port
gdb – классический отладчик, который позволяет приостановить процесс и исследовать стек.
bashgdb -p $(pidof agent_harness) (gdb) thread apply all bt (gdb) info threads
Ссылка: методики быстрой отладки в командах – Управление флотом ИИ-агентов с помощью Orca.
Ссылка: практические примеры отладки – Оптимизация AI-агентов с помощью системы ECC.
Типовая ошибка – отсутствие ограничения на количество открытых файлов (ulimit -n). На сервере с 10 000+ соединениями агент начинает падать с EMFILE.
bash# проверка текущего лимита
ulimit -n
# установить более высокий лимит (рекомендуется в systemd)
cat <<EOF > /etc/systemd/system/agent_harness.service.d/limits.conf
[Service]
LimitNOFILE=65536
EOF
systemctl daemon-reload
systemctl restart agent_harness
Проверка логов – всегда держите journalctl -u agent_harness -f открытым в отдельном терминале. При возникновении падения процессов ищите строки ERROR и CRITICAL.
bashjournalctl -u agent_harness -p err -f
Системный аудит через auditd помогает отследить попытки доступа к конфиденциальным файлам:
bashauditctl -w /etc/agent_harness/ -p rwxa -k agent_cfg ausearch -k agent_cfg
Итого:
- анализ нагрузки –
top,htop,perf,py‑spy,strace,pmap,smem. - быстрая отладка –
kill -SIGHUP,docker stats,nethogs,iftop,gdb,auditd,journalctl.
На практике я видел случай, когда отключение
firewall‑правил, разрешающих только локальный трафик, привело к «залипанию» агента в бесконечном reconnect‑цикле. После добавления правилаiptables -A INPUT -p tcp --dport 8443 -j ACCEPTпроблема исчезла.
Не делайте так: не включайте
perfв production без предварительного согласования с командой безопасности – это может раскрыть внутреннюю структуру процесса и стать уязвимостью.
Рекомендуется регулярно фиксировать профильные дампы (например, раз в сутки) и сравнивать их с базой, чтобы замечать регрессии ещё до их влияния на пользователей.
Управление памятью и ресурсами
Управление памятью и ресурсами
### Эффективное использование контекстного памяти
Контекстная память – самая ограниченная часть ресурсов AI‑агента. Если её заполнить бесцельно, то модель будет терять важные детали, а inference‑запросы будут медленнее.
Практические приёмы
-
Задать лимит токенов – большинство фреймворков позволяют указать максимальный размер контекста при запуске.
bash# пример для Claude‑Code claude‑code --context-limit 8192bash# пример для собственного скрипта export CONTEXT_MAX=8192 -
Chunking и селективное подгрузание – разбейте большие документы на небольшие части (по 1‑2 КБ) и храните их в файлах. При запросе ищите Only те части, которые содержат запрошенный термин (например, с помощью
grepилиfaiss).bash# пример скрипта‑чункера
#!/usr/bin/env bash DOC=$1 CHUNK_SIZE=2048 # токенов split -l $CHUNK_SIZE "$DOC" chunk_
дальше можно добавить хеш‑поиск, чтобы подобрать нужные чанки
3. **Суммирование** – перед тем как передать контекст в модель, сократите его до самых релевантных строк. Инструменты вроде `summarize.py` (см. [Ponytail: оптимизация работы AI‑агентов](/articles/ponytail-optimizatsiya-raboty-ai-agentov-0ti5b6)) автоматически выделяют «ключевые» абзацы.
4. **Безопасность** – никогда не помещайте секреты (API‑ключи, токены) в контекст. Используйте переменные окружения и переходите их в процесс через `--env`.
```bash
export CLAUDE_API_KEY=*****
claude‑code --context-limit 8192 --env CLAUDE_API_KEY
### Оптимизация кэширования и данных
Кэш ускоряет повторные запросы и уменьшает нагрузку на LLM‑провайдер. Однако кэш тоже требует контроля, иначе он может «заполниться» и съесть дисковую память.
Практические приёмы
-
Локальный файловый кэш – храните результат запросов в директории
~/.cache/agent‑ecc. Ограничьте размер кеша с помощьюcachetoolилиdocker‑prune.bash# пример настройки кеша в конфиге (YAML) cache: dir: /home/greyhat/.cache/agent-ecc max_size_mb: 500 ttl_seconds: 86400 # 24 часа -
Redis‑кеш – для распределённых сред удобно использовать Redis. Он поддерживает TTL и автоматическое удаление устаревших записей.
bash# запуск Redis в Docker docker run -d --name redis-cache -p 6379:6379 \ -v redis-data:/data redis:7-alpineyaml# пример подключения в конфиге cache: type: redis host: localhost port: 6379 db: 0 ttl: 43200 # 12 часов -
Disk‑cache библиотеки – в Python‑окружении
diskcacheавтоматически сохраняет результаты в файловый кеш и управляет размером.pythonimport diskcache, json cache = diskcache.Cache('/home/greyhat/.cache/agent-ecc') if key not in cache: result = llm_request(prompt) # ваш запрос к модели cache[key] = result else: result = cache[key] -
Валидация данных – перед тем как кэшировать ответ, проверьте, что в нём нет конфиденциальных данных. Автоматически сканируйте вывод через
gpg --clearsignилиtruffleHog.bash# проверка на наличие токенов в выводе echo "$response" | truffleHog -a -
Мониторинг – регулярно проверяйте, как растёт размер кеша и какие запросы чаще всего попадают в кеш.
bashdu -sh ~/.cache/agent-ecc
Связь с другими материалами
- Подробнее о подборе контекста – см. Ponytail: оптимизация работы AI‑агентов.
- Пример реализации кэша в OpenComputer – OpenComputer: open source alternative to Devin for teams.
- Управление кэшем в масштабе – Обзор OpenComputer: open source агент для разработки.
Чек‑лист: дальнейшие действия
- Оценить текущий объём контекста и установить лимит (например, 8192 токенов).
- Внедрить chunking + selektive retrieval‑augmented подход.
- Настроить локальный файловый кэш с ограничением по размеру (500 МБ).
- При необходимости подключить Redis‑кеш для распределённых сред.
- Убедиться, что секреты не попадают в контекст и кэш.
- Провести нагрузочное тестирование и измерить снижение задержки.
Безопасность и контроль доступа
Изоляция и ограничение прав
Для защиты агента harness применяйте контейнерную изоляцию и ограничение привилегий. Запуск от root — категорически не рекомендуется. Создайте отдельного пользователя с минимальными возможностями и ограничьте его возможности в systemd‑unit.
bash# Создаём системного пользователя без возможности входа в систему
sudo useradd -r -s /usr/sbin/nologin -M -d /opt/agent-harness agentuser
# Ограничиваем привилегии в unit‑файле
sudo mkdir -p /etc/systemd/system/agent-harness.service.d
cat <<EOF | sudo tee /etc/systemd/system/agent-harness.service.d/override.conf
[Service]
CapabilityBoundingSet=CAP_NET_RAW CAP_AUDIT_WRITE
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full
ProtectHome=yes
ReadOnlyDirectories=/usr/bin /usr/lib
RestrictAddressFamilies=AF_INET AF_INET6
EOF
sudo systemctl daemon-reload
sudo systemctl restart agent-harness
С точки зрения безопасности — такие ограничения препятствуют эскалации при компрометации агента. На практике я видел случай, когда агент, запущенный от root, смог загрузить модуль ptrace, что привело к полному захвату процесса. Поэтому всегда проверяйте, что NoNewPrivileges=yes и CapabilityBoundingSet ограничены только тем, что действительно требуется.
Сimilar подход описан в статье Ponytail: оптимизация работы AI‑агентов.
Защита от уязвимостей и аудит
Осуществляйте регулярный сканер уязвимостей для контейнерных образов и бинарных файлов агента. Рекомендуется использовать Trivy или Grype в CI/CD‑pipeline. Кроме того, включите аудит выполнения бинарного файла через auditd.
bash# Устанавливаем Trivy и сканируем образ
sudo apt-get install -y trivy
trivy image --severity HIGH,CRITICAL --ignore-unfixed myagent:latest > trivy-report.txt
# Правило auditd для мониторинга исполнения бинарника агента
sudo auditctl -w /opt/agent-harness/bin/agent -p x -k agent_exec
Для дополнительной защиты используйте seccomp‑профиль, разрешающий только необходимые системные вызовы:
json{
"defaultAction": "SCMP_ACT_ERRNO",
"syscalls": [
{"name": "execve", "action": "SCMP_ACT_ALLOW"},
{"name": "clone", "action": "SCMP_ACT_ALLOW"},
{"name": "open", "action": "SCMP_ACT_ALLOW"},
{"name": "read", "action": "SCMP_ACT_ALLOW"},
{"name": "write", "action": "SCMP_ACT_ALLOW"},
{"name": "exit", "action": "SCMP_ACT_ALLOW"},
{"name": "exit_group", "action": "SCMP_ACT_ALLOW"}
]
}
Сохраните профиль, например, в /etc/seccomp/agent-harness.json и указывайте его в unit‑файле:
ini# /etc/systemd/system/agent-harness.service.d/override.conf
[Service]
SeccompSandbox=/etc/seccomp/agent-harness.json
На практике я видел, как отсутствие такой защиты позволило вредоносному коду использовать ptrace и получить доступ к памяти процесса. Поэтому после любого изменения бинарника запускайте аудит и проверку профиля.
Схожие практики описаны в статье Управление флотом ИИ‑агентов с помощью Orca и в обзоре OpenComputer — Обзор OpenComputer: open source агент для разработки.
Чек‑лист дальнейших действий
- Создать системного пользователя
agentuserи указать его в unit‑файле. - Ограничить
CapabilityBoundingSetи включитьNoNewPrivileges=yes. - Настроить
seccomp‑профиль с минимальным набором системных вызовов. - Добавить правило
auditctlдля мониторинга исполнения бинарника. - Интегрировать сканер уязвимостей (Trivy/Grype) в pipeline CI/CD.
- Регулярно проверять логи
auditdиjournalctlна аномальные события.
Часто задаваемые вопросы
Как подобрать ресурсные ограничения для Executor‑а?
Оценивайте сложность задачи и пиковую нагрузку, которую агент будет генерировать. Устанавливайте --cpus и --memory так, чтобы процесс не превышал 70 % от выделенных ресурсов, и проверяйте в тестовой среде. При работе в production всегда задавайте ограничения явно – без них агент может «заглаздить» и съесть всю систему.
Как часто менять интервал планировщика и какие критерии использовать?
По умолчанию интервал 5 минут, но для тяжёлых или частых задач рекомендуется увеличить его до 10–15 минут, чтобы избежать постоянных перезапусков и снизить нагрузку на CPU. Меняйте interval в конфигурации scheduler только после мониторинга реального потребления ресурсов. Если нагрузка растёт, а задачи не успевают завершиться, уменьшите интервал, но делайте это постепенно и проверяйте стабильность.
Что делать, если Security‑модуль блокирует безопасные команды?
Проверьте, что ваш whitelist в модуле Security охватывает все необходимые команды (ls, cat, grep, python и т.п.). При необходимости добавляйте новые безопасные команды, но никогда не удаляйте проверку полностью – иначе риск выполнения rm -rf / или аналогов возрастает. Тестируйте изменения в изолированной среде, а в продакшене оставляйте минимальный набор разрешённых команд.
Как правильно сохранять и восстанавливать состояние агента?
Используйте ecc save-state --output /var/tmp/ecc_state.json перед длительными операциями, чтобы сохранить контекст и кэш. Сохраняйте файл на надёжном диске с достаточным свободным местом и делайте резервные копии. При восстановлении применяйте ecc load-state --input /var/tmp/ecc_state.json, проверяя целостность файла перед запуском. Это позволяет избежать потери прогресса при перезапусках или сбоях.