Обновление контрольных точек рабочего процесса Python до версии 1.13.0

Agent Framework 1.13.0 содержит незначительные критические изменения в Python выполнении рабочего процесса. Большинство приложений не требуют изменений. Изменения затрагивают приложения, которые зависят от точного количества супершагов или номеров итераций, устанавливают max_iterations на границе сходимости, проверяют идентификатор источника исходного сообщения или делают предположения о размещении и порядке контрольных точек.

Предыстория

До версии 1.13.0 механизм создания контрольных точек не в полной мере выполнял своё обещание сохранять состояние рабочего процесса, необходимое для возобновления выполнения из любой зафиксированной точки. Начальный исполнитель выполнялся до цикла супершагов и создания контрольных точек, поэтому самая ранняя контрольная точка содержала результат работы начального исполнителя и обновлённое состояние, но не исходные входные данные процесса. Аналогичным образом, ответы на события запроса доставлялись и обрабатывались без предварительной записи в контрольной точке. В результате ни одна точка сохранения не смогла ни воспроизвести исполнитель запуска по исходным входным данным, ни воссоздать продолжение с участием человека на основе выданного ответа.

Изменения в поведении

Версия 1.13.0 закрывает эти пробелы. Начальный исполнитель теперь выполняется на первом супершаге, контрольная точка входа записывает исходные входные данные перед этим супершагом, а контрольная точка входа ответа записывает доставленные ответы до их обработки. Вместе эти изменения позволяют полностью воспроизвести рабочий процесс с контрольными точками по его входным данным, включая продолжения с участием человека.

Important

Эти изменения не влияют на контрольные точки, созданные до версии 1.13.0. Существующие контрольные точки остаются поддерживаемыми и по-прежнему могут быть восстановлены после обновления.

Изменения, которые могут потребовать действия

Area	До 1.13.0	В версии 1.13.0 и более поздних версий	Влияние на пользователей
Запуск исполнителя	Исполнитель запуска выполнялся до цикла супершага.	Входные данные помещаются в очередь для начального исполнителя, который запускается на первом супершаге.	Каждый новый запуск генерирует по одному дополнительному событию superstep_started и superstep_completed.
Число итераций	Итерация 1 обозначала первый суперстеп после выполнения start executor.	Итерация 1 запускает начальный исполнитель. Последующие рабочие смены сдвигаются на одну итерацию.	Рабочий процесс, который ранее требовал $N$ итерации, теперь требуется $N + 1$.
Источник входного сообщения	Первоначальное сообщение имело жестко заданный идентификатор источника "Workflow".	Начальное сообщение доставляется через внутреннее ребро исполнителя запуска и имеет идентификатор источника INTERNAL_SOURCE_ID(start_executor.id).	Код, который считывает или фильтрует исходный идентификатор источника сообщения, должен использовать новое значение.

Улучшения реиграбельности

Area	До 1.13.0	В версии 1.13.0 и более поздних версий	Улучшение
Начальная контрольная точка	Контрольная точка итерации 0 была создана после выполнения start executor. Он захватывал выходные сообщения исполнителя и обновлял состояние, но не исходные входные данные.	Контрольная точка входа создается перед superstep 1. Он сохраняет исходные данные, поставленные в очередь для исполнителя запуска.	Восстановление контрольной точки записи воспроизводит полный запуск, включая исполнителя запуска.
Контрольная точка ответа	Ответ на событие запроса был доставлен без записи в контрольной точке.	Контрольная точка получения ответа создается после получения ответа и перед выполнением супершага, который его обрабатывает.	Восстановление контрольной точки получения ответа повторно воспроизводит продолжение, которое обрабатывает ответ.

Обновление обработки событий superstep

Теперь новый рабочий процесс создает еще одну пару событий суперстепа, так как начальный исполнитель выполняется в superstep 1:

• superstep_started с iteration == 1
• superstep_completed с iteration == 1

