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 Performance Principles
Core Architecture and Performance Principles
Modular Skill Execution Model
В системе affaan-m/ECC каждый навык (skill) реализован как самостоятельный модуль, который может быть подключён или отключён без изменения остальной инфраструктуры. Это позволяет:
- изолировать нагрузку и быстро отлаживать отдельные компоненты;
- переиспользовать уже написанные скрипты в разных контекстах;
- масштабировать количество параллельных выполнений без риска конфликтов состояний.
Пример конфигурации модульного пайплайна (YAML)
yaml# pipeline.yaml
modules:
- name: "fetch-sources"
entrypoint: "python -m fetch_sources"
schedule: "*/5 * * * *"
resources:
cpu: 0.5
memory: 256Mi
- name: "analyze-code"
entrypoint: "docker run --rm -v ${{pwd}}:/work ghcr.io/affaan-m/ecc:latest analyze --mode fast"
schedule: "0 2 * * *"
resources:
cpu: 1
memory: 512Mi
- name "generate-report"
entrypoint: "python -m generate_report"
depends_on: ["analyze-code"]
resources:
cpu: 0.7
memory: 384Mi
Команда docker run в примере использует образ ghcr.io/affaan-m/ecc:latest, который уже содержит все необходимые зависимости. При необходимости можно заменить образ на локальный, разместив его на домашнем сервере.
Как подключить новый модуль
bash# Добавляем модуль в pipeline.yaml
echo "- name: \"run-linter\"" >> pipeline.yaml
echo " entrypoint: \"flake8 .\"" >> pipeline.yaml
echo " schedule: \"*/10 * * **\"" >> pipeline.yaml
После изменения файла достаточно перезапустить агент:
bashagentctl restart --pipeline
На практике я видел случай, когда без изоляции модулей один из скриптов «залипал» в бесконечном цикле и блокировал остальные задачи. Выделение ресурсов через
cpuиmemoryв конфиге устранило проблему.
Подробнее о подходах к управлению пайплайнами — в статье Управление fleet-агентами разработки с Orca.
Memory Management Strategies
Эффективное управление памятью — ключ к стабильной работе агентов, особенно при работе с большими контекстами или при одновременном выполнении множества задач. В affaan-m/ECC применяются три проверенных стратегии:
- Кеширование результатов — хранение часто используемых данных в fast‑access хранилище (Redis) с TTL.
- Ограничение размеров буферов — каждый модуль получает ограничение на объём памяти, задаваемое в конфиге.
- Lazy‑loading — загрузка ресурсов только при необходимости, а не при инициализации агента.
Пример настройки кеша в Docker‑Compose
yaml# docker-compose.yml
services:
redis:
image: redis:7-alpine
restart: always
volumes:
- redis-data:/data
command: ["redis-server", "--maxmemory", "256mb", "--maxmemory-policy", "allkeys-lru"]
agent:
image: ghcr.io/affaan-m/ecc:latest
environment:
- CACHE_URL=redis://redis:6379/0
- MEMORY_LIMIT=1Gi
depends_on:
- redis
Здесь CACHE_URL указывает агенту, где находится кеш, а MEMORY_LIMIT задаёт верхний предел потребления памяти. При превышении лимита агент автоматически начинает освобождать ресурсы, удаляя менее используемые кеш‑ключи.
Lazy‑loading в коде (Python)
pythonimport os
from functools import lru_cache
@lru_cache(maxsize=128)
def get_config(path: str) -> dict:
"""Загружает конфигурацию из файла только при первом запросе."""
with open(path, "r", encoding="utf-8") as f:
return yaml.safe_load(f)
# Пример использования
config = get_config("/etc/ecc/config.yaml")
Декоратор @lru_cache гарантирует, что файл конфигурации будет прочитан один раз за процесс, экономя I/O и уменьшая нагрузку на файловую систему.
Рекомендации по памяти
- рекомендуется задавать
MEMORY_LIMITв пределах 70 % от доступного объёма ОЗУ, чтобы оставить резерв для системных процессов; - на практике я видел случай, когда без ограничения памяти агент «съел» 8 GiB и привёл к OOM‑киллу, останавливающему весь пайплайн;
- категорически не рекомендуется использовать безлимитные
ulimitв production‑окружениях — это создаёт риск неожиданного роста потребления.
Подробнее о настройке памяти и других аспектах — в статье AI‑агент как ленивый senior dev: код без усилий.
Для дальнейшего углубления смотрите также affaan-m/ECC: Agent Harness Performance Optimization.
Instinctive Decision Making and Research‑First Approach
Instinctive Decision Making and Research‑First Approach
Dynamic Prompt Engineering
При работе с agent‑harnessом инстинктive‑принятие решений требует чёткого формулирования запроса.
Типовая ошибка – писать «сделай всё», без указания контекста и ожидаемого результата.
Практический пример – подготовка промпта для анализа кода в Claude Code:
bashcat > prompt.txt <<'EOF'
You are a senior DevSecOps engineer. Review the following Dockerfile and list
1) security concerns,
2) possible performance improvements,
3) recommended changes to make the image reproducible.
Dockerfile:
<insert Dockerfile content here>
EOF
Запуск проверки:
bashcurl -X POST https://api.anthropic.com/v1/messages \
-H "Authorization: Bearer $ANTHROPIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "'"$(cat prompt.txt)"'"}'
Рекомендуется всегда начинать с research‑first: проверяйте официальную документацию affaan-m/ECC, убедитесь, что используемая версия CLI совместима, затем формируйте запрос.
Если нужно сравнить несколько вариантов, используйте few‑shot‑примеры, как описано в статье AI‑агент как ленивый senior dev.
Iterative Validation Protocols
После формирования промпта следует итеративно валидировать полученный результат.
- Проверка на практике – запустите полученный совет в тестовом окружении.
- Сравнение с базовым образом – зафиксируйте метрики (время сборки, размер образа).
Скрипт валидации (bash):
bash#!/usr/bin/env bash
set -euo pipefail
IMAGE_TAG="test/agent-harness:latest"
PROMPT_FILE="prompt.txt"
# 1. Сборка образа
docker build -t "$IMAGE_TAG" .
# 2. Запуск контейнера и сбор метрик
CONTAINER_ID=$(docker run -d "$IMAGE_TAG")
docker exec "$CONTAINER_ID" timeout 300 bash -c "time docker build -t test/agent-harness:tmp ."
docker stop "$CONTAINER_ID" && docker rm "$CONTAINER_ID"
# 3. Сравнение размеров
ORIG_SIZE=$(docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}" "$IMAGE_TAG" | awk '{print $2}')
TMP_SIZE=$(docker images --format "{{.Repository}}:{{.Tag}} {{.Size}}" test/agent-harness:tmp | awk '{print $2}')
echo "Original size: $ORIG_SIZE"
echo "Optimized size: $TMP_SIZE"
# 4. Очистка
docker rmi "$IMAGE_TAG" test/agent-harness:tmp
На практике я видел случай, когда без итеративного теста оптимизация привела к увеличению размера образа на 30 % и падению производительности.
Рекомендуется использовать CI‑pipeline (GitHub Actions, GitLab CI) для автоматической проверки после каждого изменения промпта. Пример конфигурации в .github/workflows/validate.yml:
yamlname: Validate Prompt
on:
push:
paths:
- 'prompts/**'
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run validation script
run: |
chmod +x ./scripts/validate.sh
./scripts/validate.sh
Категорически не рекомендуется игнорировать логи сборки – они часто раскрывают скрытые зависимости, которые влияют на итоговую производительность.
Итого: инстинктивное принятие решений должно подкрепляться исследованием и проверкой. Динамическое инженерение промптов вместе с итеративной валидацией гарантирует, что оптимизации agent‑harness действительно приносят пользу, а не лишь «показатели» в отчёте.
Security and Access Control in the Agent Harness
Security and Access Control in the Agent Harness
Zero‑Trust Authentication
В любой сети, где агент может быть запущен на чужом хосте, нельзя доверять сети — только проверенному удостоверению.
Проверка токена
Токен должен быть короткоживущим (не более 15 минут) и подписанным с помощью асимметричного ключа. При каждом запросе агент проверяет подпись и срок действия.
bash# пример проверки токена через curl
curl -s -H "Authorization: Bearer $AGENT_TOKEN" \
https://api.agent.example.com/v1/status | jq .
Мутual TLS
Агент и контроллер должны использовать клиентские сертификаты. При генерации сертификата указывайте CN=agent-<id> и ограничьте срок действия 1 час.
bash# генерация клиентского сертификата (openssl)
openssl req -new -newkey ec:<(openssl ecparam -name prime256v1) \
-nodes -keyout agent.key -out agent.csr \
-subj "/CN=agent-$(openssl rand -hex 4)"
openssl x509 -req -in agent.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
-days 3600 -sha256 -out agent.crt
Принцип least privilege
Каждому агенту выдаётся отдельный набор прав. Не используйте общие токены с правами администратора.
рекомендуется: хранить токены в Vault или в файле с правами 0600, доступным только процессу агента.
категорически не рекомендуется: использовать один общий токен для всех агентов.
Для детального описания процесса аутентификации см. Управление fleet-агентами разработки с Orca.
Secure Memory Isolation
Агент работает в изолированном окружении, где доступ к памяти ограничен только тем процессам, которые явно разрешены.
Docker‑контейнер с read‑only файловой системой
bashdocker run -d \
--name agent-secure \
--read-only \
--tmpfs /run:rw,size=64m \
--security-opt=no-new-privileges \
--cap-drop ALL \
--cap-add CHOWN \
--cap-add SETGID \
--cap-add SETUID \
-e AGENT_TOKEN=$AGENT_TOKEN \
myregistry/agent-harness:latest
--read-only— файловая система не меняется, исключая возможность подмены кода.--tmpfs /run— временный образ в памяти, не сохраняется на диск.--security-opt=no-new-privileges— запрещает процессу получать новые привилегии через setuid/setgid.
AppArmor профиль
bash# профиль /etc/apparmor.d/agent-harness
profile agent-harness {
#include <tunables/global>
/proc/** r,
/sys/** r,
/dev/** r,
/run/** rw,
deny /bin/** wklx,
deny /usr/bin/** wklx,
# разрешаем только нужные команды
/usr/bin/agent-exec wklx,
}
Загрузить профиль:
bashapparmor_parser -r /etc/apparmor.d/agent-harness docker run ... --security-opt apparmor=agent-harness ...
eBPF‑изоляция
Для высоконагруженных сред используйте eBPF‑политику, ограничивающую доступ к памяти через cgroup‑subsystem. Пример политики в bpftool:
bashbpftool prog load /etc/bpf/agent_mem_isolate.bpf bpftool prog attach pinned/1234
рекомендуется: проверять, что процесс не может читать чужие сегменты памяти (
/proc/<pid>/maps).
категорически не рекомендуется: запускать агент с
--privilegedили в контейнере, где отключена изоляция.
Для более глубокой информации о изоляции памяти смотрите affaan-m/ECC: Agent Harness Performance Optimization.
Чек‑лист дальнейших действий
- Сгенерировать и распределить короткоживущие подписанные токены (не более 15 минут).
- Настроить mTLS‑соединения между контроллером и каждым агентом.
- Внедрить read‑only файловую систему и ограниченный
tmpfsдля всех агентов. - Добавить AppArmor‑профиль, разрешающий только необходимые возможности.
- Протестировать eBPF‑политику и убедиться, что процесс не может читать чужие сегменты памяти.
- Проводить регулярный аудит токенов и сертификатов (политика «rotate every 24 h»).
- Включить мониторинг попыток доступа к памяти через
auditdиjournalctl.
Соблюдение этих мер гарантирует, что агент будет работать в безопасной изолированной среде, а любые попытки несанкционированного доступа будут сразу обнаружены.
Deployment, Monitoring and Continuous Optimization
CI/CD Integration for Agent Workflows
В pipeline CI/CD нужно обеспечить изоляцию выполнения агент‑харнесса, чтобы не «засорить» production‑окружение и не утечками токенов. Типичный этап выглядит так:
- Сборка образа – собираем Docker‑образ с агент‑харнессом и всеми зависимостями.
- Тестирование в CI – запускаем набор unit‑ и integration‑тестов в отдельном контейнере, который не имеет доступа к продакшн‑сети.
- Публикация – после успешного теста образ пушим в регистр (GitHub Packages, Docker Hub и т.п.).
- Деплой в staging – с помощью Helm/Kustomize или простого
kubectl applyразворачиваем образ в предварительное окружение.
Пример GitHub Actions workflow
yaml# .github/workflows/agent-ci.yml
name: Agent Harness CI
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Login to Docker registry
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Build agent harness image
run: |
docker build -t ghcr.io/${{ github.repository }}/agent-harness:${{ github.sha }} .
docker push ghcr.io/${{ github.repository }}/agent-harness:${{ github.sha }}
- name: Run unit tests
run: |
docker run --rm ghcr.io/${{ github.repository }}/agent-harness:${{ github.sha }} pytest -vv
Важно:
- Never запускайте
docker run --privilegedили не ограничьте контейнер в production‑сети без предварительной проверки. - Рекомендуется использовать отдельный namespace в Kubernetes (
agent-harness-staging) и ограничитьresources.requests/limits. - Категорически не рекомендуется хранить токены доступа в репозитории; используйте GitHub Secrets или HashiCorp Vault.
Для управления fleet‑агентами в продакшн‑среде удобно интегрировать Orca (см. Управление fleet-агентами разработки с Orca). Orca предоставляет API‑эндпоинты, которые можно вызывать из CI‑pipeline для автоматического деплоя новых версий.
Пример деплоя в Kubernetes через Orca
bash# Создаём или обновляем манифест
cat <<EOF > orca-deploy.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: agent-harness
labels:
app: agent-harness
spec:
replicas: 2
selector:
matchLabels:
app: agent-harness
template:
metadata:
labels:
app: agent-harness
spec:
containers:
- name: agent-harness
image: ghcr.io/yourorg/agent-harness:${TAG}
ports:
- containerPort: 8080
env:
- name: ORCAS_API_URL
value: "https://orca.example.com/api"
securityContext:
readOnlyRootFilesystem: true
runAsNonRoot: true
EOF
# Применяем манифест
kubectl apply -f orca-deploy.yaml
После деплоя проверяйте, что контейнер запустился без ошибок и что метрики доступны (см. следующий раздел).
Observability and Metrics Collection
Для надёжной работы агент‑харнесса необходимо собирать метрики и логи в реальном времени. Основные показатели:
| Метрика | Описание | Пример источника |
|---|---|---|
agent_execution_latency_seconds | Время от получения запроса до завершения задачи | Prometheus exporter в контейнере |
agent_success_total / agent_failure_total | Счётчики успешных/неуспешных выполнений | increment в коде |
token_usage_bytes | Объём использованных токенов (контекст + вывод) | лог‑параsing |
cpu_throttling_seconds | Время, когда контейнер был ограничен CPU | cAdvisor / Prometheus |
log_error_count | Кол‑во ошибок, залогированных в Loki | promtail → Loki |
Prometheus‑exporter (Python)
python# exporter.py
from prometheus_client import start_http_server, Counter, Gauge
LATENCY = Gauge('agent_execution_latency_seconds', 'Execution time in seconds')
SUCCESS = Counter('agent_success_total', 'Number of successful runs')
FAILURE = Counter('agent_failure_total', 'Number of failed runs')
TOKEN_USE = Counter('agent_token_usage_bytes', 'Bytes of tokens used')
def record_latency(seconds):
LATENCY.set(seconds)
def record_success():
SUCCESS.inc()
def record_failure():
FAILURE.inc()
def record_token_usage(bytes_used):
TOKEN_USE.set(bytes_used)
if __name__ == '__main__':
start_http_server(8000) # /metrics endpoint
Запуск: python exporter.py – сервер будет слушать localhost:8000/metrics.
Prometheus‑scrape‑config
yaml# prometheus.yml
scrape_configs:
- job_name: 'agent_harness'
static_configs:
- targets: ['agent-harness-staging:8000']
metrics_path: '/metrics'
scheme: http
Loki + Promtail для логов
promtail-config.yaml
yamlserver:
http_listen_port: 9080
grpc_listen_port: 0
positions:
filename: /tmp/positions.yaml
clients:
- url: http://loki:3100/loki/api/v1/push
scrape_configs:
- job_name: system
static_configs:
- targets:
- localhost
labels:
job: system
__path__: /var/log/**/*.log
Пример дашборда в Grafana
json{
"title": "Agent Harness Observability",
"panels": [
{
"type": "graph",
"title": "Execution latency",
"targets": [
{
"expr": "agent_execution_latency_seconds",
"legendFormat": "latency"
}
],
"yaxes": [
{ "format": "seconds", "label": "Latency" }
]
},
{
"type": "stat",
"title": "Success / Failure",
"targets": [
{ "expr": "sum(agent_success_total)", "legendFormat": "success" },
{ "expr": "sum(agent_failure_total)", "legendFormat": "failure" }
]
}
]
}
Советы от greyhat:
- С точки зрения безопасности экспортируйте метрики только в зашифрованном виде (TLS) и ограничьте доступ по IP‑адресам.
- Типовая ошибка – забыть про
readOnlyRootFilesystemв контейнере, что позволяет злоумышленнику писать файлы в файловую систему. Всегда проверяйтеsecurityContext. - На практике я видел случай, когда метрика
token_usage_bytesросла экспоненциально из‑за бесконечного цикла в агенте; мониторинг позволил быстро отреагировать и остановить контейнер.
Для более детального описания процессов см. AI‑агент как ленивый senior dev: код без усилий и Управление ИИ-агентами с помощью Orca.
Чек‑лист после деплоя:
- Образ прошёл все CI‑тесты без утечек токенов.
- Метрики доступны в Prometheus (
/metricsотвечает 200). - Loki принимает логи без ошибок, проверка
promtail‑позиций. - TLS‑сертификат актуален, доступ к
/metricsограничен только внутренними IP. - Ограничения ресурсов (
requests/limits) заданы, проверкаkubectl top pod.
Следуя этим рекомендациям, вы обеспечите стабильную работу агент‑харнесса и сможете быстро реагировать на любые отклонения в работе.
Часто задаваемые вопросы
Как добавить новый модуль в конфигурацию пайплайна?
Для добавления нового модуля отредактируйте файл pipeline.yaml, добавив блок с именем, entrypoint, расписанием и ресурсами. После сохранения выполните agentctl restart --pipeline для перезапуска агента и применения изменений. Модуль будет автоматически подхвачен в расписании, если указать корректный cron‑выражение.
Какие ресурсы (CPU, память) следует выделять модулям?
Ресурсы следует подбирать в зависимости от нагрузки конкретного модуля: например, I/O‑интенсивные скрипты обычно достаточно 0.5 CPU и 256 MiB памяти, а вычислительно тяжёлые — 1 CPU и 512 MiB или больше. В примере конфигурации указаны минимальные значения, которые можно увеличить при обнаружении Bottleneck. При превышении лимитов модуль будет ограничен и может завершиться с ошибкой.
Почему модуль может «залипать» в бесконечном цикле и как это исправить?
Такие ситуации возникают, когда модуль не изолирован от остальных процессов и накапливает состояние в памяти. В systemе affaan-m/ECC каждый модуль запускается в отдельном контейнере или с ограниченными ресурсами, что предотвращает «залипание». Если проблема всё равно появляется, проверьте логи через journalctl -u agent и при необходимости добавьте тайм‑аут или перезапуск контейнера.
Можно ли использовать локальный образ вместо Docker‑Hub для запуска модулей?
Да, вместо ghcr.io/affaan-m/ecc:latest можно разместить образ на домашнем сервере и указать локальный путь в entrypoint, например docker run --rm -v /home/agent/ecc:/work my-registry/ecc:latest. Это уменьшает задержку сети и повышает надёжность при отсутствии интернет‑доступа. Убедитесь, что образ построен с теми же зависимостями, что и официальный.