Продвинутый

affaan-m/ECC: оптимизация производительности

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

Система agent‑harness от affaan-m: навыки, инстинкты, память, защита и исследовательский подход для Claude Code, Codex, Opencode, Cursor и др.

affaan-m/ECC: оптимизация производительности

Система agent‑harness от affaan-m: навыки, инстинкты, память, защита и исследовательский подход для Claude Code, Codex, Opencode, Cursor и др.

Архитектура и ключевые компоненты

Архитектура и ключевые компоненты

### Навыки агента

Навыки – это небольшие модули, которые определяют, какие действия может выполнить агент в ответ на запрос. Они реализуются как отдельные файлы‑конфиги и подключаются к harness через CLI.

Пример манифеста навыка (yaml‑файл skills/search.yml):

yaml
name: search
description: Поиск в файлах проекта с использованием ripgrep
required_capabilities:
  - file_access
  - shell_execution
parameters:
  query: "строка для поиска"
  max_results: 5

Команда загрузки навыка в текущий сеанс:

bash
harness load skill skills/search.yml

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

python
await agent.run("search", {"query": "docker-compose", "max_results": 3})

Важно: навыки, работающие с файловой системой, должны иметь ограниченные права доступа. Не делайте file_access: true без необходимости – это типичная ошибка, снижающая безопасность.

Ссылка на более детальное описание подхода к навыкам: affaan-m/ECC: оптимизация производительности агент‑ха́рнс.


### Инстинкты и память

Инстинкты – это автоматические триггеры, которые активируют определённый набор навыков без явного запроса пользователя. Они позволяют агенту «чувствовать» контекст и действовать проактивно.

Типичный инстинкт «auto‑doc» срабатывает, когда запрос содержит слова пример, как, показать. В respuesta генерируется запрос к навыку search и render_examples.

Пример конфигурации инстинкта (json‑файл instincts/auto_doc.json):

json
{
  "trigger_phrases": ["пример", "как", "показать"],
  "action": "search",
  "params": {
    "query": "${request}",
    "max_results": 2
  }
}

Память – хранит векторные представления (embeddings) предыдущих диалогов и результатов выполнения навыков. Позволяет агенту «помнить» контекст без пере‑запроса к внешним сервисам.

Конфигурация памяти в harness (yaml):

yaml
memory:
  provider: "sql"
  db_path: "./memory.db"
  vector_dim: 768
  cache_ttl_seconds: 86400

Команда инициализации базы памяти:

bash
harness memory init --db ./memory.db --dim 768

Пример добавления записи в память (через CLI):

bash
harness memory add --key "docker-compose-usage" --value '{"example": "docker-compose up -d", "timestamp": "2025-10-31T12:00:00Z"}'

Практический пример: после того, как агент один раз показал, как использовать docker-compose, он будет предлагать эту инструкцию автоматически, когда пользователь попросит «как запустить контейнеры». Это экономит время и уменьшает количество повторных запросов к поиску.

См. подробнее в статье Ponytail: Как заставить AI‑агент вести себя как ленивый старший разработчик, где описывается Principle of lazy senior.

Замечание: не храните в памяти чувствительные данные (токены, пароли). Используйте зашифрованные поля или отдельные хранилища с ограниченным доступом.


Все команды и конфиги приведены в виде примеров, их нужно адаптировать под конкретный проект.

Оптимизация производительности

Профилирование нагрузки

Прежде чем менять любые параметры, измеряйте. Без измерений вы рискуете ухудшить производительность, а не улучшить её.

Собирайте метрики CPU, памяти и I/O в режиме реального времени. Типичный набор команд выглядит так:

bash
# Запуск профилирования CPU с помощью perf
perf top --pid $(pidof agent-harness) -d 10
bash
# Захват трассировок системных вызовов (strace) для дальнейшего анализа
strace -p $(pidof agent-harness) -f -o /tmp/agent_harness.strace &
bash
# Мониторинг памяти и I/O через htop (внутри контейнера)
htop

Совет: если агент развёрнут в Docker, используйте docker exec для запуска htop внутри контейнера:

bash
docker exec -it affaan-m_agent_harness htop

Для более глубокой аналитики удобно подключить cAdvisor + Prometheus + Grafana. Метрики container_cpu_user_seconds_total, container_memory_working_set_bytes и container_io_read_bytes_total позволяют увидеть Bottlenecks на уровне контейнеров.

На практике я видел случай, когда увеличение vm.max_map_count без мониторинга привёл к быстрому исчерпанию памяти и падению процесса. Поэтому всегда держите под контролем free -m и vmstat 1.

Подробный подход к профилированию описан в статье Ponytail: оптимизация работы AI‑агентов.

