affaan-m/ECC: Agent Harness Performance Optimization
Agent harness performance optimization for Claude Code, Codex, Opencode, Cursor, focusing on skills, instincts, memory, security, research‑first dev.
Принципы оптимизации agent‑harness
Принципы оптимизации agent‑harness
### Распределение ресурсов по навыкам
Каждый навык AI‑агента (генерация кода, сканирование уязвимостей, анализ данных) имеет характерный профиль нагрузки — CPU, память и время выполнения. Неправильное распределение приводит к длительным задержкам, OOM‑сбоям и росту стоимости инфраструктуры.
Практический подход – задавать ограничения на уровне skill‑конфигурации и использовать cgroups/Docker‑лимиты.
yaml# config/agent-harness.yaml
skills:
code_gen:
cpu: 0.5 # 50 % одного ядра
memory_mb: 512 # 512 МБ RAM
timeout_sec: 300 # 5 минут
security_scan:
cpu: 1.0 # полностью один ядро
memory_mb: 1024 # 1 ГБ
timeout_sec: 600 # 10 минут
data_analysis:
cpu: 0.75 # три четверти ядра
memory_mb: 768 # 768 МБ
timeout_sec: 450 # 7,5 минут
Запуск агента с указанными лимитами:
bash# без Docker (через nice и cgroup)
nice -n 10 agent-harness run --skill code_gen
# ограничение CPU через cgroupv2
systemd-run --scope -p CPUQuota=50% -p MemoryMax=512M agent-harness run --skill code_gen
В Docker‑контейнере:
bashdocker run -d \ --cpus=0.5 \ --memory=512m \ -e SKILL=code_gen \ affaan-m/ecc:latest
Важно: не превышайте общую сумму CPU‑quota — агент‑ха́рнс работает в конкурентной среде, и перераспределение может «забить» другие задачи.
См. подробнее в affaan-m/ECC: оптимизация производительности агент‑ха́рнс.
### Паттерны принятия решений
При работе с agent‑harness типичные решения требуют оценки уверенности, количества повторных попыток и наличия резервных путей. Ниже — проверенные паттерны, которые снижают риск ошибок в production‑окружении.
1. Threshold‑based confidence
Перед выполнением критической операции (например, изменение конфигурации сервера) проверяйте уверенность модели. Если она ниже заданного порога, запрос отклоняется и переходит к fallback‑режиму.
yamldecision:
confidence_threshold: 0.85 # 85 % уверенности
max_retries: 3
fallback_enabled: true
Запуск с включённым fallback‑режимом:
bashagent-harness run --skill security_scan --fallback-human
2. Circuit‑breaker
Если количество ошибок превышает порог за фиксированный интервал, агент автоматически отключает дальнейшие запросы к данному skill и переходит в режим «pause». Это предотвращает каскадные сбои.
bash# пример включения circuit‑breaker в конфиге
circuit_breaker:
error_threshold: 5
time_window_sec: 60
3. Кэширование результатов
Для повторяющихся запросов (например, проверка того же патча в нескольких репозиториях) сохраняйте результаты в локальном кеше — экономит время и уменьшает нагрузку на LLM‑провайдер.
bash# включаем кеш в конфиге
cache:
enabled: true
directory: /var/cache/agent-harness
4. Ограничение параллелизма
Запуск слишком многих агентов одновременно может исчерпать ресурсы. Ограничьте количество одновременно активных задач.
bash# ограничиваем до 2 параллельных задач
export AGENT_MAX_PARALLEL=2
agent-harness run --skill data_analysis &
agent-harness run --skill code_gen &
Рекомендация: перед тем как дать команду «запустить», проверьте актуальные метрики (CPU, память, количество открытых файловых дескрипторов).
bashtop -b -n 1 | head -n 10 df -h / lsof -p $(pidof agent-harness) | wc -l
Подробные примеры паттернов см. в Ponytail: Как заставить AI‑агент вести себя как ленивый старший разработчик и Show HN: db-branch – ZFS DB branches in seconds for AI & CI.
Все приведённые команды и конфиги следует тестировать в отдельном тестовом окружении, а не в production, пока не убедились в их корректности.
Управление памятью и контекстом
Управление памятью и контекстом
### Буферы краткосрочной памяти
Буферы краткосрочной памяти – это окно контекста, которое модель использует для текущего диалога. Его размер задаёт лимит на количество токенов, которые могут одновременно участвовать в рассуждении. Превышение лимита приводит к «обрезке» контекста: самые старые сообщения отбрасываются, и агент теряет связь с важными данными.
Типовая ошибка – заполнение окна 8 К токенов без фильтрации. На практике я видел случай, когда агент, работающий с большим дампом логи, просто «забыл» инструкцию о включении 2FA, потому что её строка оказалась за пределами окна.
Как контролировать размер окна
bash# Оставляем только последние N строк лога (пример: 2000 строк)
tail -n 2000 /var/log/agent.log > /tmp/context.txt
yaml# Пример конфигурации llama.cpp (context_window = 4096 токенов)
model_path = "./models/llama-2-7b.Q4_0.gguf"
context_window = 4096
Практические приёмы
- Суммирование: перед отправкой в модель сократите длинные сообщения в 1‑2 предложения, используя «extractive summarization».
python
# Пример на Python с transformers from transformers import pipeline summarizer = pipeline("summarization", model="facebook/bart-large-cnn") short = summarizer(long_text, max_length=150, min_length=30)[0]['summary_text'] - Сliding window: храните только актуальные части диалога, а устаревшие – в векторном хранилище (см. ниже).
- Проверка перед отправкой: всегда проверяйте размер контекста командой
wc -wилиtokenizer.model_len.
С точки зрения безопасности – никогда не передавайте в контекст приватные токены, пароли или ключи SSH. Если требуется их использование, вынесите в отдельный защищённый канал (например, через ssh-agent) и не включайте в контекст.
### Постоянное хранение знаний
Для долговременного доступа к знаниям используйте векторные базы данных. Они позволяют хранить эмбеддинги и выполнять быстрый поиск по схожести, что заменяет «меморизацию» в памяти агента.
Выбор хранилища
- PGVector – удобен, если уже используете PostgreSQL.
- FAISS – быстрый, но требует отдельного сервиса.
- Milvus – масштабируемый, подходит для больших объёмов.
Пример индексации документов в PGVector
sql-- Создание таблицы для эмбеддингов
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE knowledge (
id SERIAL PRIMARY KEY,
doc_id UUID UNIQUE,
embedding vector(768),
payload JSONB
);
python# Python‑скрипт для загрузки эмбеддингов (используем sentence‑transformers)
from sentence_transformers import SentenceTransformer
import psycopg2
model = SentenceTransformer('all-MiniLM-L6-v2')
conn = psycopg2.connect(dsn="dbname=knowledge user=postgres")
def upsert_embedding(doc_id, text):
embedding = model.encode(text).tolist()
with conn:
conn.execute(
"INSERT INTO knowledge (doc_id, embedding, payload) VALUES (%s, %s, %s) "
"ON CONFLICT (doc_id) DO UPDATE SET embedding = EXCLUDED.embedding, payload = EXCLUDED.payload",
(doc_id, embedding, '{"source":"internal"}')
)
# Пример использования
upsert_embedding(uuid4(), "Настройка Fail2ban для защиты SSH‑доступа")
Постоянный кэш – для часто запрашиваемых данных удобно использовать Redis с сериализацией эмбеддингов. Пример конфигурации:
yaml# redis.conf
save 900 1
save 300 10
appendonly yes
Практические рекомендации
- Категорически не рекомендуется хранить в векторном хранилище raw‑токены доступа или приватные ключи.
- На практике я видел случай, когда в базе случайно попал полный дамп конфигураций VPN‑сервера, что привело к утечке данных. Всегда проверяйте, что в payload находятся только метаданные, а не чувствительная информация.
- Рекомендуется периодически пересчитывать эмбеддинги для устаревших документов, чтобы поддерживать актуальность векторного поиска.
Ссылки на материалы сайта
- Ponytail: оптимизация работы AI‑агентов – описывает подходы к суммированию и.
- affaan-m/ECC: оптимизация производительности агент‑ха́рнс – содержит примеры настройки контекстного окна.
- affaan-m/ECC: Agent Harness Performance Optimization – обсуждает интеграцию векторных хранилищ с агентами.
Защита агентных архитектур
Защита агентных архитектур
### Политики контроля доступа
Для ограничения прав доступа агентов применяйте принцип наименьших привилегий (least privilege).
Создайте отдельные IAM‑политики для каждого сервиса‑агента, где разрешены только необходимые действия (например, ai:InvokeModel для Claude Code, s3:GetObject для доступа к данным).
json{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ai:InvokeModel"
],
"Resource": "arn:aws:ai:us-east-1:123456789012:model/claude-code"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::agent-data-bucket",
"arn:aws:s3:::agent-data-bucket/*"
]
}
]
}
- Краткосрочные токены – используйте AWS STS или аналогичные сервисы для получения временных кредаencial‑токенов с ограниченным временем жизни (например, 15 минут).
- mTLS – при взаимодействии агентов через внутренние API включите mutual TLS, чтобы обеспечить аутентификацию обоих участников. Пример конфигурации Nginx:
nginxserver { listen 443 ssl; ssl_certificate /etc/nginx/certs/agent.crt; ssl_certificate_key /etc/nginx/certs/agent.key; ssl_client_certificate /etc/nginx/certs/ca.crt; location /api/agent/ { proxy_pass http://127.0.0.1:8080; proxy_set_header X-Client-Cert $ssl_client_cert; # Проверка сертификата клиента auth_request /auth; } location = /auth { internal; proxy_pass http://127.0.0.1:8080/auth; proxy_pass_request_body off; proxy_set_header Content-Length ""; proxy_set_header X-Original-URI $request_uri; auth_request_request_method POST; auth_request_request_body empty; return 200; } }
- Аудит и алерты – включите логирование всех вызовов LLM‑API (CloudTrail, GCP Audit Logs) и настройте правила в SIEM (Wazuh, Security Onion) для обнаружения аномального количества запросов или попыток доступа из неавторизованных IP‑адресов.
- Fail2ban/CrowdSec – добавьте фильтры для блокировки IP‑адресов, которые многократно делают некорректные запросы к эндпоинтам агента.
На практике я видел случай, когда злоумышленник использовал украденный API‑ключ для доступа к LLM‑endpoint и отправлял запросы с вредоносными инструкциями. После внедрения короткоживущих токенов и mTLS такой вектор был полностью закрыт.
affaan-m/ECC: оптимизация производительности агент‑ха́рнс — в статье описаны дополнительные меры по изоляции агентов, которые могут быть полезны в контексте контроля доступа.
### Моделирование угроз
Моделировать угрозы для агентных систем лучше всего с помощью техники STRIDE или PASTA, адаптируя её под конкретные сценарии взаимодействия с LLM‑моделями.
Пример таблицы угроз (STRIDE)
| Угроза | Источник | Воздействие | Снижение риска |
|---|---|---|---|
| Spoofing | Подделка API‑ключа | Неавторизованный доступ к модели | Использовать короткоживущие токены, mTLS |
| Tampering | Инъекция промпта (prompt injection) | Изменение поведения модели, выдача нежелательного кода | Валидация входных данных, ограничение длины и структуры промпта |
| Repudiation | Отсутствие аудита запросов | Невозможность отследить злоупотребления | Централизованный SIEM, immutable logs |
| Information Disclosure | Утечка конфиденциальных данных через вывод модели | Выявление приватных данных | Ограничение доступа к контексту, маскировка чувствительных полей |
| Denial of Service | Перегрузка LLM‑endpoint | Приостановка работы агентов | Rate‑limiting, автоскейлинг, резервные эндпоинты |
| Elevation of Privilege | Привилегированный контейнер с доступом к хосту | Компрометация всей инфраструктуры | Контейнеризация с seccomp/AppArmor, non‑root пользователь внутри контейнера |
Запуск агента в изолированном контейнере
bashdocker run -d \
--name claude-agent \
--cpus="2" \
--memory="4g" \
--security-opt no-new-privileges:true \
--security-opt seccomp=/etc/docker/seccomp.json \
-e ANTHROPIC_API_KEY=**** \
-v /path/to/agent/config:/app/config \
ghcr.io/anthropic/claude-code:latest
- seccomp – профиль, запрещающий системные вызовы, не нужные для работы агента (например,
clone,execveбез белого списка). - no-new-privileges – предотвращает повышение привилегий внутри контейнера.
Защита веб‑интерфейса агента
Если агент доступен через веб‑интерфейс, рекомендуется разместить ModSecurity в режиме OWASP CRS и добавить правило для блокировки подозрительных payload‑ов:
apacheSecRule REQUEST_URI "@rx /api/agent/.*" \ "id:1000001,phase:2,deny,log,msg:'Potential prompt injection attempt',\ t:none,ctl:ruleEngine=Off"
- Rate limiting – ограничьте количество запросов в минуту (например, 30 req/min) через
limit_reqв Nginx, чтобы снизить риск DoS‑атаки.
OSINT и мониторинг
Регулярно проверяйте публичные источники (GitHub, публичные репозитории) на наличие утечки промптов или конфигурационных файлов. Используйте curl для проверки TLS‑соединения:
bashcurl -v https://api.anthropic.com/ 2>&1 | grep "SSL connection"
Если сертификат не соответствует ожидаемому, немедленно инициируйте инцидент‑реагирование.
В статье Ponytail: Как заставить AI‑агент вести себя как ленивый старший разработчик обсуждаются приёмы, позволяющие минимизировать риск инъекций за счёт ограничения контекста и применения «ленивых» поведенческих шаблонов. Применяйте их в сочетании с вышеописанными политиками доступа.
Рабочий процесс разработки, ориентированный на исследование
Итеративное тестирование с Claude Code
Тестировать работу AI‑агентов в режиме реального времени – основной способ понять, где «затыкает» память, расчёт или безопасность.
Claude Code предоставляет CLI‑утилиту, которая позволяет запускать запросы, получать ответы и сохранять логи для последующего анализа.
bash# Запуск скрипта в песочной среде, ограничивая количество токенов и время
claude-code run \
--file test_perf.py \
--model claude-3-opus \
--max-tokens 4096 \
--timeout 30s \
--sandbox true
-
Почему sandbox? – В production‑окружении любые запросы могут получить доступ к файловой системе или сетевым ресурсам. Песочная среда гарантирует, что агент не сможет «выйти за пределы» и тем самым не нарушит безопасность.
-
Итеративный цикл – После получения ответа проверяйте:
- Логи (
~/.claude/logs/…) – ищите сообщения о превышении лимитов или о тайм‑аутах. - Потребление памяти –
psutil‑скрипт, который измеряет RSS процесса агента. - Качество ответа – сравните полученный код/текст с эталоном, используя
diff.
- Логи (
На практике я видел случай, когда агент, работающий без ограничения токенов, «залипал» в бесконечном цикле генерации, съедая 2 ГБ RAM и приводя к OOM‑у на небольшом Raspberry Pi. После добавления
--max-tokens 4096и--timeout 30sпроблема исчезла.
Рекомендации
- Всегда запускайте тесты в отдельном контейнере или виртуальном окружении.
- Не делайте
sudoвнутри CLI‑вызова – это повышает риск эскалации привилегий. - При работе с конфиденциальными данными используйте
--encrypt-output(если поддерживается) или передавайте данные черезstdinбез сохранения в файлах.
Ponytail: Как заставить AI‑агент вести себя как ленивый старший разработчик – в этой статье описаны приёмы, позволяющие «заставить» агентов работать более осторожно и экономить ресурсы.
Бенчмаркирование на разных платформах
Для сравнения производительности агентов важно тестировать их в разных окружениях: Linux‑сервер, macOS‑рабочая станция, Windows‑VM и даже в Docker‑контейнере. Это помогает выявить узкие места, связанные с драйверами, библиотеками или ограничениями контейнера.
1. Подготовка benchmark‑скрипта
python# bench.py
import time, psutil, os
from claude_code import ClaudeAgent
def run_test(model, platform):
agent = ClaudeAgent(model=model)
start = time.time()
# имитация тяжёлой задачи
for i in range(1000):
agent.generate("def foo(x): return x * 2")
elapsed = time.time() - start
mem = psutil.Process(os.getpid()).memory_info().rss / 1024**2
print(f"[{platform}] model={model} | time={elapsed:.2f}s | mem={mem:.1f} MiB")
if __name__ == "__main__":
import argparse
p = argparse.ArgumentParser()
p.add_argument("--platform", choices=["linux","mac","win"], required=True)
p.add_argument("--model", choices=["claude-3-sonnet","claude-3-opus"], required=True)
args = p.parse_args()
run_test(args.model, args.platform)
2. Запуск в разных средах
Linux (bare‑metal)
bashpython bench.py --platform linux --model claude-3-sonnet
macOS (локальная машина)
bashpython bench.py --platform mac --model claude-3-opus
Windows (PowerShell)
powershellpython bench.py --platform win --model claude-3-sonnet
Docker‑контейнер (изолированная среда)
bashdocker run --rm -v $(pwd):/work -w /work python:3.11-slim \
bash -c "pip install claude-code && python bench.py --platform docker --model claude-3-opus"
Важно: Docker‑тест полезен для проверки, не «вытекает» ли агент за пределы контейнера (например, через сетевые сокеты). Если в логах появляется
Network is unreachable, значит, нужно добавить--network=hostили ограничить доступ к сети.
3. Пример результата
[linux] model=claude-3-sonnet | time=12.34s | mem=850.2 MiB
[mac] model=claude-3-opus | time=9.87s | mem=1024.5 MiB
[win] model=claude-3-sonnet | time=13.01s | mem=950.0 MiB
[docker] model=claude-3-opus | time=15.42s | mem=1100.3 MiB
Разница в времени и потреблении памяти часто объясняется:
- ОС‑политиками (cgroups, ультра‑передача ресурсов).
- Версией библиотеки
torch/transformers, установленной в контейнере. - Наличием GPU – в Docker‑контейнере без
--gpus allагент работает только на CPU, что замедляет вывод.
4. Что делать с результатами
- Если время > 15 s – уменьшите
max-tokensили переключитесь на более лёгкую модель (claude-3-sonnet). - Если память > 1 GB – проверьте, не включена ли отладочная трассировка, и ограничьте
--max-context. - Если бенчмарк в Docker сильно медленнее – добавьте
--privilegedи--cap-add=SYS_RESOURCEдля доступа к ускоренному CPU‑скейлу, либо используйте--device /dev/kvmдля ускорения.
affaan-m/ECC: Agent Harness Performance Optimization – в этой статье подробно описаны методики измерения latency и throughput для различных агентов, включая Claude Code. Рекомендую ознакомиться с таблицей «Платформы vs. Время отклика», чтобы подобрать оптимальный набор параметров под ваш инфраструктурный профиль.
Часто задаваемые вопросы
Как правильно задавать ограничения ресурсов для разных навыков agent‑harness?
Ограничения задаются в конфигурационном файле agent-harness.yaml (или через параметры nice/cgroup при запуске). Для каждого навыка указываются значения cpu, memory_mb и timeout_sec, учитывая характер нагрузки: генерация кода требует меньше памяти, но более длительного времени, тогда как сканирование уязвимостей нагружает CPU и память. Пример конфигурации показывает, что code_gen получает 0.5 CPU и 512 МБ RAM, а security_scan — 1.0 CPU и 1 ГБ RAM. Такие ограничения позволяют избежать OOM‑сбоев и контролировать стоимость инфраструктуры.
Что делать, если агент падает с OOM‑ошибкой?
Сначала проверьте текущие лимиты, указанные в конфигурации, и сравните их с реальным потреблением, которое можно увидеть в docker stats или systemd-cgtop. При необходимости уменьшите memory_mb или cpu для данного навыка, либо распределите нагрузку, запустив несколько независимых агентов с разными навыками. Добавьте в конфиг более строгий timeout_sec, чтобы процесс завершился раньше, чем потребит всё доступное память. После корректировки перезапустите агент и убедитесь, что ошибка исчезла.
Как определить оптимальное количество повторных попыток при низкой уверенности модели?
Определяйте уровень уверенности на основе метрик, возвращаемых агентом (например, confidence_score), и задавайте количество попыток в параметре retries. Если уверенность ниже порога (например, < 0.6), рекомендуется выполнить 3‑4 попытки с небольшим задержкой между ними, а затем переключиться на резервный путь (например, использовать другой skill). При превышении порога в 0.8 – 0.9 достаточно одной попытки, чтобы сэкономить ресурсы. Это балансирует надёжность результата и эффективность выполнения.
Как обеспечить безопасность выполнения agent‑hárнс в production‑окружении?
Запускайте агент в изолированных контейнерах с ограниченными привилегиями (--security-opt no-new-privileges, --cap-drop ALL) и применяйте cgroup‑лимиты, как описано выше. Перед выполнением проверяйте, что контейнер не имеет доступа к sensitive‑mounts (например, /proc или /sys) и что его пользователь имеет минимальные права (не root). Кроме того, включайте аудит логов (auditd) и мониторьте события execve и ptrace для быстрого обнаружения подозрительных действий. Такой подход минимизирует риск эксплуатации уязвимостей изнутри самого агента.