Aggiornare Python checkpoint del flusso di lavoro alla versione 1.13.0

Agent Framework 1.13.0 contiene modifiche di rilievo minime per Python'esecuzione del flusso di lavoro. La maggior parte delle applicazioni non richiede modifiche. Le modifiche influiscono sulle applicazioni che dipendono dal numero esatto di passaggi sovrapposti o dai numeri di iterazione, impostati max_iterations al limite di convergenza, controllano l'ID origine del messaggio iniziale o fanno ipotesi sul posizionamento e l'ordinamento dei checkpoint.

Background

Prima della versione 1.13.0, il checkpoint non soddisfava completamente la promessa di acquisire lo stato del flusso di lavoro necessario per riprendere l'esecuzione da qualsiasi limite registrato. L'executor di avvio è stato eseguito prima del ciclo superstep e checkpoint, quindi il primo checkpoint conteneva l'output dell'executor iniziale e lo stato aggiornato, ma non l'input originale del flusso di lavoro. Analogamente, le risposte agli eventi di richiesta sono state recapitate ed elaborate senza prima essere registrate in un checkpoint. Di conseguenza, nessun checkpoint potrebbe riprodurre l'executor di avvio dall'input originale o riprodurre una continuazione umana nel ciclo dalla risposta recapitata.

Modifiche del comportamento

La versione 1.13.0 chiude queste lacune. L'executor di avvio viene ora eseguito nel primo passaggio superiore, un checkpoint di ingresso registra l'input iniziale prima del passaggio e un checkpoint di risposta-entry registra le risposte prima dell'elaborazione. Insieme, queste modifiche rendono un flusso di lavoro sottoposto a checkpoint completamente riproducibile dal relativo input, incluse le continuazioni del ciclo umano nel ciclo.

Importante

Queste modifiche non influiscono sui checkpoint creati prima della versione 1.13.0. I checkpoint esistenti rimangono supportati e possono comunque essere ripristinati dopo l'aggiornamento.

Modifiche che potrebbero richiedere un'azione

Area	Prima della versione 1.13.0	Nella versione 1.13.0 e successive	Impatto sugli utenti
Avviare l'executor	L'executor di avvio è stato eseguito prima del ciclo superstep.	L'input viene accodato per l'executor di avvio, che viene eseguito nel primo passaggio superiore.	Ogni nuova esecuzione genera un evento aggiuntivo superstep_started e superstep_completed .
Numero di iterazioni	L'iterazione 1 ha rappresentato il primo passaggio superiore dopo l'esecuzione dell'executor di avvio.	L'iterazione 1 esegue l'executor di avvio. I turni di lavoro successivi si spostano di un'iterazione.	Un flusso di lavoro che in precedenza richiedeva iterazioni $N$ ora richiede $N + 1$.
Origine del messaggio di input	Il messaggio iniziale aveva l'ID "Workflow"di origine hardcoded .	Il messaggio iniziale viene recapitato tramite il perimetro interno dell'executor di avvio e ha l'ID INTERNAL_SOURCE_ID(start_executor.id)di origine .	Il codice che legge o filtra l'ID origine messaggio iniziale deve usare il nuovo valore.

Miglioramenti della riproducibilità

Area	Prima della versione 1.13.0	Nella versione 1.13.0 e successive	Miglioramento
Checkpoint iniziale	Il checkpoint iterazione-0 è stato creato dopo l'esecuzione dell'executor di avvio. Ha acquisito i messaggi di output dell'executor e lo stato aggiornato, ma non l'input originale.	Viene creato un checkpoint di ingresso prima del passaggio 1. Registra l'input originale in coda per l'executor di avvio.	Il ripristino del checkpoint di ingresso riproduce l'esecuzione completa, incluso l'executor di avvio.
Checkpoint di risposta	Una risposta a un evento di richiesta è stata recapitata senza prima essere registrata in un checkpoint.	Dopo il recapito della risposta viene creato un checkpoint di immissione della risposta e prima dell'esecuzione del passaggio superiore di utilizzo.	Il ripristino del checkpoint response-entry riproduce la continuazione che utilizza la risposta.

Aggiornare la gestione degli eventi superstep