Настройка параметров

После получения профиля можно корректировать параметры ядра, Docker‑демонa и ограничения ресурсов.

sysctl

Создайте файл /etc/sysctl.d/99-affaan-m.conf с рекомендациями:

conf
# Уменьшаем склонность к свопингу – экономия RAM
vm.swappiness = 10

# Увеличиваем количество наблюдаемых файлов (inotify)
fs.inotify.max_user_watches = 524288

# Увеличиваем максимальное количество соединений в очереди
net.core.somaxconn = 65535

# Ограничиваем максимальный размер памяти, которую процесс может выделять
kernel.max_mem_bytes = 1610612736

Применяйте изменения без перезагрузки:

bash
sysctl --system

Docker‑демон

В docker-compose.yml задавайте ограничения ресурсов для сервиса агента:

yaml
services:
  agent-harness:
    image: affaan-m/agent-harness:latest
    deploy:
      resources:
        limits:
          cpus: '4'          # не более 4 ядер
          memory: 8G         # максимум 8 ГБ RAM
        reservations:
          cpus: '2'          # гарантированные 2 ядра
          memory: 4G

Ограничения файлового дескриптора

Для процессов, открывающих множество файлов, установите ulimit в unit‑файле systemd:

ini
[Service]
LimitNOFILE=65536

После изменения перезапустите сервис:

bash
systemctl daemon-reload
systemctl restart agent-harness

На практике я видел случай, когда слишком низкое значение fs.file-max приводило к «Too many open files» и аварийному завершению агента. Установите ulimit -n 65536 и проверьте cat /proc/sys/fs/file-max.

Проверка после изменения

Перезапустите сервис и повторите профилирование, сравнив результаты с базой:

bash
perf top --pid $(pidof agent-harness) -d 10

Если наблюдается снижение времени выполнения критических операций (например, perf показывает уменьшение cpu-cycles), значит настройка эффективна.

Рекомендуется провести тест нагрузки (например, ab или wrk) перед и после изменений, чтобы убедиться в реальном приросте производительности.

Подробные рекомендации по настройке параметров находятся в статье affaan-m/ECC: Agent Harness Performance Optimization.


  • Запустить perf top и собрать профиль на 5‑10 минут нагрузки.
  • Сохранить вывод top/htop в лог для последующего сравнения.
  • Проверить sysctl -a | grep swappiness и при необходимости изменить.
  • Установить ulimit -n 65536 в systemd‑unit для сервиса.
  • В docker-compose.yml задать ограничения cpus и memory.
  • Перезапустить сервис и повторить профилирование.

Безопасность и контроль доступа

### Механизмы аутентификации

Для AI‑агентов, работающих в системе affaan‑m/ECC, аутентификация должна быть строгой и проверяемой. На практике я использую комбинацию трёх факторов:

  1. API‑ключ — короткая строка, генерируемая в веб‑консоли, хранится в переменной окружения и не передаётся в логах.
  2. JWT‑токен — подписанный токен с ограниченным сроком жизни (например, 15 минут). Позволяет проверять как подпись, так и-Claim‑ы (scopes, role).
  3. mTLS — клиентский сертификат, проверяемый на уровне TLS‑handshake; используется, когда агент подключается к привилегированному сервису.

Пример генерации JWT‑токена (Python)

python
import jwt, datetime, os

secret = os.getenv("JWT_SECRET")
payload = {
    "sub": "agent-harness",
    "role": "operator",
    "exp": datetime.datetime.utcnow() + datetime.timedelta(minutes=15),
    "scope": ["execute", "read"]
}
token = jwt.encode(payload, secret, algorithm="HS256")
print(token)

Защита от brute‑force

Fail2Ban — стандартный инструмент для блокировки IP после нескольких неудачных попыток входа. Пример конфигурации (/etc/fail2ban/jail.d/agent-auth.conf):

ini
[agent-auth]
enabled   = true
filter    = agent-auth
logpath   = /var/log/agent-auth.log
maxretry  = 5
bantime   = 3600

После изменения перезапустите сервис:

bash
sudo systemctl restart fail2ban

Важно: никогда не храните секретные ключи в открытом виде в репозиториях. Используйте vault‑провайдеры (HashiCorp Vault, AWS Secrets Manager) или at least .env‑файлы, исключённые из git.

Проверка TLS‑соединения

Перед тем как agent‑harness начнёт работать, рекомендуется убедиться, что TLS‑рукопожатие проходит успешно и сертификат валиден:

bash
curl -v --cert client.crt --key client.key https://api.agent-harness.local/health

Если сервер использует самоподписанный сертификат, добавьте --cacert ca.crt для проверки цепочки.


