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

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

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`
`feedback`	лайки/дизлайки по шаблону/юзеру/сессии/значению	`group_by`, `value`, `template`, `user_id`, `session_id`, `days`
`escalations`	воронка эскалаций: сколько ушло оператору (requested/resolved), по причинам и каналам	`days`, `limit`
`blind_spots`	«слепые зоны»: инструменты, что часто возвращают warning (пустой поиск) или падают, по инструментам	`days`, `limit`

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

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

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

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

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

agent-os tool <tool.yaml> '<json_args>'
agent-os office <tool.yaml> '<json_args>'        # с автозагрузкой officecli

Выводит: аргументы, call_template (что видит пользователь до), вывод для LLM, result_template (что видит после). agent-os tool поддерживает все kind: — site_tool, browser_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, sql_tool, shell_tool, file_tool, office_tool, vk_tool, ym_tool. Отдельная команда agent-os office — тонкая обёртка для офисного kind: office_tool: при первом запуске скачивает officecli и печатает блок file результата.