Последующая работа исполнителя сдвигается на один суперстеп. Обновление тестов, телеметрии, индикаторов хода выполнения или другого кода, предполагающих точное число событий или сопоставление определенного исполнителя с фиксированной итерацией.

Код, реагирующий на типы событий без учета их количества или итерации, не требует изменения.

Проверьте максимальное ограничение итерации

Ограничение max_iterations теперь также включает супершаг, в котором выполняется исполнитель запуска. Если рабочий процесс ранее использовал его полный предел, увеличьте настроенное значение на один:

from agent_framework import WorkflowBuilder

workflow = WorkflowBuilder(
    start_executor=start_executor,
    max_iterations=previous_max_iterations + 1,
).build()

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

Обновление проверок источника исходного сообщения

Если стартовый исполнитель использует идентификатор источника начального сообщения, замените жёстко заданное значение "Workflow" на идентификатор источника для внутреннего ребра стартового исполнителя.

До 1.13.0:

is_workflow_input = ctx.source_executor_ids != ["Workflow"]

В версии 1.13.0 и более поздних версий:

from agent_framework import INTERNAL_SOURCE_ID

is_workflow_input = ctx.source_executor_ids != [INTERNAL_SOURCE_ID(self.id)]

INTERNAL_SOURCE_ID(executor_id) в настоящее время возвращает "internal:<executor_id>". Используйте вспомогательный элемент вместо создания этой строки, чтобы код следует формату исходного идентификатора платформы.

Обновление обработки контрольных точек

Начальные входные контрольные точки

Когда включено создание контрольных точек, каждый новый запуск теперь создаёт начальную контрольную точку в iteration_count == 0. Эта точка сохранения содержит исходные данные в виде сообщения в процессе обработки, адресованного исполнителю запуска. При восстановлении этого объекта повторно запускается исполнитель запуска и полностью воспроизводится выполнение рабочего процесса.

После каждого завершённого супершагa фреймворк продолжает создавать контрольную точку сохранения. При выполнении с $N$ суперстепами следует ожидать $N + 1$ контрольных точек: начальную контрольную точку, за которой следует по одной контрольной точке для каждого завершенного суперстепа.

Проверьте код, предполагающий, что контрольная точка итерации-0 содержит состояние, созданное начальным исполнителем. Это состояние теперь отображается в контрольной точке, созданной после superstep 1.

Контрольные точки запроса-ответа

Когда вы продолжаете рабочий процесс с помощью workflow.run(responses=...), фреймворк теперь создает контрольную точку записи ответа после постановки ответов в очередь и перед выполнением супершага, который их обрабатывает. Восстановление этой контрольной точки повторно предоставляет записанные ответы и воспроизводит остальную часть рабочего процесса.

Контрольная точка ввода ответа совпадает iteration_count с предыдущей контрольной точкой, содержащей ожидающий запрос. Это отдельная контрольная точка, previous_checkpoint_id которая указывает на контрольную точку ожидающего запроса.

Important

iteration_count не гарантированно является уникальным в истории контрольных точек с участием человека. Проследите цепочку previous_checkpoint_id, чтобы определить порядок контрольных точек. Если вам нужна последняя контрольная точка, используйте API хранилища контрольных точек вместо выбора самого большого iteration_count.

Контрольный список миграции

• Обновите проверки и обработчики событий, которые зависят от точного количества супершагов или номера итерации.
• Увеличьте max_iterations на единицу только для процессов, достигших предыдущего предела.
• Замените первоначальные проверки идентификатора источника для "Workflow" на INTERNAL_SOURCE_ID(start_executor.id).
• Считайте контрольную точку iteration-0 входной контрольной точкой перед выполнением.
• Упорядочивайте контрольные точки с участием человека по цепочке происхождения, а не считайте, что iteration_count является уникальным.
• Убедитесь, что повторное воспроизведение контрольной точки входа и контрольной точки входа ответа приводит к ожидаемым выходным данным и побочным эффектам.

Подробные сведения о реализации см. в разделе Разрешить полное воспроизведение контрольных точек рабочего процесса.