### Изоляция и sandboxing

Агент‑ха́рнс запускает пользовательский код, поэтому изоляция — обязательный уровень защиты. Ниже перечислены практики, проверенные на продакшене.

МераЧто делаетПример
User namespacesОтделяет UID/GID процесса внутри контейнера, не позволяет «выходить» за его пределы.docker run --userns-remap=default …
Read‑only rootfsЗапрещает изменение файловой системы контейнера, кроме томов, явно смонтированных как rw.docker run --read-only …
Seccomp‑profileОграничивает набор системных вызовов, которые может использовать процесс.docker run --security-opt seccomp=profile.json …
AppArmorПрофиль, задающий правила доступа к сетевым сокетам, файлам, устройствам.docker run --security-opt apparmor=profile.local …
FirejailДополнительный слой изоляции, работает на уровне namespaces и сеccomp.firejail --net=none --private=~/agent-data docker run …

Пример запуска контейнера с полной изоляцией

bash
docker run -d \
  --name agent-harness \
  --userns-remap=default \
  --read-only \
  --tmpfs /tmp:exec,size=64m \
  --security-opt no-new-privileges \
  --security-opt seccomp=seccomp.json \
  --security-opt apparmor=apparmor.local \
  -v /opt/agent-data:/data:rw \
  ghcr.io/affaan-m/ecc:latest

seccomp.json – минимальный профиль, разрешающий только системные вызовы, необходимые для работы Python‑интерпретатора и сетевого стека. Пример минимального профиля (JSON):

json
{
  "defaultAction": "SCMP_ACT_ERRNO",
  "syscalls": [
    {"name": "accept", "action": "SCMP_ACT_ALLOW"},
    {"name": "bind", "action": "SCMP_ACT_ALLOW"},
    {"name": "listen", "action": "SCMP_ACT_ALLOW"},
    {"name": "socket", "action": "SCMP_ACT_ALLOW"},
    {"name": "execve", "action": "SCMP_ACT_ALLOW"},
    {"name": "exit", "action": "SCMP_ACT_ALLOW"}
  ]
}

Контроль доступа к файловой системе

Если агент должен работать только с определённым набором файлов, монтируйте их как ro и используйте chroot‑подобный механизм:

bash
docker run -d \
  --name agent-harness \
  --read-only \
  -v /srv/agent/conf:/etc/agent:ro \
  -v /srv/agent/data:/data:rw \
  ghcr.io/affaan-m/ecc:latest

Не делайте так: запускайте контейнер с --privileged или без ограничения seccomp — это открывает путь к полной компрометации системы.

Логи и аудит

Для контроля доступа рекомендуется включить аудит Linux (auditd) и отправлять события в центральный SIEM (например, Wazuh). Пример правила для отслеживания попыток исполнения execve внутри контейнера:

bash
auditctl -a exit,always -F arch=b64 -S execve -k container_exec

Эти записи можно потом проанализировать в Wazuh или Security Onion, чтобы увидеть, какие процессы пытались запускать неавторизованные бинарники.


Сводка

  • Аутентификация — многофакторная (API‑ключ + JWT + mTLS), регулярная ротация секретов, защита от brute‑force через Fail2Ban.
  • Изоляция — user namespaces, read‑only rootfs, seccomp, AppArmor, Firejail; аудит через auditd и SIEM.

Следуя этим практикам, вы снижаете риск компрометации как самого агента, так и инфраструктуры, в которой он operates. Подробнее о конфигурации и проверке см. в affaan-m/ECC: Agent Harness Performance Optimization и Ponytail: Как заставить AI‑агент вести себя как ленивый старший разработчик.

Разработка и исследования

Исследовательский процесс

Для оценки нагрузки на AI‑агентов использую микробенчмарки и профайлеры, которые позволяют измерять реальное время отклика и потребление памяти.
На практике я запускаю набор запросов через hyperfine и сохраняю результаты в CSV, после чего анализирую их в gnuplot:

bash
hyperfine --warmup 3 --min-runs 5 --export csv results.csv \
  "curl -s -X POST http://localhost:8080/api/query -d '{\"prompt\":\"test\"}'"

Для измерения потребления памяти применяю psutil в небольшом скрипте‑обёртке, который запускает агент в контейнере с ограниченными ресурсами:

python
import subprocess, psutil, time

proc = subprocess.Popen(
    ["docker", "run", "--rm", "-v", "./agent:/app", "--cpus", "2", "--memory", "2g",
     "affaan-m/ecc:latest", "run", "--task", "benchmark"],
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
)

