شرح Habr AI كيفية بناء وكيل إنتاج مع حالة دائمة وخطوات وأحداث

Чтобы AI-агент нормально жил в продакшене, ему недостаточно держать всё в памяти процесса: после рестарта он должен помнить, что именно попросил пользователь, какой план уже был построен, какие инструменты отработали и где выполнение остановилось. В первой части нового практического разбора на Habr AI автор предлагает строить такой durable state вокруг трёх базовых сущностей — хода, шага и события — и показывает, почему без них длинные агентские сценарии быстро превращаются в непрозрачный и хрупкий пайплайн. Отправная точка текста простая: если агент хранит состояние только in-memory, любое падение сервиса обнуляет задачу.

Для демо это терпимо, но production-агент может анализировать документы, ждать подтверждения пользователя и выполнять длинную цепочку действий, поэтому после сбоя ему нужно восстановиться из базы, а не из обрывков промпта. В качестве минимального набора persistent-сущностей автор перечисляет AgentTurn, AgentPlanItem и AgentEvent, а также напоминает, что рядом почти неизбежно появляются ApprovalGrant, SessionContext и BackgroundJob. Идея в том, что durable state описывает не только итоговый ответ, но весь путь к нему: исходный запрос, нормализованную команду, флаги подтверждения, статусы выполнения и возможную ошибку.

AgentTurn в этой схеме — полноценная запись одного пользовательского хода. Она хранит идентификатор сессии и turn_id, текст сообщения, нормализованную команду и статус обработки вроде created, planned, awaiting_approval, running, completed или failed. Важно, что ход фиксирует и финальный output_text, и error, если выполнение сорвалось.

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

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

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

Вместо одного размытого состояния фронтенд может читать turn_started, tool_started, tool_progress, tool_completed, approval_requested, tool_failed и turn_completed, а затем показывать понятный прогресс. Пример из текста выглядит приземлённо и поэтому полезно: агент запускает collect_documents, находит 12 документов, затем на шаге analyze_documents сообщает прогресс 40 из 100, а в случае сбоя пишет timeout внешнего сервиса и помечает ошибку как retryable. Для пользователя это означает нормальный UX вместо бесконечного «агент думает», а для команды разработки — возможность отлаживать пайплайн, проводить аудит, разбирать инциденты и восстанавливать задачи после рестарта без ручной реконструкции истории.

Главный вывод из материала Habr AI в том, что production-агент в 2026 году — это не удачный prompt с обвязкой, а stateful-система с журналом исполнения. Если у агента нет durable state на уровне хода, шага и события, он плохо переживает сбои, непрозрачен для интерфейса и почти не поддаётся поддержке. А значит, следующий этап эволюции агентских приложений лежит не столько в новых моделях, сколько в дисциплине backend-архитектуры: в том, как мы фиксируем состояние, контролируем подтверждения и превращаем работу модели в воспроизводимый операционный процесс.