affaan-m/ECC: оптимизация производительности
Система agent‑harness от affaan-m: навыки, инстинкты, память, защита и исследовательский подход для Claude Code, Codex, Opencode, Cursor и др.
Архитектура и ключевые компоненты
Архитектура и ключевые компоненты
### Навыки агента
Навыки – это небольшие модули, которые определяют, какие действия может выполнить агент в ответ на запрос. Они реализуются как отдельные файлы‑конфиги и подключаются к harness через CLI.
Пример манифеста навыка (yaml‑файл skills/search.yml):
yamlname: search
description: Поиск в файлах проекта с использованием ripgrep
required_capabilities:
- file_access
- shell_execution
parameters:
query: "строка для поиска"
max_results: 5
Команда загрузки навыка в текущий сеанс:
bashharness load skill skills/search.yml
После загрузки навык становится доступен в контексте агента, и его можно вызвать так:
pythonawait 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):
yamlmemory:
provider: "sql"
db_path: "./memory.db"
vector_dim: 768
cache_ttl_seconds: 86400
Команда инициализации базы памяти:
bashharness memory init --db ./memory.db --dim 768
Пример добавления записи в память (через CLI):
bashharness 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внутри контейнера:
bashdocker 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
Применяйте изменения без перезагрузки:
bashsysctl --system
Docker‑демон
В docker-compose.yml задавайте ограничения ресурсов для сервиса агента:
yamlservices:
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
После изменения перезапустите сервис:
bashsystemctl daemon-reload systemctl restart agent-harness
На практике я видел случай, когда слишком низкое значение
fs.file-maxприводило к «Too many open files» и аварийному завершению агента. Установитеulimit -n 65536и проверьтеcat /proc/sys/fs/file-max.
Проверка после изменения
Перезапустите сервис и повторите профилирование, сравнив результаты с базой:
bashperf 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, аутентификация должна быть строгой и проверяемой. На практике я использую комбинацию трёх факторов:
- API‑ключ — короткая строка, генерируемая в веб‑консоли, хранится в переменной окружения и не передаётся в логах.
- JWT‑токен — подписанный токен с ограниченным сроком жизни (например, 15 минут). Позволяет проверять как подпись, так и-Claim‑ы (scopes, role).
- mTLS — клиентский сертификат, проверяемый на уровне TLS‑handshake; используется, когда агент подключается к привилегированному сервису.
Пример генерации JWT‑токена (Python)
pythonimport 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
После изменения перезапустите сервис:
bashsudo systemctl restart fail2ban
Важно: никогда не храните секретные ключи в открытом виде в репозиториях. Используйте vault‑провайдеры (HashiCorp Vault, AWS Secrets Manager) или at least
.env‑файлы, исключённые из git.
Проверка TLS‑соединения
Перед тем как agent‑harness начнёт работать, рекомендуется убедиться, что TLS‑рукопожатие проходит успешно и сертификат валиден:
bashcurl -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 … |
Пример запуска контейнера с полной изоляцией
bashdocker 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‑подобный механизм:
bashdocker 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 внутри контейнера:
bashauditctl -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:
bashhyperfine --warmup 3 --min-runs 5 --export csv results.csv \
"curl -s -X POST http://localhost:8080/api/query -d '{\"prompt\":\"test\"}'"
Для измерения потребления памяти применяю psutil в небольшом скрипте‑обёртке, который запускает агент в контейнере с ограниченными ресурсами:
pythonimport 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):
yamlname: 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 и ограничьте кеширование данных, чтобы уменьшить объём используемой памяти.