Продвинутый

affaan-m/ECC: Agent Harness Performance Optimization

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

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

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:

bash
curl -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:

yaml
opcode:
  endpoint: "https://api.opencode.io/v1/agent"
  auth_token: "${ECC_OPCODE_TOKEN}"
  sandbox: true   # включить изоляцию контейнера

Запрет: не включайте sandbox: false в production‑средах – это открывает доступ к полной системе без ограничений.

Cursor

Cursor интегрируется через WebSocket‑соединение. Минимальный пример на Python:

python
import 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 с фильтром по сетевым пакетам:

bash
strace -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 – они показывают распределение процессов по страницам и суммарный объём.

bash
pmap -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 с фильтром по системным вызовам – один из самых быстрых способов понять, где «зависает» процесс.

bash
strace -c -p $(pidof agent_harness)  # подсчёт времени системных вызовов

Если процесс использует Docker, удобно смотреть ресурсы контейнера через docker stats и при необходимости ограничить их:

bash
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}" agent_harness
docker update --cpus="2" --memory="4g" agent_harness

Для анализа сетевых задержек применяйте nethogs и iftop:

bash
nethogs eth0    # per‑process network bandwidth
iftop -i eth0   # real‑time bandwidth per IP/port

gdb – классический отладчик, который позволяет приостановить процесс и исследовать стек.

bash
gdb -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.

bash
journalctl -u agent_harness -p err -f

Системный аудит через auditd помогает отследить попытки доступа к конфиденциальным файлам:

bash
auditctl -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‑запросы будут медленнее.

Практические приёмы

  1. Задать лимит токенов – большинство фреймворков позволяют указать максимальный размер контекста при запуске.

    bash
    # пример для Claude‑Code
    claude‑code --context-limit 8192
    
    bash
    # пример для собственного скрипта
    export CONTEXT_MAX=8192
    
  2. 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‑провайдер. Однако кэш тоже требует контроля, иначе он может «заполниться» и съесть дисковую память.

Практические приёмы

  1. Локальный файловый кэш – храните результат запросов в директории ~/.cache/agent‑ecc. Ограничьте размер кеша с помощью cachetool или docker‑prune.

    bash
    # пример настройки кеша в конфиге (YAML)
    cache:
      dir: /home/greyhat/.cache/agent-ecc
      max_size_mb: 500
      ttl_seconds: 86400   # 24 часа
    
  2. Redis‑кеш – для распределённых сред удобно использовать Redis. Он поддерживает TTL и автоматическое удаление устаревших записей.

    bash
    # запуск Redis в Docker
    docker run -d --name redis-cache -p 6379:6379 \
      -v redis-data:/data redis:7-alpine
    
    yaml
    # пример подключения в конфиге
    cache:
      type: redis
      host: localhost
      port: 6379
      db: 0
      ttl: 43200   # 12 часов
    
  3. Disk‑cache библиотеки – в Python‑окружении diskcache автоматически сохраняет результаты в файловый кеш и управляет размером.

    python
    import 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]
    
  4. Валидация данных – перед тем как кэшировать ответ, проверьте, что в нём нет конфиденциальных данных. Автоматически сканируйте вывод через gpg --clearsign или truffleHog.

    bash
    # проверка на наличие токенов в выводе
    echo "$response" | truffleHog -a
    
  5. Мониторинг – регулярно проверяйте, как растёт размер кеша и какие запросы чаще всего попадают в кеш.

    bash
    du -sh ~/.cache/agent-ecc
    

Связь с другими материалами


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

  • Оценить текущий объём контекста и установить лимит (например, 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, проверяя целостность файла перед запуском. Это позволяет избежать потери прогресса при перезапусках или сбоях.

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

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