Продвинутый

affaan-m/ECC: Agent Harness Performance Optimization

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

The agent harness performance optimization system for Claude Code, Codex, Opencode, Cursor. Skills, instincts, memory, security, research‑first development.

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) в виде отдельных шагов, каждый из которых изолирован в контейнере с ограниченными ресурсами. Это позволяет гарантировать безопасность и стабильность выполнения даже при работе с потенциально тяжёлыми задачами.

yaml
skill:
  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:
bash
orcacli skill run "Deploy service"

При отсутствии ограничения памяти типичная ошибка выглядит так: агент «съел» 80 % RAM сервера и привёл к OOM‑kill других подов. Поэтому рекомендуется явно указывать memory и cpu в конфиге навыка, а перед запуском в production проверить лимиты cgroup.

Для управления несколькими агентами см. Управление fleet-агентами разработки с Orca.

Memory Management Strategies

Харнесс использует несколько стратегий управления памятью, которые можно настроить per‑agent:

  1. Лимиты памяти на уровне контейнера – задаются при запуске Docker‑контейнера (--memory, --memory-swap).
  2. Конфигурационный файл агента – в 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.

Пример запуска агента с заданными лимитами:

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

bash
ecc run --instinct http_client https://api.example.com/query

Если инстинкт не срабатывает, хард‑кейс переходит к следующему в списке. Поэтому важно, чтобы условия были точными и приоритеты отражали реальную нагрузку.

Важно: перед изменением инстинктов всегда проверяйте текущие логи, иначе можно получить «бесконечный цикл» запросов.
Проверка логов в Orca показывает, как быстро находить падения инстинктов в fleet‑агентах.


### Resource Allocation and Profiling

Оптимизация производительности требует корректного распределения ресурсов (CPU, память, I/O) и систематического профилирования. Ниже – проверенные подходы, используемые в продакшене.

1. Ограничение ресурсов через cgroup

При запуске агента в Docker удобно задавать лимиты:

bash
docker 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). Пример команды:

bash
orca 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‑контейнера

bash
docker 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)

bash
mkdir -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, и их удаление ускорило выполнение в два раза.

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

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