Установка recorder для запросов ИИ-агента

Ответ возвращается тем же путём и тоже записывается. Для агента recorder невидим, для вас — источник правды о том, что происходило в сессии.

Схема работы выглядит так.

запрос:  агент  →  recorder  →  модель
ответ:   агент  ←  recorder  ←  модель

Recorder ничего не меняет в запросах: он только копирует их и пересылает дальше. Именно поэтому его безопасно держать включённым постоянно — он не влияет на поведение агента и модели, а лишь оставляет след.

Но большинство важных вопросов касается того, что внутри: насколько заполнен контекст, какие файлы попали в запрос, почему агент повёл себя так, а не иначе. Без записи на эти вопросы можно отвечать только догадками.

1. Расход контекста — видно, как сессия заполняет окно контекста и когда пора начинать новую.
2. Стоимость — по числу токенов в запросах легко оценить, сколько тратится на каждую задачу.
3. Отладка — если агент сделал что-то странное, в записи видно, какая информация привела его к этому решению.
4. Обучение — разбор записей показывает, как устроен «ход мысли» агента и как формулировать более точные промпты.

Recorder — обязательный элемент курса ещё и потому, что следующие уроки постоянно обращаются к понятию контекста. Без инструмента, который показывает контекст «в цифрах», эти уроки останутся абстракцией.

Recorder сохраняет весь пакет целиком, поэтому по одной записи можно восстановить, что именно видел агент в этот момент.

1. Системный промпт — инструкции, которые агент держит в начале каждого запроса.
2. История сессии — предыдущие сообщения и ответы, формирующие контекст.
3. Новое сообщение — последний запрос или действие агента.
4. Результаты инструментов — вывод команд, содержимое прочитанных файлов, результаты тестов.
5. Ответ модели — текст, который агент получил и использовал для следующего шага.

Журнал хранится в формате JSONL: каждая строка файла — это один запрос в виде JSON-объекта. Формат удобен и для чтения глазами, и для обработки программами, о чём поговорим в разделе про чтение записей.

Recorder устанавливается как обычная программа. В экосистеме Node.js удобнее всего поставить его глобально через npm, чтобы запускать из любого проекта.

npm install -g имя-пакета-recorder

Проверка установки

Сразу после установки проверьте, что программа видна в терминале, — командой вывода версии.

recorder --version

Если команда не найдена, действуйте как в уроке про установку агента: перезапустите терминал или добавьте каталог установки в переменную окружения PATH.

Чтобы агент начал отправлять запросы через recorder, нужно направить его на адрес recorder вместо адреса провайдера. У большинства harness-ов для этого есть настройка — обычно переменная окружения с базовым адресом API.

Запуск recorder

Сначала запустим recorder на отдельном порту. Точная команда зависит от конкретной программы, но схема одинакова: указать порт и файл журнала.

recorder --port 9090 --log requests.log

Recorder запущен и ждёт запросы. Оставьте его работать в этом терминале.

Настройка агента

Теперь укажем агенту адрес recorder вместо адреса модели. Имя переменной зависит от вашего harness, но смысл один: все запросы пойдут через http://localhost:9090.

export AGENT_BASE_URL=http://localhost:9090

Готово: запрос агента сначала попадёт в recorder, тот сохранит копию в requests.log и перешлёт запрос настоящей модели. Ответ вернётся по тому же пути и тоже будет записан.

После настройки сделайте проверочный запрос агенту — например, попросите описать структуру проекта, как в уроке про установку агента. Затем посмотрите, что записалось в журнал.

wc -l requests.log

Если в журнале появились строки — recorder работает: каждая строка это один запрос к модели. Теперь посмотрим на содержимое первой записи.

head -1 requests.log

Вывод будет длинным и «сырым», но это нормально. Ключевое — наличие данных: значит, путь агент → recorder → модель работает, и можно переходить к чтению записей.

Сырой JSON читать глазами неудобно, поэтому для разбора записей используем инструменты. jq — утилита для работы с JSON, которая есть почти во всех системах. С её помощью можно извлечь из каждой строки нужные поля и представить их в виде таблицы.

jq -r "[.timestamp, .model, .usage.prompt_tokens, .usage.completion_tokens] | @tsv" requests.log

Типичная запись содержит несколько важных полей.

