Python 워크플로 검사점을 1.13.0으로 업그레이드

에이전트 프레임워크 1.13.0에는 Python 워크플로 실행에 대한 사소한 호환성이 손상되는 변경 내용이 포함되어 있습니다. 대부분의 애플리케이션에는 변경이 필요하지 않습니다 . 변경 사항은 정확한 슈퍼스텝 수 또는 반복 횟수에 의존하거나, 수렴 경계에서 max_iterations를 설정하거나, 초기 메시지 소스 ID를 검사하거나, 체크포인트의 배치 및 순서를 가정하는 애플리케이션에 영향을 미칩니다.

Background

1.13.0 이전에는 검사점이 기록된 경계에서 실행을 다시 시작하는 데 필요한 워크플로 상태를 캡처하겠다는 약속을 완전히 충족하지 못했습니다. 시작 실행기는 슈퍼스텝 및 검사점 루프 이전에 실행되었으므로 가장 빠른 검사점은 시작 실행자의 출력 및 업데이트된 상태를 포함하지만 원래 워크플로 입력은 포함하지 않았습니다. 마찬가지로 요청 이벤트에 대한 응답은 검사점에서 먼저 기록되지 않고 전달되고 처리되었습니다. 그 결과, 어떤 체크포인트도 원래 입력을 바탕으로 시작 실행기를 다시 실행하거나, 전달된 응답을 바탕으로 사람이 개입하는 후속 진행을 재현할 수 없었습니다.

동작 변경

버전 1.13.0은 이러한 격차를 해소합니다. 시작 실행기는 이제 첫 번째 슈퍼스텝에서 실행되고, 항목 검사점은 해당 슈퍼스텝 전에 초기 입력을 기록하고, 응답 항목 검사점은 처리되기 전에 전달된 응답을 기록합니다. 이러한 변화들이 결합되어, 사람이 개입하는 방식의 재개를 포함한 체크포인트 기반 워크플로 실행을 입력 시점부터 완전히 재실행할 수 있게 합니다.

Important

이러한 변경 내용은 버전 1.13.0 이전에 만든 검사점에는 영향을 주지 않습니다. 기존 검사점은 계속 지원되며 업그레이드 후에도 복원할 수 있습니다.

작업이 필요할 수 있는 변경 내용

영역	1.13.0 이전	1.13.0 및 이후 버전	사용자 영향
실행기 시작	시작 실행기는 슈퍼스텝 루프 전에 실행되었습니다.	입력은 첫 번째 슈퍼스텝에서 실행되는 시작 실행자에 대해 큐에 대기됩니다.	새로 실행할 때마다 `superstep_started` 이벤트와 `superstep_completed` 이벤트가 각각 하나씩 추가로 발생한다.
반복 횟수	반복 1은 시작 실행기가 실행된 후 첫 번째 슈퍼스텝을 나타냅니다.	반복 1은 시작 실행기를 실행합니다. 이후 작업은 한 번의 반복으로 바뀝니다.	이전에 $N$ 반복이 필요했던 워크플로에는 이제 $N + 1$가 필요합니다.
입력 메시지 원본	초기 메시지에 하드 코딩된 원본 ID `"Workflow"`가 있습니다.	초기 메시지는 시작 실행자의 내부 에지를 통해 전달되며 원본 ID `INTERNAL_SOURCE_ID(start_executor.id)`가 있습니다.	초기 메시지 원본 ID를 읽거나 필터링하는 코드는 새 값을 사용해야 합니다.

재생성 향상

영역	1.13.0 이전	1.13.0 및 이후 버전	개선
초기 검사점	반복-0 검사점은 시작 실행기가 실행된 후에 만들어졌습니다. 실행기 출력 메시지와 업데이트된 상태를 캡처했지만 원래 입력은 캡처하지 않았습니다.	슈퍼스텝 1 전에 진입 체크포인트가 생성됩니다. 시작 실행기에서 큐에 대기 중인 원래 입력을 기록합니다.	항목 검사점을 복원하면 시작 실행기를 포함하여 전체 실행이 재생됩니다.
응답 검사점	요청 이벤트에 대한 응답은 검사점에서 먼저 기록되지 않고 전달되었습니다.	응답 항목 체크포인트는 응답이 전달된 후, 이를 소비하는 슈퍼스텝이 실행되기 전에 생성됩니다.	응답 진입 체크포인트를 복원하면 응답을 처리하는 후속 실행이 다시 재생됩니다.

슈퍼스텝 이벤트 처리 업데이트

이제 시작 실행기가 슈퍼스텝 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()

구성된 제한에 도달하기 전에 워크플로가 이미 수렴된 경우에는 변경이 필요하지 않습니다.

초기 메시지 원본 검사 업데이트

시작 실행기가 초기 메시지의 원본 ID를 사용하는 경우 하드 코딩된 "Workflow" 값을 시작 실행기의 내부 에지에 대한 원본 ID로 바꿉니다.

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>"를 반환합니다. 코드가 프레임워크의 원본 ID 형식을 따르도록 이 문자열을 생성하는 대신 도우미를 사용합니다.

검사점 처리 업데이트

초기 입력 검사점

검사점 기능을 사용하도록 설정하면 새로 실행할 때마다 iteration_count == 0에 초기 검사점이 생성됩니다. 이 체크포인트에는 start executor에 전달되는 전송 중 메시지로서 원래 입력이 포함됩니다. 복원하면 시작 실행기가 다시 실행되고 전체 워크플로 실행이 재현됩니다.

각 슈퍼스텝이 완료되면 프레임워크는 검사점을 계속 만듭니다. 슈퍼스텝이 $N$개인 실행에서는 체크포인트가 총 $N + 1$개 예상됩니다. 즉, 진입 체크포인트 1개와 완료된 각 슈퍼스텝마다 체크포인트 1개씩입니다.

반복-0 검사점이 시작 실행기에서 생성한 상태를 포함하고 있다고 가정하는 검토 코드입니다. 이제 해당 상태가 슈퍼스텝 1 이후에 생성된 검사점에서 나타납니다.

요청-응답 검사점

워크플로를 workflow.run(responses=...)로 계속하면 프레임워크는 응답을 대기열에 넣은 후, 그리고 이를 소비하는 슈퍼스텝을 실행하기 전에 응답 항목 체크포인트를 생성합니다. 이 검사점을 복원하면 기록된 응답이 다시 전달되고 나머지 워크플로가 재생됩니다.

응답 항목 체크포인트에는 보류 중인 요청을 포함하는 이전 체크포인트와 동일한 iteration_count가 있습니다. 이는 previous_checkpoint_id가 해당 보류 중인 요청 체크포인트를 가리키는 별도의 체크포인트입니다.