# 16. Бенчмарки и контроль качества

🔵 `agent_bench` прогоняет агентов по сценариям end-to-end и пишет отчёт — так
качество агентов проверяется автоматически, а не «на глаз».

---

## 16.1 Запуск

```bash
# против работающего сервера
agent_bench --url=https://HOST --max=5

# поднять собственный локальный сервер (нужен DEEPSEEK_API_KEY в .env)
agent_bench --port=3001 --max=3

# конкретный агент
agent_bench --url=https://HOST --agent=drom --max=5 --parallel=3

# сценарии по имени (подстрока / regex)
agent_bench --url=https://HOST --name="Camry|BMW" --max=10
```

Флаги: `--url=`, `--port=` (3001), `--agent=`, `--name=`, `--max=`, `--parallel=`
(4), `--timeout=` (90).

Результат — `bench_report_<timestamp>.json` в рабочей папке, со счётчиками
`passed`/`failed` и per-turn `failures`.

## 16.2 Формат сценария

Сценарии в `config/agents/<agent>/bench/scenarios.yaml`:

```yaml
name: "Drom Agent"
model: "drom-agent"

scenarios:
  - name: "Поиск Camry"
    turns:
      - user: "Найди Toyota Camry"
        assert:
          contains: [camry]
          min_links: 2
          valid_urls: true
```

### Многоходовые сценарии

```yaml
  - name: "Multi-turn: уточнение"
    turns:
      - user: "Первый вопрос"
        assert: { contains: [Слово], min_links: 2 }
      - user: "Уточнение"
        assert: { min_links: 1 }
      - user: "Финальное уточнение"
        assert: { valid_urls: true }
```

### Типы проверок

| Проверка | Смысл |
|---|---|
| `contains: [w1, w2]` | ответ должен содержать подстроки (без учёта регистра) |
| `min_links: N` | минимум N markdown-ссылок `[text](url)` |
| `min_urls: N` | то же, что `min_links` (считает URL внутри markdown) |
| `valid_urls: true` | все ссылки начинаются с http:// или https:// |

## 16.3 Анализ результата

1. Смотри консоль: `✓` (pass) / `✗` (fail).
2. Читай `bench_report_*.json`: поля `failures` и `error`.
3. Сравни два отчёта (diff) для поиска регрессий.

## 16.4 Хранилище запусков

Запуски пишутся в `logs/bench.db` и видны в админ-API:

| Endpoint | Описание |
|---|---|
| `POST /v1/agents/:name/bench/run` | запустить бенчмарк шаблона (`{timeout_secs}`) |
| `GET /v1/agents/:name/bench/runs` | история запусков шаблона |
| `GET /v1/agents/:name/bench/runs/:id` | один запуск + его ходы |

## 16.5 Практики

- Каждый сценарий фокусируется на **одном** фильтре/потоке.
- Запросы на русском (drom/hg/ngu), английском (rss).
- Многоходовые сценарии проверяют сохранение контекста между ходами.
- Тяжёлые сценарии — комбинированные фильтры и крайние случаи.
- `min_links: 1` для крайних случаев (редкие бренды, узкие фильтры).
- Всегда `valid_urls: true` — ловит сломанное форматирование ссылок.
