Mettre à niveau les points de contrôle du flux de travail Python en version 1.13.0

Agent Framework 1.13.0 contient des changements mineurs avec rupture de compatibilité dans l’exécution des flux de travail Python. La plupart des applications ne nécessitent pas de modifications. Les modifications affectent les applications qui dépendent du nombre exact de supersteps ou du nombre d’itérations, définissent max_iterations à la limite de convergence, inspectent l’ID source du message initial ou supposent l’emplacement et l’ordre des points de contrôle.

Background

Avant la version 1.13.0, le point de contrôle n’a pas entièrement satisfait à sa promesse de capturer l’état du flux de travail nécessaire pour reprendre l’exécution à partir de n’importe quelle limite enregistrée. L’exécuteur de démarrage a été exécuté avant le superstep et la boucle de point de contrôle, de sorte que le point de contrôle le plus ancien contenait la sortie de l’exécuteur de démarrage et l’état mis à jour, mais pas l’entrée initiale du flux de travail. De même, les réponses aux événements de demande ont été remises et traitées sans être enregistrées au préalable dans un point de contrôle. Par conséquent, aucun point de contrôle ne pouvait réexécuter l’exécuteur initial à partir de l’entrée d’origine ni reproduire une continuation avec intervention humaine à partir de la réponse fournie.

Changements de comportement

La version 1.13.0 ferme ces lacunes. L’exécuteur de démarrage s’exécute désormais dans le premier superstep, un point de contrôle d’entrée enregistre l’entrée initiale avant ce superstep et un point de contrôle d’entrée de réponse enregistre les réponses remises avant qu’elles ne soient traitées. Ensemble, ces changements rendent un flux de travail avec points de contrôle entièrement rejouable à partir de son entrée, y compris les reprises avec intervention humaine.

Important

Ces modifications n’affectent pas les points de contrôle créés avant la version 1.13.0. Les points de contrôle existants restent pris en charge et peuvent toujours être restaurés après la mise à niveau.

Modifications susceptibles de nécessiter une action

Zone	Avant 1.13.0	Dans la version 1.13.0 et ultérieure	Impact sur les utilisateurs
Démarrer l’exécuteur	L’exécuteur de démarrage s’est lancé avant la boucle de superstep.	L’entrée est mise en file d’attente pour l’exécuteur de démarrage, qui s’exécute dans le premier superstep.	Chaque nouvelle exécution émet un événement superstep_started supplémentaire et un événement superstep_completed supplémentaire.
Nombre d’itérations	L’itération 1 représentait la première super-étape après l’exécution de l’exécuteur de démarrage.	L’itération 1 exécute l’exécuteur de démarrage. Les travaux suivants sont décalés d’une itération.	Un flux de travail qui avait précédemment besoin d’itérations $N$ a maintenant besoin de $N + 1$.
Source du message d’entrée	Le message initial avait l’ID "Workflow"source codé en dur.	Le message initial est remis via la périphérie interne de l’exécuteur de démarrage et a l’ID INTERNAL_SOURCE_ID(start_executor.id)source.	Le code qui lit ou filtre l’ID source du message initial doit utiliser la nouvelle valeur.

Améliorations de la rejouabilité

Zone	Avant 1.13.0	Dans la version 1.13.0 et ultérieure	Amélioration
Point de contrôle initial	Le point de contrôle itération-0 a été créé après l’exécution de l’exécuteur de démarrage. Il a capturé les messages de sortie de l’exécuteur et l’état mis à jour, mais pas l’entrée d’origine.	Un point de contrôle d’entrée est créé avant le superstep 1. Il enregistre l’entrée d’origine mise en file d’attente pour l’exécuteur de démarrage.	La restauration du point de contrôle d’entrée relance l’intégralité de l’exécution, y compris l’exécuteur initial.
Point de contrôle de réponse	Une réponse à un événement de demande a été remise sans être enregistrée au préalable dans un point de contrôle.	Un point de contrôle à l’entrée de la réponse est créé après la livraison de la réponse et avant l’exécution du superstep qui la consomme.	La restauration du point de contrôle d’entrée de réponse relecture la continuation qui consomme la réponse.

Mettre à jour la gestion des événements superstep

Une nouvelle exécution du workflow produit désormais une paire supplémentaire d’événements de superstep, car l’exécuteur initial s’exécute dans le superstep 1 :

