Atualize os checkpoints de fluxo de trabalho em Python para a versão 1.13.0

O Agent Framework 1.13.0 contém pequenas alterações de quebra na execução do fluxo de trabalho em Python. A maioria das aplicações não exige alterações. As alterações afetam aplicações que dependem de contagens exatas de superpassos ou números de iteração, definem max_iterations no limite de convergência, inspecionam o ID de origem da mensagem inicial ou fazem suposições sobre o posicionamento e a ordenação dos pontos de verificação.

Background

Antes da versão 1.13.0, a criação de pontos de verificação não cumpria integralmente a promessa de captar o estado do fluxo de trabalho necessário para retomar a execução a partir de qualquer limite registado. O executor inicial era executado antes do superstep e do ciclo de checkpoints, pelo que o primeiro checkpoint continha a saída do executor inicial e o estado atualizado, mas não a entrada original do fluxo de trabalho. De forma semelhante, as respostas aos eventos solicitados eram entregues e processadas sem serem previamente registadas num ponto de controlo. Como resultado, nenhum checkpoint conseguia reexecutar o executor de arranque a partir da entrada original nem reproduzir uma continuação com intervenção humana a partir da resposta fornecida.

Alterações comportamentais

A versão 1.13.0 elimina estas lacunas. O executor inicial agora executa o primeiro superpasso, um ponto de controlo de entrada regista a entrada inicial antes desse superpasso, e um ponto de verificação resposta-entrada regista as respostas entregues antes de serem processadas. Em conjunto, estas alterações fazem com que um fluxo de trabalho com pontos de controlo seja integralmente reexecutável a partir dos seus dados de entrada, incluindo continuações com intervenção humana.

Alterações que podem exigir ação

Melhorias na possibilidade de voltar a jogar

Atualizar a gestão de eventos superstep

Uma nova execução do fluxo de trabalho produz agora um par adicional de eventos de superstep, porque o executor inicial é executado no superstep 1:

• superstep_started com iteration == 1
• superstep_completed com iteration == 1

O trabalho do executor subsequente é deslocado em um superpasso. Atualize testes, telemetria, indicadores de progresso ou outro código que assuma uma contagem exata de eventos ou que mapeie um executor específico para uma iteração fixa.

O código que responde aos tipos de eventos sem depender da sua contagem ou iteração não precisa de mudar.

Revise o limite máximo de iteração

O limite max_iterations passa agora a incluir o superstep que executa o executor de arranque. Se um fluxo de trabalho usou anteriormente o seu limite total, aumente o valor configurado em um:

from agent_framework import WorkflowBuilder

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

Não é necessária qualquer alteração se o fluxo de trabalho já convergir antes de atingir o limite configurado.

Atualizar as verificações iniciais da fonte da mensagem

Se um executor de início consumir o ID de origem da mensagem inicial, substitua o valor fixo "Workflow" pelo ID de origem da aresta interna do executor de início.

Antes da 1.13.0:

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

Na versão 1.13.0 e posteriores:

from agent_framework import INTERNAL_SOURCE_ID

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

INTERNAL_SOURCE_ID(executor_id) atualmente devolve "internal:<executor_id>". Use o helper em vez de construir esta cadeia de caracteres para que o seu código siga o formato de source ID do framework.

Atualização do tratamento de pontos de controlo

Pontos de verificação de entrada iniciais

Quando o ponto de verificação está ativado, cada nova execução cria agora um ponto de verificação inicial em iteration_count == 0. Este checkpoint contém a entrada original como uma mensagem em voo endereçada ao executor inicial. Ao restaurá-lo, reexecuta o executor inicial e reproduz toda a execução do fluxo de trabalho.

Após cada superpasso concluído, a estrutura continua a criar um ponto de controlo. Para uma execução com $N$ superpassos, espere $N + 1$ pontos de controlo: o ponto de controlo inicial, seguido de um ponto de controlo por cada superpasso concluído.

Reveja o código que parte do princípio de que o ponto de controlo da iteração 0 contém o estado produzido pelo executor de arranque. Esse estado aparece agora no ponto de controlo criado após o superstep 1.

Pontos de controlo de pedido e resposta

Quando se continua um fluxo de trabalho com workflow.run(responses=...), o framework cria agora um checkpoint de entrada de resposta após colocar as respostas na fila e antes de executar o superstep que as consome. Restaurar este ponto de controlo volta a entregar as respostas gravadas e repete o resto do fluxo de trabalho.

O ponto de controlo de entrada de resposta tem o mesmo iteration_count que o ponto de controlo anterior que contém o pedido pendente. É um ponto de controlo separado cujo previous_checkpoint_id aponta para esse ponto de controlo de pedido pendente.

Lista de verificação da migração

• Atualize asserções e consumidores de eventos que dependam de contagens exatas de superpassos ou números de iteração.
• Aumente max_iterations em uma unidade apenas nos fluxos de trabalho que atingiram o limite anterior.
• Substitua as verificações iniciais do ID de origem para "Workflow" por INTERNAL_SOURCE_ID(start_executor.id).
• Considere o ponto de verificação da iteração 0 como o ponto de verificação de entrada de pré-execução.
• Ordene os pontos de controlo com intervenção humana com base na linhagem, em vez de assumir que iteration_count é único.
• Verifique se repetir um ponto de controlo de entrada e um ponto de controlo de resposta-entrada produz a saída esperada e os efeitos secundários.

Para obter detalhes de implementação, consulte Permitir a repetição integral do ponto de verificação do fluxo de trabalho.