# 5. Инструменты — наблюдение и отладка

🔵 Read-only запросы к трейсам агентов и локальное тестирование инструментов.
Сводную таблицу всех движков см. в
[«Справочник инструментов»](05-tools-reference.md).

## 5.9 trace_tool

Запросы к трейсам агентов. Read-only запросы к `logs/events.db` и
`logs/process-*.jsonl`. `operation` выбирает запрос:

| operation | Назначение | Ключевые параметры |
|---|---|---|
| `sessions` | список сессий + агрегированная статистика | `limit`, `offset`, `agent`, `only_errors` |
| `events` | таймлайн событий сессии/процесса | `session_id` или `pid`, `event_type`, `search`, `limit` |
| `transcript` | диалог сессии | `session_id`, `search` |
| `search` | полнотекстовый поиск по транскриптам | `query`, `limit` |
| `process` | сырой JSONL-трейс процесса | `pid`, `event_type`, `include_tokens`, `search`, `limit` |

### Видимость и скоупинг

`trace_tool` возвращает только то, что вызывающему разрешено видеть:

| Контекст | Скоуп | Что можно запрашивать |
|---|---|---|
| `admin_templates: "*"` | полный | все сессии / процессы |
| `admin_templates: "a,b"` | ограниченный | только эти шаблоны |
| нет админа, есть `user_id` | пользовательский | только свои сессии / транскрипты / процессы |
| ни того, ни другого | запрет | `access denied` |

Агент конечного пользователя (например Феликс) без админ-токена автоматически
получает **user**-скоуп из `X-User-Id` своей сессии — его поиск видит только
историю текущего пользователя, без утечек между пользователями.

---

## 5.21 Тестирование локально

```bash
site_tool <tool.yaml> '<json_args>'
```

Выводит: аргументы, `call_template` (что видит пользователь до), вывод для LLM,
`result_template` (что видит после). Поддерживает все `kind:` — `site_tool`,
`archive_tool`, `pdf_tool`, `rss_tool`, `json_tool`, `trace_tool`, `script_tool`,
`state_tool`, `geo_tool`, `table_tool`, `chart_tool`, `visualize_tool`,
`subagent_tool`, `email_tool`, `workflow_tool`, `duckdb_tool`, `shell_tool`,
`file_tool`.
