Продвинутый

affaan-m/ECC: Agent Harness Performance Optimization

greyhat
greyhat
Специалист по безопасности20 ноября 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

Компоненты системы

Система agent harness состоит из нескольких взаимодействующих модулей, каждый из которых отвечает за конкретную часть процесса выполнения агентов.

  • Agent Manager — отвечает за создание, запуск и завершение агентов. При старте он читает конфигурацию из agent_harness.yaml и формирует список задач.
yaml
# agent_harness.yaml
agents:
  - name: "code-analyzer"
    image: "ghcr.io/anthropic/claude-code:latest"
    resources:
      cpu: 2
      memory: 4Gi
    env:
      - name: "LOG_LEVEL"
        value: "info"
  - name: "data-sync"
    image: "ghcr.io/anthropic/opencode:latest"
    resources:
      cpu: 1
      memory: 2Gi
    env:
      - name: "API_KEY"
        value: "REPLACE_WITH_REAL_KEY"
  • Task Scheduler — распределяет задачи между агентами, учитывая их текущую нагрузку. Реализован на базе cron-подобного планировщика, который берёт метрики из Prometheus.
bash
# пример запроса к Prometheus для получения средней загрузки CPU
curl -s 'http://localhost:9090/api/v1/query?query=avg_over_time(container_cpu_usage_seconds_total{container!="",image!=""}[5m])'
  • Resource Monitor — следит за потреблением CPU, памяти, сетевого трафика и температурой контейнеров. При превышении порогов инициирует автоматическое масштабирование или завершение агента.