• superstep_started avec iteration == 1
• superstep_completed avec iteration == 1

Le travail de l’exécuteur suivant est décalé d’un superstep. Mettez à jour des tests, des données de télémétrie, des indicateurs de progression ou d’autres codes qui supposent un nombre d’événements exact ou mappe un exécuteur particulier à une itération fixe.

Le code qui répond aux types d’événements sans compter sur leur nombre ou leur itération n’a pas besoin de changer.

Passer en revue la limite d’itération maximale

La limite max_iterations inclut désormais le superstep qui lance l’exécuteur de démarrage. Si un flux de travail a déjà utilisé sa limite complète, augmentez la valeur configurée par un :

from agent_framework import WorkflowBuilder

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

Aucune modification n’est nécessaire si le workflow converge déjà avant d’atteindre la limite configurée.

Mettre à jour les vérifications initiales de la source du message

Si un exécuteur de démarrage consomme l’ID source du message initial, remplacez la valeur codée "Workflow" en dur par l’ID source du bord interne de l’exécuteur de démarrage.

Avant la version 1.13.0 :

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

Dans la version 1.13.0 et ultérieure :

from agent_framework import INTERNAL_SOURCE_ID

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

INTERNAL_SOURCE_ID(executor_id) retourne actuellement "internal:<executor_id>". Utilisez l’assistance au lieu de construire cette chaîne afin que votre code suit le format d’ID source du framework.

Gestion des points de contrôle de mise à jour

Points de contrôle d’entrée initiaux

Lorsque le point de contrôle est activé, chaque nouvelle exécution crée désormais un point de contrôle d’entrée à l’adresse iteration_count == 0. Ce point de contrôle contient l’entrée d’origine en tant que message en cours d’exécution adressé à l’exécuteur de démarrage. La restauration de celui-ci réexécute l’exécuteur de démarrage et reproduit l’exécution complète du flux de travail.

Une fois chaque super-étape terminée, l’infrastructure continue de créer un point de contrôle. Pour une exécution avec $N$ supersteps, attendez-vous à $N + 1$ points de contrôle : le point de contrôle d’entrée suivi d’un point de contrôle pour chaque superstep terminé.

Passez en revue le code qui suppose que le point de contrôle itération-0 contient l’état généré par l’exécuteur de démarrage. Cet état apparaît maintenant dans le point de contrôle créé après le superstep 1.

Points de contrôle de demande-réponse

Lorsque vous poursuivez un flux de travail avec workflow.run(responses=...), le framework crée désormais un point de contrôle d’enregistrement des réponses après leur mise en file d’attente et avant d’exécuter le superstep qui les consomme. La restauration de ce point de contrôle renvoie les réponses enregistrées et réexécute le reste du flux de travail.

Le point de contrôle d’entrée de la réponse présente le même iteration_count que le point de contrôle précédent qui contient la requête en attente. Il s’agit d’un point de contrôle distinct dont previous_checkpoint_id pointe vers ce point de contrôle de requête en attente.

Important

Un iteration_count n’est pas forcément unique dans un historique des points de contrôle avec intervention humaine. Suivez la previous_checkpoint_id chaîne pour déterminer l’ordre des points de contrôle. Si vous avez besoin du dernier point de contrôle, utilisez l’API de stockage de point de contrôle au lieu de sélectionner le plus grand iteration_count.

Liste des éléments à vérifier pour la migration

• Mettez à jour les assertions et les consommateurs d’événements qui dépendent du nombre exact de supersteps ou des numéros d’itération.
• Augmentez max_iterations d’un seul pour les flux de travail qui ont atteint la limite précédente.
• Remplacez les vérifications initiales de l’ID source pour "Workflow" par INTERNAL_SOURCE_ID(start_executor.id).
• Traitez le point de contrôle iteration-0 comme le point de contrôle d’entrée de pré-exécution.
• Triez les points de contrôle avec intervention humaine par lignée plutôt que de supposer que iteration_count est unique.
• Vérifiez que la réexécution d’un point de contrôle d’entrée et d’un point de contrôle d’entrée de réponse produit la sortie attendue et les effets secondaires attendus.

Pour plus de détails sur l’implémentation, consultez Autoriser la rejouabilité complète du point de contrôle du workflow.