ps = psutil.Pid(proc.pid)
start = time.time()
while proc.poll() is None:
    mem = ps.memory_info().rss / (1024 * 1024)  # MB
    print(f"[{time.strftime('%H:%M:%S')}] Memory: {mem:.1f} MB")
    time.sleep(1)

proc.wait()
print(f"Exit code: {proc.returncode}")

Что я проверяю

  • latency – среднее время ответа; если превышает 200 ms, рекомендуется уменьшить batch‑size.
  • cpu‑util – если процесс потребляет более 70 % ядра, стоит включить cgroups‑лимиты.
  • memory leak – рост RSS выше 10 % за 10 минут указывает на утечку; в таком случае использую read‑only filesystem и seccomp‑профиль.

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

Для сравнения с другими подходами смотрю материал Ponytail: оптимизация работы AI‑агентов, где автор показывает, как «ленивый» агент может снизить нагрузку за счёт задержек между запросами. Принцип прост: добавить небольшую паузу (0.5‑1 s) после каждой итерации – это уменьшает пиковую нагрузку на GPU без заметного падения точности.


Интеграция с CI/CD

В CI я включаю этапы build, test и benchmark в один пайплайн, чтобы проверять регрессии сразу после коммита. Ниже пример конфигурации для GitHub Actions (файл .github/workflows/ci.yml):

yaml
name: CI

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Run unit tests
        run: pytest -q
      - name: Build Docker image
        run: |
          docker build -t affaan-m/ecc:ci-${{ github.sha }} .
      - name: Run performance benchmark
        run: |
          docker run --rm affaan-m/ecc:ci-${{ github.sha }} \
            ./run_benchmark.sh --output /tmp/bench.json
          cat /tmp/bench.json

Ключевые моменты

  • кеширование образов с помощью actions/cache экономит время сборки.
  • benchmark‑script (run_benchmark.sh) формирует JSON‑отчёт, который затем отправляется в Artifacts для последующего анализа.

Если в пайплайне требуется проверка security‑scan, я добавляю шаг с trivy:

yaml
      - name: Scan image for vulnerabilities
        uses: aquasecurity/trivy-action@0.28.0
        with:
          image-ref: affaan-m/ecc:ci-${{ github.sha }}
          format: table
          severity: HIGH,CRITICAL

Не делайте так – не храните секреты в переменных окружения без шифрования, а также не включайте latest тег в продакшн‑деплой; всегда используйте фиксированный SHA‑тег.

Для более продвинутой интеграции с GitLab CI можно взять за основу пример из affaan-m/ECC: Agent Harness Performance Optimization, где показан matrix‑подход к тестированию на разных версиях Docker‑Compose и разных конфигурациях seccomp‑proфилей.

рекомендуется добавить в каждый пайплайн шаг, который проверяет, что полученные метрики не превышают заранее заданные пороги (например, latency ≤ 150 ms, memory ≤ 1 GB). При превышении порога пайплайн должен завершиться с кодом ошибки, чтобы сразу блокировать merge.

категорически не рекомендуется игнорировать падения тестов из‑за сетевых задержек – в CI используйте локальный прокси‑контейнер с предсказуемой задержкой, чтобы изолировать сетевой шум.

Таким образом, исследовательский процесс и CI/CD становятся взаимосвязанными звеньями: результаты профайлинга попадают в кодовую базу, а CI‑проверки гарантируют, что любые изменения не ухудшат уже отполированную производительность.

Часто задаваемые вопросы

Как правильно ограничить права доступа у загружаемых навыков?

Навыки, взаимодействующие с файловой системой, должны иметь минимальный набор required_capabilities. Указывайте file_access: true только тогда, когда это действительно необходимо, и проверяйте, какие файлы действительно читаются или модифицируются. Пример: вместо file_access: true используйте конкретные пути в параметрах навыка. Это снижает риск эксплуатации уязвимостей и улучшает общую безопасность системы.

Что делать, если агент начинает работать медленно после загрузки нескольких навыков?

Сначала проверьте, не активируются ли инстинкты, которые запускают лишние поиски или запросы к файловой системе. Ограничьте количество одновременно загруженных навыков и используйте harness unload для отключения неиспользуемых модулей. Кроме того, мониторьте нагрузку через harness stats и при необходимости оптимизируйте параметры max_results и query в конфигурации навыка.

Как эффективно использовать инстинкты для автоматического вызова навыков?

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

Как профилировать и оптимизировать потребление памяти агента?

Используйте встроенный механизм harness memory-profile, который показывает распределение памяти между навыками, инстинктами и основной логикой. Регулярно проверяйте профиль после добавления новых модулей и удаляйте те, которые не используют память в течение длительного времени. При необходимости настройте max_results и ограничьте кеширование данных, чтобы уменьшить объём используемой памяти.

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

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