Stately Agent: зачем агентному сценарию собственная история событий

Отладка агента часто начинается с неприятного вопроса: почему два запуска, которые выглядели одинаково, вернули разные действия? В версии 2.0.0-alpha.32 проекта Stately Agent авторы добавили более явную семантику для ответвлений истории: новый fork получает собственный executionId и отметку о родительском запуске и позиции, откуда он ответвился. Это точечное изменение, но оно закрывает реальную ловушку кэширования: если ветка сохраняет идентификатор родителя, одинаковый ключ вызова может ошибочно вернуть результат из другого сценария.

Что за инструмент рассматриваем

Stately Agent — библиотека для сценариев, где важно описывать ход выполнения и его состояния, а не только отправлять длинный промпт модели. Для агента это означает, что вызовы инструментов, результаты и ответвления могут стать проверяемой историей. В последнем предварительном релизе также изменили требования к пользовательскому хранилищу веток и усилили тест на соответствие интерфейсу event log. Это не означает, что библиотека автоматически даст приложению аудит, безопасность или устойчивость: качество интеграции по-прежнему зависит от кода, хранения и ограничений инструментов.

Почему fork должен иметь собственную идентичность

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

Отдельный ID запуска плюс ссылка на родителя помогают отличить историю исходного сценария от эксперимента. Это похоже не на «умную память» модели, а на дисциплину версионирования: каждая ветка объясняет, откуда началась, до какого события она дошла и что изменилось дальше. Сопоставьте этот подход с журналом действий, который нужен для расследования сбоя: библиотечный event log упрощает работу с ветками, но прикладная команда всё равно должна решить, какие поля хранить и как защищать данные.

Как оценить на малом прототипе

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

Важно проверить контракт собственного store. Если приложение хранит ветки в базе, метод fork должен сохранять возвращённый префикс и новый init-событие, а не только копировать старые записи. Прогоните тест на совпадение ключей, на пустой истории и на ошибку записи. Подумайте, можно ли переиграть события в том же порядке после обновления библиотеки. Если обработчики зависят от внешней системы, тестируйте их с заглушкой и не подключайте реальные права до завершения эксперимента.

Ограничения alpha

Предварительная версия — не обещание стабильного API. Перед внедрением нужно оценить лицензирование, частоту изменений, поддержку, формат миграции и совместимость с вашей версией хранилища. Функция fork решает конкретную проблему истории, но не исправляет ошибочные права доступа, плохую идемпотентность или повторную отправку внешнего действия. В проекте, где агент может менять состояние вне приложения, тестовая ветка должна быть изолирована от реальных инструментов.

Кроме того, журнал событий не равен полной воспроизводимости. Модель может давать разные ответы, сторонний API меняется, а порядок событий в очереди влияет на результат. Для повторного запуска сохраняйте версии конфигурации и безопасные ссылки на входные данные; секреты и полные закрытые документы в тестовые логи не копируйте. Иначе отладочный инструмент станет источником утечки.

Кому стоит попробовать

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

FAQ

Это релиз стабильной версии? Нет, версия обозначена как alpha, поэтому API и поведение могут измениться.

Исправляет ли fork ошибки самого агента? Нет. Он помогает отличать ветки и историю выполнения, но логика принятия решения остаётся в приложении.

Нужно ли включать кэш в первый тест? Полезно проверить оба режима: без кэша вы проверите базовую ветку, с кэшем — не смешиваются ли результаты разных исполнений.

Что проверить перед внедрением

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

В небольшой команде полезно заранее договориться, какая ветка считается исходной и кто имеет право объединять её изменения. Если это не определить, технически раздельные истории всё равно превратятся в организационную путаницу. Не храните в журнале секреты и необработанные пользовательские данные только потому, что инструмент умеет сохранять состояние. Для каждого поля укажите цель, срок хранения и способ удаления. Поскольку версия помечена alpha, оберните интеграцию небольшим адаптером, чтобы смена API не затронула бизнес-логику.