bash
# скрипт проверки памяти и её логирование
#!/usr/bin/env bash
MEM=$(curl -s http://localhost:9090/api/v1/query?query=container_memory_usage_bytes{container!="",image!=""} | jq -r '.[0].value[0]')
MAX=2147483648   # 2GiB
if (( MEM > MAX )); then
    echo "$(date) [WARN] Memory usage high: $MEM bytes" | tee -a /var/log/agent_harness.log
    # здесь может быть вызов API для уменьшения реплик
fi
  • Security Guard — проверяет, что образ агента подписан, что переменные окружения не содержат конфиденциальных данных и что запуск происходит в изолированном контейнере с seccomp‑профилем.
json
{
  "securityProfile": {
    "syscalls": ["read", "write", "open", "close", "exit"],
    "allowNetwork": true,
    "readOnlyRootFilesystem": true
  }
}
  • Config Loader — обеспечивает динамическое обновление конфигураций без перезапуска всего сервиса. Поддерживает как файлы YAML, так и environment‑переменные через consul‑key‑value store.

Оптимизация ИИ-агентов с помощью системы ECC — в этой статье описаны подходы к управлению конфигурациями, которые легко адаптировать под наш harness.


Механизмы обратной связи

Обратная связь в agent harness реализуется через несколько каналов, позволяющих системе быстро реагировать на изменения нагрузки и ошибки.

  1. Метрики производительности
    • CPU / Memory — собираются Prometheus‑exporter’ом, агрегируются в Grafana‑дашбордах.
    • Latency — измеряется время от получения задачи до её завершения, сохраняется в Loki.
promql
# пример запроса: средняя длительность задачи в секундах
sum(rate(agent_task_duration_seconds_bucket[1m])) by (agent_name)
  1. Система оповещений
    • При превышении порогов (CPU > 80 % более 2 минут, ошибки > 5 % от общего числа задач) отправляются уведомления в Slack и в консоль сервера.
bash
#!/usr/bin/env bash
THRESHOLD=80
CPU=$(curl -s 'http://localhost:9090/api/v1/query?query=avg_over_time(container_cpu_usage_seconds_total{container!="",image!=""}[2m])' | jq -r '.[0].value[0] | tonumber')
if (( $(echo "$CPU > $THRESHOLD" | bc -l) )); then
    curl -X POST -H 'Content-type: application/json' \
        --data '{"text":"⚠️ Высокая загрузка CPU: '"$CPU"'%"}' \
        https://hooks.slack.com/services/XXX/YYY/ZZZ
fi
  1. Адаптивное масштабирование
    • На основе метрик система автоматически меняет количество реплик агента через Kubernetes Horizontal Pod Autoscaler (HPA).
yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: agent-harness
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: agent-harness
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  1. Обратная связь от агентов
    • Каждый агент отправляет статус‑сообщения (успех, неудача, тайм‑аут) через HTTP‑POST на /api/feedback. Это позволяет системе пересматривать приоритет задач.
json
POST /api/feedback
{
  "agent": "code-analyzer",
  "status": "failed",
  "error": "timeout after 30s",
  "timestamp": "2025-10-31T12:00:00Z"
}

DietrichGebert/ponytail: AI‑agent like the lazy senior dev — в этой работе рассматриваются подходы к построению надёжных каналов обратной связи, которые мы применяем в нашем harness.

  1. Логирование и аудит
    • Все действия фиксируются в audit.log с меткой времени, именем агента и результатом операции. Это критически важно для расследования инцидентов и соответствия требованиям безопасности.
bash
# пример записи в audit.log
echo "$(date '+%Y-%m-%d %H:%M:%S') [INFO] Agent 'data-sync' completed successfully" >> /var/log/audit.log

Эти механизмы позволяют agent harness поддерживать высокий уровень надёжности и отзывчивости, а также быстро реагировать на любые отклонения от ожидаемого поведения. В следующем разделе будет рассмотрена механизмы обратной связи в более детальном виде.

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

Навыки и инстинкты

Когда мы говорим об оптимизации производительности в контексте ECC (Agent Harness Performance Optimization), важно понимать: задержка (latency) — это не только скорость ответа модели, это время, которое агент тратит на «раздумья» и лишние циклы планирования. Типовая ошибка при работе с Claude Code или Cursor — позволить агенту бесконечно перебирать варианты в попытке решить задачу. Это сжигает токены и время.

С точки зрения безопасности и эффективности, агент должен обладать «инстинктом» раннего выхода. Вместо того чтобы пробовать все подряд, harness должен ограничивать область поиска через контекстные подсказки. На практике я видел случаи, когда агенты уходили в бесконечные циклы рефакторинга, пытаясь исправить несуществующую проблему, просто потому что им не задали жесткие границы.

Для оптимизации этого процесса рекомендуется внедрять систему ограничений на количество итераций (step limit) и использовать специализированные системные промпты, которые заставляют модель переходить к действию, если она не нашла решение за N шагов.

Пример конфигурации ограничений для агента в среде разработки:

yaml
# Конфигурация ограничений для agent harness
agent_constraints:
  max_iterations: 5             # Максимальное количество шагов на одну задачу
  max_tokens_per_step: 2000     # Ограничение на длину ответа, чтобы не ждать вечность
  allow_shell_execution: true   # Разрешаем выполнение команд, но...
  execution_timeout: 30s        # Категорически не рекомендую ставить больше 30с для dev-инструментов
  safety_check_enabled: true    # Обязательная проверка команд перед выполнением

Если вы хотите глубже изучить, как выстроить архитектуру управления такими агентами, рекомендую прочитать материал про оптимизацию ИИ-агентов с помощью системы ECC.

Память и кэш

Память агента — это его контекстное окно. Чем больше в него запихано лишнего, тем медленнее работает модель и тем выше вероятность галлюцинаций. В ECC оптимизация памяти строится на двух столпах: семантическом кэшировании и агрессивной очистке контекста.

Вместо того чтобы каждый раз скармливать агенту весь лог выполнения или всю структуру проекта, нужно использовать векторные представления (embeddings) для быстрого поиска только релевантных кусков кода. Это похоже на то, как работает эффективная домашняя лаборатория, где вы не перебираете все диски, а обращаетесь к конкретному индексу.

На практике я использую подход «скользящего окна» для логов и кэширование результатов тяжелых операций (например, сканирования проекта nmap или grep).

Пример реализации локального кэша для контекста агента:

bash
# Пример очистки контекста от мусора перед отправкой в модель
# Удаляем временные файлы, логи сборки и артефакты, которые не несут смысла
find . -type d \( -name "node_modules" -o -name ".git" -o -name "dist" \) -prune -o -print | grep -v "junk_pattern" > context_map.txt

# Проверка целостности кэша перед использованием
# Никогда не доверяйте кэшу, если он не прошел валидацию по контрольной сумме
sha256sum context_map.txt > context_map.sha256

С точки зрения безопасности, работа с кэшем требует осторожности. Если агент сохраняет в память чувствительные данные (API-ключи, токены), эти данные могут «утечь» в следующий запрос или в логи провайдера (Anthropic/OpenAI). Настоятельно рекомендую использовать инструменты для автоматического маскирования (redaction) чувствительной информации перед тем, как она попадет в контекстное окно.

Для тех, кто планирует масштабировать такие решения и запускать целые группы агентов, стоит изучить запуск флота AI-агентов с Orca. Это даст понимание, как управлять памятью на уровне распределенной системы.

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

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

Когда мы говорим об оптимизации agent harness, фокус часто смещается на скорость отклика и объём контекста. Но с точки зрения безопасности, чем больше полномочий мы даём агенту (Claude Code, Cursor или кастомным решениям на базе Orca), тем выше риск превратить инструмент разработки в инструмент для компрометации вашей системы.

Типовая ошибка — запускать агентный интерфейс с правами текущего пользователя, имеющего доступ к SSH-ключам, конфигурациям облачных провайдеров и секретам в .env файлах. Если агент совершит ошибку в логике или будет подвержен атаке через Prompt Injection, он получит полный контроль над вашей домашней лабораторией.

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

Агент не должен работать в среде, где доступ к API или интерфейсу управления открыт всем. Если вы разворачиваете ECC для управления флотом агентов, как это описано в материале про запуск флота AI-агентов, первым делом изолируйте точку входа.

Категорически не рекомендуется использовать простые API-ключи без ограничений по IP или времени жизни. Для управления агентами я рекомендую внедрять двухфакторную аутентификацию (2FA) на уровне прокси-сервера или использовать краткосрочные токены.

На практике я часто вижу, как разработчики оставляют порты управления открытыми для всего локального интерфейса. Если ваш агент работает в Docker, убедитесь, что API не проброшено на 0.0.0.0 без защиты.

Пример настройки Nginx как защитного слоя перед API агента с использованием базовой аутентификации и ограничением по IP:

nginx
server {
    listen 443 ssl;
    server_name agent-control.local;

    # Настройка TLS — только современные протоколы
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location /api/v1/ {
        # Ограничение доступа по IP (замените на ваш адрес)
        allow 192.168.1.0/24;
        deny all;

        # Базовая аутентификация
        auth_basic "Restricted Access";
        auth_basic_user_file /etc/nginx/.htpasswd;

        proxy_pass http://agent_harness_backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Изоляция и ограничения

Изоляция — это единственный способ гарантировать, что агент не «уйдёт в разнос». Если вы используете систему ECC для оптимизации агентов, каждый агент должен работать в максимально ограниченном окружении.

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

Рекомендуемые меры изоляции:

  1. Read-only файловая система: Агент должен иметь право записи только в строго определённые директории (например, рабочая папка проекта). Все остальные части системы должны быть доступны только для чтения.
  2. Ограничение сетевого доступа: Агент не должен иметь возможности сканировать вашу локальную сеть. Используйте Docker network для изоляции.
  3. Seccomp и AppArmor: Ограничьте системные вызовы, которые может выполнять процесс агента.

Пример Docker Compose конфигурации для запуска агента в изолированном окружении:

yaml
services:
  agent-harness:
    image: ecc-agent-runtime:latest
    user: "1000:1000" # Запуск от не-привилегированного пользователя
    read_only: true    # Файловая система только для чтения
    tmpfs:
      - /tmp          # Разрешаем запись только в /tmp
      - /app/workspace # Разрешаем запись только в рабочую директорию
    networks:
      - agent_net
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
    security_opt:
      - no-new-privileges:true # Запрет повышения привилегий

networks:
  agent_net:
    internal: true # Запрещает агенту прямой выход в интернет, если это не требуется

Перед тем как разворачивать подобные системы, проверьте, какие права доступа у вашего пользователя в системе. Если вы работаете над задачами, похожими на те, что описываются в статье про DietrichGebert/ponytail, помните: агент — это не ваш коллега, это инструмент с непредсказуемым поведением. Относитесь к нему как к потенциально скомпрометированному процессу.

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

Тестирование и benchmarking

В работе с ИИ-агентами вроде Claude Code или Cursor главная проблема — это нехватка предсказуемости. Вы можете настроить идеальный контекст, но при изменении версии модели или обновлении системного промпта поведение агента изменится. С точки зрения безопасности и стабильности это критично: агент может начать генерировать более опасные команды или ошибаться в логике доступа.

Чтобы не гадать, работает ли оптимизация ECC, я использую подход, основанный на количественных метриках. Мы не оцениваем «качество кода» на глаз. Мы замеряем три параметра:

  1. Latency (задержка): время от постановки задачи до первого полезного действия.
  2. Token Efficiency (эффективность токенов): сколько контекста тратится на выполнение одной итерации. Лишние токены — это не только деньги, но и риск «замыливания» внимания модели.
  3. Success Rate (коэффициент успеха): процент задач, выполненных без ручного вмешательства.

Для автоматизации этого процесса я использую кастомные скрипты, которые прогоняют агент через набор изолированных задач в Docker-контейнерах. Типовая ошибка — тестировать агента прямо на основной машине. Никогда не делайте этого. Если агент в процессе «исследования» решит протестировать rm -rf / или некорректную команду chmod, вы потеряете данные.

Пример конфигурации для бенчмарка в среде ECC, где мы ограничиваем ресурсы и фиксируем окружение:

yaml
# benchmark-config.yaml
test_suite:
  name: "security-audit-tasks"
  environment:
    image: "debian:bookworm-slim" # Изолированный образ
    network: "none"               # Отключаем сеть, чтобы агент не ушел во внешний мир
    capabilities:
      drop: ["ALL"]             # Ограничиваем привилегии
  metrics:
    track_tokens: true
    max_iterations: 5

Запуск теста выглядит примерно так:

bash
# Запуск бенчмарка для оценки эффективности контекста
./ecc-bench --suite security-audit-tasks --model claude-3-5-sonnet --output report.json

Если вы только начинаете строить свою инфраструктуру для агентов, рекомендую изучить Оптимизация ИИ-агентов с помощью системы ECC, чтобы понять базу измерений.

Обратная связь и улучшения

Бенчмарки дают цифры, но не дают понимания причин. Когда агент «галлюцинирует» или зацикливается, нам нужно понимать, на каком этапе произошел сбой: на уровне извлечения знаний из памяти или на уровне интерпретации системного промпта.

На практике я видел случай, когда агент успешно выполнял задачи, но тратил в 3 раза больше токенов, чем нужно, просто потому что его «инстинкты» (настроенные через ECC) заставляли его перечитывать весь README.md при каждом запросе. Это классический пример неэффективного использования памяти.

Для исправления таких ситуаций я внедряю цикл обратной связи (Feedback Loop), состоящий из двух этапов:

  1. Анализ логов выполнения: Мы не просто смотрим на результат, мы анализируем цепочку рассуждений (Chain of Thought). Если агент делает неверный вывод, мы фиксируем этот паттерн.
  2. Корректировка весов памяти: Вместо того чтобы просто менять промпт, мы меняем то, как ECC подбирает релевантные куски данных для текущей задачи.

Для автоматизации сбора ошибок я использую связку из journald (для логов самого агента) и кастомного парсера, который вычленяет ошибки выполнения команд.

bash
# Пример команды для быстрого анализа логов ошибок агента за последний час
journalctl -u ecc-agent --since "1 hour ago" | grep -E "error|failed|denied"

Важно понимать: улучшение агента — это не добавление новых инструкций «будь осторожен». Это тонкая настройка того, какую информацию агент получает в момент принятия решения. Если вы хотите посмотреть, как это реализуется в более «ленивом», но эффективном стиле, почитайте про DietrichGebert/ponytail.

Если же ваша цель — масштабирование, то после отладки одного агента следующим шагом станет развертывание целого флота, о чем подробно написано в материалах про запуск флота AI-агентов с Orca.

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

Как обеспечить безопасность API-ключей в конфигурации?

Категорически не рекомендуется хранить секреты в открытом виде в файле agent_harness.yaml. С точки зрения безопасности, это типичная ошибка, которая приводит к утечке данных при попадании конфига в репозиторий. На практике я рекомендую использовать переменные окружения или специализированные хранилища секретов, подставляя их в конфигурацию через механизм подстановки вашего оркестратора.

Можно ли использовать ECC для запуска агентов на домашнем сервере?

Да, систему можно развернуть на собственном оборудовании, если ресурсы позволяют запустить контейнеры с указанными лимитами. Однако при размещении на своём оборудовании важно заранее рассчитать запас по оперативной памяти и CPU, так как Resource Monitor может инициировать масштабирование, что создаст пиковую нагрузку. Перед запуском проверьте, что ваша домашняя лаборатория защищена и лишние порты не проброшены во внешнюю сеть.

Как ограничить потребление ресурсов агентами?

Ограничение ресурсов задаётся в блоке resources для каждого агента в конфигурационном файле. Это позволяет предотвратить ситуацию, когда один агент потребляет все доступные мощности и вызывает отказ всей системы. Настоятельно рекомендуется всегда устанавливать жесткие лимиты (limits) на CPU и память, чтобы Resource Monitor мог корректно реагировать на аномалии.

Что произойдёт, если агент превысит установленный лимит памяти?

При превышении лимита Resource Monitor зафиксирует инцидент и запишет предупреждение в лог. В зависимости от настроек, система может попытаться масштабировать ресурсы или принудительно завершить процесс агента для защиты стабильности всей платформы. Перед внедрением в production убедитесь, что вы настроили адекватные пороги срабатывания, чтобы избежать постоянных перезапусков из-за кратковременных всплесков нагрузки.

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

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