AgentLab: эксперименты с архитектурой tool-calling агента

Исследовательский стенд: базовый агентный цикл с MCP-инструментами (original/), 15 экспериментальных доработок (improvements/) и бенчмарк для их сравнения (benchmark/).

Результаты коротко

suite_balanced: 40 сценариев (89 ходов), из них 4 с тегом critical и 11 в домене safety. Каждый вариант прогнан один раз в паре с baseline.

Вариант	SR	CSR (из 4)	Safety (из 11)	Latency
Baseline (original), 11 прогонов	67.5–75.0%	50–75%	81.8–90.9%	1.58–1.99s
07 Active Compression	80.0%	75%	100%	1.81s
09 Context Engineering	77.5%	75%	100%	1.53s
12 Multi-Agent Validation	77.5%	100%	100%	1.79s
14 Graph-RAG	77.5%	100%	90.9%	1.69s
02 Tool Validation	75.0%	100%	90.9%	2.01s
05 Deterministic Routing	75.0%	75%	100%	1.62s
15 Memory Formation	75.0%	100%	100%	1.63s
08 Semantic Selection (2 прогона)	70.0 / 72.5%	75%	90.9 / 100%	1.76–2.28s
13 Buddy System	67.5%	100%	100%	1.78s

Как читать. Один сценарий в SR = 2.5 п.п., один critical-сценарий в CSR = 25 п.п., один safety-сценарий = 9 п.п. Baseline, перезапущенный 11 раз на том же наборе, дал SR от 67.5% до 75.0% (среднее 72.5%, σ ≈ 2.2 п.п.) и CSR от 50% до 75%. Значит, разница в несколько п.п. по SR между вариантами укладывается в шум, а повторов для самих вариантов нет. Устойчивее выглядят только сдвиги в safety (у большинства вариантов 10–11 из 11 против 9 из 11 у baseline почти во всех прогонах) и в токенах (05 и 08 тратят примерно на 22–27% меньше токенов, чем baseline в том же прогоне).

Сводка scorecard по всем прогонам: benchmark/results/balanced_summary.json; markdown-отчёты прогонов лежат рядом. Сырые JSON с транскриптами в репозиторий не кладутся.

Состав репозитория:

1. Базовый пайплайн (original/): агентный цикл LLM → Tool Executor → LLM с интеграцией MCP.
2. Эксперименты (improvements/): доработки базового пайплайна (валидация аргументов, детерминированная маршрутизация, сжатие контекста, графовый RAG, мультиагентная проверка и др.).
3. Бенчмарк (benchmark/): мок-серверы MCP, сценарии, метрики, LLM-as-a-Judge.

Структура

AgentLab/
├── benchmark/           # общий бенчмарк (сценарии, mock MCP, метрики, отчёты)
├── config.benchmark.yml # конфиг LLM/MCP для прогонов бенчмарка
├── tests/               # unit-тесты бенчмарка
├── requirements.txt
├── original/            # стандартный эталонный пайплайн агента (baseline)
│   ├── agent_core.py
│   ├── prompts/
│   └── ...
└── improvements/        # исследовательские эксперименты и архитектурные улучшения
    ├── 02-tool-validation-layer/
    ├── 05-deterministic-routing/
    ├── 07-focus-active-compression/
    ├── ...
    └── 17-hierarchical-context-tree/

Бенчмарк (из корня репозитория)

Каталог: ~500+ ходов, 4 MCP-сервера, ~25 инструментов (core, hr, crm, sse).

source original/.venv/bin/activate
pip install -r requirements.txt

# перегенерация каталога (опционально)
PYTHONPATH=. python -m benchmark.generate_catalog --turns 500

# терминал 1 — mock MCP (все 4 mount на :19100)
python -m benchmark.mcp_mock_server

# терминал 2 — полный прогон
PYTHONPATH=. python -m benchmark.compare --variant original

# быстрый smoke (~5 сценариев с тегом smoke + critical)
PYTHONPATH=. python -m benchmark.compare --variant original --tags smoke

# эталонный стандартный пайплайн
PYTHONPATH=. python -m benchmark.compare --variant original

# экспериментальный вариант
PYTHONPATH=. python -m benchmark.compare --variant improvements/05-deterministic-routing/variant

# сравнительный анализ двух вариантов
PYTHONPATH=. python -m benchmark.compare --variant original --variant improvements/05-deterministic-routing/variant --metrics comparative

CLI агента (внутри варианта)

cd original
source .venv/bin/activate
python basic_agent.py -i

Добавление нового эксперимента

cp -r original improvements/my-experiment/variant
# правки в improvements/my-experiment/variant/, затем:
PYTHONPATH=. python -m benchmark.compare --variant improvements/my-experiment/variant

---

Анализ экспериментов

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

1. Tool Calling & Routing: надёжность вызова инструментов, предобработка аргументов, маршрутизация.
2. Context & Memory Management: длинный контекст, сохранение фактов между сессиями, индексация.
3. Knowledge & Graph-RAG: графовые структуры знаний, валидация сущностей, галлюцинации в структурированных данных.
4. Multi-Agent & Guardrails: мультиагентная проверка, двухуровневые фильтры (Tier-1/Tier-2).

Таблица suite_balanced с привязкой к прогонам

40 сценариев, 89 ходов, домены Tools, Safety, Memory, Graph; оценка ответов через LLM-as-a-Judge (Qwen 35B). В каждом прогоне baseline и вариант идут на одном наборе; ниже указан baseline того же прогона.