Число токенов на входе — это и есть расход контекста. Рост prompt_tokens от строки к строке показывает, как сессия постепенно заполняет окно контекста.

Сложите prompt_tokens по всем строкам журнала — получите, сколько токенов «съела» задача. Сравните с размером окна модели: если сумма приближается к пределу, пора завершать сессию и начинать новую.

jq -s "map(.usage.prompt_tokens) | add" requests.log

Проверяйте расход после каждого упражнения: одна команда — и видно, насколько «тяжёлой» была сессия. Со временем вы научитесь предсказывать расход по типу задачи ещё до её начала: простая правка файла — это немного токенов, а исследование кодовой базы — заметно больше.

Стоимость считается похожим образом: умножьте число токенов на цену модели. Многие recorder-ы считают её автоматически и кладут в поле cost — достаточно посмотреть на сумму по журналу.

Шаги простые. Найдите строку журнала, соответствующую моменту странного поведения, посмотрите системный промпт и историю сессии, найдите источник «грязи» в контексте. Чаще всего причина видна сразу: лишний вывод команды, огромный файл, случайно попавший в контекст, или устаревшая инструкция из прошлой задачи.

1. Найти запись по времени или по номеру шага.
2. Просмотреть, какие файлы и выводы попали в запрос.
3. Определить, что из этого мешало агенту.
4. Исправить источник проблемы: удалить файл из контекста, очистить историю, уточнить инструкцию.

Такой разбор — основа дисциплины управления контекстом, которой посвящена большая часть курса. Recorder даёт факты, а не догадки.

Установку и настройку recorder — задачу с известными шагами и проверяемым результатом — можно поручить агенту. Запрос строится по уже знакомому шаблону: задача, ограничения, критерий приёмки.

1. Установи recorder глобально и подключи к проекту.
2. Запусти на порту 9090, журнал requests.log в корне проекта.
3. Укажи агенту адрес http://localhost:9090 через AGENT_BASE_URL.
4. Критерий приёмки: после проверочного запроса в requests.log появилась хотя бы одна строка с полями model и usage.

Обратите внимание на критерий приёмки: он проверяет не «recorder установлен», а факт записи реального запроса. Именно такой критерий доказывает, что весь путь настроен, а не только программа поставлена.

1. Recorder не запущен, а агент настроен на его адрес — запросы падают с ошибкой соединения.
2. Агенту не указан адрес recorder — журнал остаётся пустым, и кажется, что recorder не работает.
3. Чтение журнала целиком глазами вместо выборочного извлечения полей jq.
4. Игнорирование расхода токенов — сессия незаметно упирается в окно контекста.
5. Журнал, закоммиченный в репозиторий, — записи содержат внутренние данные проекта и разрастаются.
6. Остановка recorder посреди работы — агент теряет связь с моделью.

Самая коварная ошибка — журнал в репозитории. Файл растёт с каждой сессией и загрязняет историю git. Добавьте requests.log в .gitignore сразу при настройке — так же, как вы уже сделали с файлом базы данных в уроке про сброс проекта.

Recorder установлен и подключён: теперь каждый запрос между агентом и моделью записывается в журнал, и вы видите расход контекста, токены и стоимость задачи. Записи стали инструментом отладки — по ним видно, какая информация попадала в контекст и почему агент вёл себя так или иначе.

В следующем уроке разграничим понятия модели, harness, агента и среды — выстроим чёткую терминологию, на которой будут держаться все дальнейшие уроки курса.

1. Recorder — инструмент записи запросов между агентом и моделью.
2. JSONL — формат журнала, в котором каждая строка — один JSON-объект.
3. Системный промпт — инструкции, которые агент отправляет модели в начале каждого запроса.
4. История сессии — предыдущие сообщения и ответы, формирующие контекст.
5. Токен — единица текста, которой модель считает вход и выход.
6. prompt_tokens — число токенов, ушедших на вход запроса.
7. completion_tokens — число токенов, возвращённых моделью в ответе.
8. Расход контекста — объём окна контекста, занятый сессией.
9. Окно контекста — максимальный объём текста, который модель обрабатывает за один раз.
10. jq — утилита командной строки для обработки JSON.
11. Прокси — программа-посредник между агентом и моделью.
12. Промпт — запрос пользователя или агента к модели.
13. Критерий приёмки — условие, по которому задача считается выполненной.
14. PATH — список каталогов, где система ищет исполняемые файлы.