Una nuova esecuzione del flusso di lavoro produce ora una coppia di eventi di superstep perché l'executor di avvio viene eseguito in superstep 1:

• superstep_started con iteration == 1
• superstep_completed con iteration == 1

I successivi turni di lavoro dell'executor si spostano di un passaggio superiore. Aggiornare test, telemetria, indicatori di stato o altro codice che presuppone un numero esatto di eventi o esegue il mapping di un determinato executor a un'iterazione fissa.

Il codice che risponde ai tipi di evento senza basarsi sul conteggio o sull'iterazione non deve cambiare.

Esaminare il limite massimo di iterazione

Il max_iterations limite include ora il passaggio superiore che esegue l'executor di avvio. Se in precedenza un flusso di lavoro usava il limite completo, aumentare il valore configurato di uno:

from agent_framework import WorkflowBuilder

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

Non è necessaria alcuna modifica se il flusso di lavoro converge già prima di raggiungere il limite configurato.

Aggiornare i controlli iniziali dell'origine dei messaggi

Se un executor di avvio utilizza l'ID di origine del messaggio iniziale, sostituire il valore hardcoded "Workflow" con l'ID di origine per il bordo interno dell'executor di avvio.

Prima della versione 1.13.0:

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

Nella versione 1.13.0 e successive:

from agent_framework import INTERNAL_SOURCE_ID

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

INTERNAL_SOURCE_ID(executor_id) attualmente restituisce "internal:<executor_id>". Usare l'helper invece di costruire questa stringa in modo che il codice segua il formato ID di origine del framework.

Gestione dei checkpoint di aggiornamento

Checkpoint di input iniziali

Quando il checkpoint è abilitato, ogni nuova esecuzione crea ora un checkpoint di ingresso in iteration_count == 0. Questo checkpoint contiene l'input originale come messaggio in anteprima indirizzato all'executor di avvio. Il ripristino esegue nuovamente l'executor di avvio e riproduce l'esecuzione completa del flusso di lavoro.

Al termine di ogni passaggio, il framework continua a creare un checkpoint. Per un'esecuzione con $N$ superstep, aspettatevi $N + 1$ checkpoint: il checkpoint di ingresso seguito da un checkpoint per ogni passaggio superiore completato.

Esaminare il codice che presuppone che il checkpoint iterazione-0 contenga lo stato generato dall'executor di avvio. Tale stato viene ora visualizzato nel checkpoint creato dopo il passaggio superiore 1.

Checkpoint di richiesta-risposta

Quando si continua un flusso di lavoro con workflow.run(responses=...), il framework crea ora un checkpoint di immissione della risposta dopo l'accodamento delle risposte e prima di eseguire il passaggio superiore che li utilizza. Il ripristino di questo checkpoint recapita nuovamente le risposte registrate e riproduce il resto del flusso di lavoro.

Il checkpoint response-entry ha lo stesso iteration_count del checkpoint precedente che contiene la richiesta in sospeso. Si tratta di un checkpoint separato i cui previous_checkpoint_id punti a quel checkpoint di richiesta in sospeso.

Importante

Non iteration_count è garantito che un elemento sia univoco in una cronologia dei checkpoint del ciclo umano. Seguire la catena per determinare l'ordine previous_checkpoint_id dei checkpoint. Se è necessario il checkpoint più recente, usare l'API di archiviazione del checkpoint anziché selezionare il più grande iteration_count.

Elenco di controllo per la migrazione

• Aggiornare asserzioni e consumer di eventi che dipendono dal numero esatto di passaggi sovrapposti o da numeri di iterazione.
• Aumentare max_iterations di uno solo per i flussi di lavoro che hanno raggiunto il limite precedente.
• Sostituire i controlli dell'ID di origine iniziale con "Workflow"INTERNAL_SOURCE_ID(start_executor.id).
• Considerare il checkpoint iterazione-0 come checkpoint di input di pre-esecuzione.
• Ordinare i checkpoint umani nel ciclo in base alla derivazione anziché presumere iteration_count che sia univoco.
• Verificare che la riproduzione di un checkpoint di ingresso e un checkpoint di immissione della risposta produa l'output e gli effetti collaterali previsti.

Per informazioni dettagliate sull'implementazione, vedere Consentire la riproduzione completa del checkpoint del flusso di lavoro.