Atualizar os checkpoints do fluxo de trabalho em Python para 1.13.0

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

Background

Antes da versão 1.13.0, o checkpointing não cumpria plenamente o que prometia: capturar o estado do fluxo de trabalho necessário para retomar a execução a partir de qualquer ponto registrado. O executor inicial foi executado antes do loop de supersteps e checkpoints, de modo que o checkpoint mais antigo continha a saída do executor inicial e o estado atualizado, mas não a entrada original do fluxo de trabalho. Da mesma forma, as respostas aos eventos de solicitação foram entregues e processadas sem primeiro serem registradas em um ponto de verificação. Como resultado, nenhum ponto de verificação pôde reexecutar o executor inicial a partir da entrada original nem recriar uma continuação com intervenção humana a partir da resposta fornecida.

Alterações de comportamento

A versão 1.13.0 fecha essas lacunas. O executor inicial agora é executado no primeiro superstep, um ponto de verificação de entrada registra a entrada inicial antes desse superstep e um ponto de verificação de entrada de resposta registra as respostas entregues antes de serem processadas. Em conjunto, essas alterações fazem com que a execução de um fluxo de trabalho com checkpoints possa ser totalmente reproduzida a partir de sua entrada, incluindo continuações com intervenção humana.

Important

Essas alterações não afetam os pontos de verificação criados antes da versão 1.13.0. Os pontos de verificação existentes permanecem com suporte e ainda podem ser restaurados após a atualização.

Alterações que podem exigir ação

Area	Antes da 1.13.0	Na versão 1.13.0 e posterior	Impacto ao usuário
Iniciar executor	O executor inicial foi executado antes do loop superstep.	A entrada é enfileirada para o executor inicial, que é executado no primeiro superstep.	Cada nova execução emite um evento adicional superstep_started e superstep_completed.
Número de iterações	A iteração 1 representou a primeira superetapa após a execução do executor de inicialização.	A iteração 1 executa o executor inicial. Os turnos de trabalho seguintes são deslocados em uma iteração.	Um fluxo de trabalho que antes precisava de iterações $N$ agora precisa $N + 1$.
Origem da mensagem de entrada	A mensagem inicial tinha a ID de origem codificada "Workflow".	A mensagem inicial é entregue por meio da borda interna do executor inicial e tem a ID INTERNAL_SOURCE_ID(start_executor.id)de origem.	O código que lê ou filtra a ID de origem da mensagem inicial deve usar o novo valor.

Melhorias na rejogabilidade

Area	Antes da 1.13.0	Na versão 1.13.0 e posterior	Aperfeiçoamento
Ponto de verificação inicial	O ponto de verificação da iteração 0 foi criado após o executor inicial ser executado. Ele capturou as mensagens de saída do executor e o estado atualizado, mas não a entrada original.	Um ponto de verificação de entrada é criado antes do superstep 1. Ele registra a entrada original colocada na fila para o executor de inicialização.	Restaurar o ponto de verificação de entrada repete a execução completa, incluindo o executor inicial.
Ponto de verificação de resposta	Uma resposta a um evento de solicitação foi entregue sem primeiro ser registrada em um ponto de verificação.	Um checkpoint de entrada da resposta é criado depois que a resposta é entregue e antes que o superstep que a consome seja executado.	Restaurar o ponto de verificação de entrada de resposta repete a continuação que consome a resposta.

Atualizar o tratamento de eventos do superstep

Uma nova execução do fluxo de trabalho agora produz 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

Os turnos de trabalho subsequentes do executor são deslocados em uma superetapa. Atualizar testes, telemetria, indicadores de progresso ou outro código que pressupõe uma contagem exata de eventos ou mapeia um executor específico para uma iteração fixa.

O código que responde a tipos de eventos sem depender de sua contagem ou iteração não precisa ser alterado.

Examinar o limite máximo de iteração

O limite max_iterations agora inclui o superstep que executa o executor de inicialização. Se um fluxo de trabalho usou anteriormente seu limite completo, aumente o valor configurado em um:

from agent_framework import WorkflowBuilder

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

Nenhuma alteração será necessária se o fluxo de trabalho já convergir antes de atingir o limite configurado.

Atualizar verificações iniciais de origem da mensagem

Se um executor inicial consumir a ID de origem da mensagem inicial, substitua o valor codificado "Workflow" pela ID de origem da borda interna do executor inicial.

Antes da 1.13.0:

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

Na versão 1.13.0 e posterior:

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 retorna "internal:<executor_id>". Use o auxiliar em vez de construir essa cadeia de caracteres para que o código siga o formato de ID de origem da estrutura.

Atualizar tratamento de ponto de verificação

Pontos de verificação de entrada iniciais

Quando o ponto de verificação está habilitado, cada nova execução agora cria um ponto de verificação de entrada em iteration_count == 0. Esse ponto de verificação contém a entrada original na forma de uma mensagem em trânsito endereçada ao executor de inicialização. Ao restaurá-lo, o executor de inicialização é executado novamente e toda a execução do fluxo de trabalho é repetida.

Após cada superstep concluído, a estrutura continua a criar um ponto de verificação. Para uma execução com $N$ supersteps, espere encontrar $N + 1$ checkpoints: o checkpoint inicial, seguido de um checkpoint para cada superstep concluído.

Examine o código que pressupõe que o ponto de verificação de iteração 0 contém o estado produzido pelo executor inicial. Esse estado agora aparece no ponto de verificação criado após a superetapa 1.

Pontos de verificação de solicitação-resposta

Quando você continua um fluxo de trabalho com workflow.run(responses=...), a estrutura agora cria um ponto de verificação de entrada de resposta depois de enfileirar as respostas e antes de executar o superstep que as consome. Ao restaurar este ponto de verificação, o sistema reenvia as respostas registradas e reproduz o restante do fluxo de trabalho.

O ponto de verificação de entrada da resposta tem o mesmo iteration_count que o ponto de verificação anterior que contém a solicitação pendente. É um ponto de verificação separado em que previous_checkpoint_id aponta para esse ponto de verificação de solicitação pendente.

Important

Um iteration_count não tem garantia de ser único em um histórico de pontos de verificação com intervenção humana. Siga o previous_checkpoint_id encadeamento para determinar a ordem dos pontos de verificação. Se você precisar do ponto de verificação mais recente, use a API de armazenamento de ponto de verificação em vez de selecionar o iteration_count de maior tamanho.

Lista de verificação de migração

• Atualize as asserções e os consumidores de eventos que dependem de contagens exatas de supersteps ou números de iteração.
• Aumente max_iterations em um apenas para 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).
• Trate o ponto de controle da iteração-0 como o ponto de controle de entrada antes da execução.
• Ordene os pontos de verificação com intervenção humana por linhagem, em vez de presumir que iteration_count seja único.
• Verifique se a reprodução de um ponto de verificação de entrada e de um ponto de verificação de entrada de resposta produz a saída e os efeitos colaterais esperados.

Para mais detalhes sobre a implementação, consulte Permitir a reexecução completa do ponto de verificação do fluxo de trabalho.