Вариант	Суть	SR	CSR	Safety	Latency	Baseline SR в том же прогоне	Прогон
02 Tool Validation	Приведение типов (_coerce_type), алиасы, очистка формул	75.0%	100%	90.9%	2.01s	75.0%	20260904_160711
05 Deterministic Routing	Fast-path маршрутизация инструментов	75.0%	75%	100%	1.62s	72.5%	20260904_172135
07 Active Compression	Knowledge Index + сохранение критичных маркеров	80.0%	75%	100%	1.81s	75.0%	20260904_175033
08 Semantic Selection	Ключевые слова + эмбеддинги внутри доменов	70.0%	75%	90.9%	2.28s	72.5%	20260904_153612
08 Semantic Selection	(повтор)	72.5%	75%	100%	1.76s	72.5%	20260904_172833
09 Context Engineering	Изоляция блоков сообщений + сохранение tool-adjacency	77.5%	75%	100%	1.53s	67.5%	20260904_174347
12 Multi-Agent Validation	Tier-1 символический фильтр + Tier-2 LLM-валидатор	77.5%	100%	100%	1.79s	72.5%	20260906_181852
13 Buddy System	Buddy-инспектор ответов	67.5%	100%	100%	1.78s	72.5%	20260906_181144
14 Graph-RAG	Графовый фильтр сущностей	77.5%	100%	90.9%	1.69s	72.5%	20260906_180456
15 Memory Formation	SQLite-память, детерминированные эмбеддинги	75.0%	100%	100%	1.63s	75.0%	20260904_173558

Прогоны 20260904_175441 (вариант 14 не запустился) и 20260904_183857 (обрыв на ~20% ходов у обоих бэкендов) в таблицу не включены.

Более ранний прогон на полном каталоге (176 сценариев, 499 ходов, одна итерация на вариант) описан в improvement_reports/SUMMARY.md; там большинство доработок v1 проигрывали baseline, после чего они были переделаны.

---

Детальный анализ ключевых решений

1. Валидация и нормализация инструментов (02-tool-validation-layer)

• Проблема v1: жёсткая валидация по JSON Schema отвергала корректные вызовы с числовыми строками ("42" вместо 42) или формулами с пробелами (" 2 + 2 "). На полном каталоге SR v1 был 14% против 26% у baseline.
• Реализация v2: мягкое приведение типов (_coerce_type), нормализация параметров и очистка строковых выражений перед исполнением.
• Итог на suite_balanced: SR 75% (на уровне baseline), CSR 4/4, но латентность выше (2.01s) и токенов на ~9% больше.

2. Детерминированная маршрутизация инструментов (05-deterministic-routing)

• Проблема v1: роутер исключал системные инструменты (graph_query) из кандидатов и не распознавал реплики с отсылкой к истории («в прошлом ответе», «там были»).
• Реализация v2: список обязательных CORE_TOOLS, расширенный словарь синонимов доменов (HR, CRM), подсказка NO_TOOLS_HINT для вопросов, на которые надо отвечать из памяти.
• Итог: safety 11/11, примерно на 22% меньше токенов за счёт отсечения нерелевантных схем, SR в пределах шума baseline.

3. Управление контекстом и индексы (07-focus, 09-context, 15-memory)

• Контекстная инженерия (09): исправлено нарушение контракта OpenAI/vLLM API: разбиение сообщений на блоки разрывало связку assistant.tool_calls и tool_message. С сохранённым adjacency: CAS 82.0, латентность 1.53s.
• Knowledge Index (07): вместо слепого сжатия истории используется структурированный индекс знаний с защищёнными маркерами ([PRESERVED_MARKERS]). Самый высокий SR в этом наборе (80%), но это +2 сценария к baseline за один прогон и примерно на 28% больше токенов.
• Долговременная память (15): недетерминизм hash() между процессами Python заменён на SHA-256 bucket-индексацию. Факты хранятся в SQLite с UNIQUE(user_id, fact_key) и поднимаются в повторных сессиях.

4. Безопасность и мультиагентная валидация (12-multi-agent, 13-buddy, 14-graph-rag)

• Двухуровневый гейтинг (Tier-1 / Tier-2): безусловный вызов LLM-валидатора на каждом ходе давал задержку больше 5.6s. Tier-1 (детерминированная проверка запрещённых инструментов, приманок и маркеров) срабатывает без обращения к LLM, LLM-валидатор вызывается реже. Задержка 1.78–1.79s, safety 11/11, CSR 4/4.
• Графовый фильтр (14): убраны ложные срабатывания на непрофильных сценариях (CRM, общие знания).

---

Выводы

Выводы предварительные: каждый вариант прогнан один раз, а разброс baseline между прогонами сопоставим с разницей между вариантами. Для уверенных выводов нужны повторные прогоны вариантов и доверительные интервалы.

1. Что выглядит полезным при низкой цене:
   • Нормализация аргументов (02) перед вызовом MCP: убирает класс ошибок из-за типов без дополнительных LLM-запросов.
   • Сохранение tool-adjacency при работе с контекстом (09): это исправление контракта API, а не оптимизация.
   • Tier-1 символические проверки (12): дешёвая проверка критических ограничений на стороне Python.
2. Что стоит проверить повторными прогонами:
   • Детерминированный роутинг (05) и семантический отбор (08): экономия токенов воспроизводится, влияние на качество нет.
   • Knowledge Indexing (07) и SQLite-память (15): нужны отдельные сценарии на длинные сессии.
   • Графовый фильтр (14): имеет смысл при подключении графовых баз знаний.