Werkstroomcontrolepunten Python bijwerken naar 1.13.0

Agent Framework 1.13.0 bevat kleine wijzigingen die de uitvoering van Python-workflows incompatibel kunnen maken. Voor de meeste toepassingen zijn geen wijzigingen vereist. De wijzigingen zijn van invloed op toepassingen die afhankelijk zijn van exacte aantallen supersteps of iteratienummers, die max_iterations instellen op de convergentiegrens, die de bron-ID van het initiële bericht inspecteren, of die aannames doen over de plaatsing en volgorde van checkpoints.

Achtergrond

Vóór 1.13.0 voldoet het controlepunt niet volledig aan de belofte van het vastleggen van de werkstroomstatus die nodig is om de uitvoering van een vastgelegde grens te hervatten. De startexecutor werd uitgevoerd vóór de superstep- en checkpointlus, dus het eerste checkpoint bevatte de uitvoer en de bijgewerkte status van de startexecutor, maar niet de oorspronkelijke workflowinvoer. Op dezelfde manier werden reacties op aanvraaggebeurtenissen afgeleverd en verwerkt zonder dat ze eerst in een controlepunt werden vastgelegd. Als gevolg daarvan kon geen checkpoint de startexecutor opnieuw uitvoeren op basis van de oorspronkelijke invoer of een human-in-the-loop-vervolg reproduceren op basis van het geleverde antwoord.

Gedragswijzigingen

Met versie 1.13.0 worden deze hiaten gesloten. De start-executor wordt nu uitgevoerd in de eerste superstep, een entry-checkpoint registreert de initiële invoer vóór die superstep en een response-entry-checkpoint registreert afgeleverde antwoorden voordat ze worden verwerkt. Samen zorgen deze wijzigingen ervoor dat een workflow met checkpoints volledig opnieuw kan worden uitgevoerd op basis van de invoer, inclusief vervolgstappen met menselijke tussenkomst.

Important

Deze wijzigingen zijn niet van invloed op controlepunten die zijn gemaakt vóór versie 1.13.0. Bestaande controlepunten blijven ondersteund en kunnen na de upgrade nog steeds worden hersteld.

Wijzigingen waarvoor mogelijk actie is vereist

Gebied	Voor 1.13.0	In 1.13.0 en hoger	Gebruikersimpact
Uitvoerprogramma starten	De startuitvoerder werd vóór de superstep-lus uitgevoerd.	De invoer wordt in de wachtrij geplaatst voor de startexecutor, die in de eerste superstep draait.	Elke nieuwe uitvoering genereert één extra superstep_started- en superstep_completed-gebeurtenis.
Aantal iteraties	Iteratie 1 vertegenwoordigde de eerste superstep nadat de startuitvoering werd uitgevoerd.	Iteratie 1 voert de startexecutor uit. Latere diensten verschuiven met één iteratie.	Een werkstroom die eerder $N$ iteraties nodig had, heeft nu $N + 1$.
Bron van invoerbericht	Het eerste bericht had de in code vastgelegde bron-id "Workflow".	Het eerste bericht wordt bezorgd via de interne rand van de startexecutor en heeft de bron-id INTERNAL_SOURCE_ID(start_executor.id).	Code die de eerste berichtbron-id leest of filtert, moet de nieuwe waarde gebruiken.

Verbeteringen aan afspeelbaarheid

Gebied	Voor 1.13.0	In 1.13.0 en hoger	Verbetering
Eerste controlepunt	Het iteratie-0-controlepunt is gemaakt nadat de startuitvoering is uitgevoerd. De uitvoerberichten en de bijgewerkte status van de executor zijn vastgelegd, maar niet de oorspronkelijke invoer.	Er wordt een invoercontrolepunt gemaakt voordat superstep 1 wordt gemaakt. Hiermee wordt de oorspronkelijke invoer vastgelegd die in de wachtrij staat voor de startuitvoerer.	Als u het begincontrolepunt herstelt, wordt de volledige run opnieuw uitgevoerd, inclusief de startexecutor.
Antwoordcontrolepunt	Een antwoord op een aanvraaggebeurtenis is afgeleverd zonder eerst in een checkpoint te zijn vastgelegd.	Er wordt een checkpoint voor responsinvoer gemaakt nadat de respons is verzonden en voordat de consumerende superstep wordt uitgevoerd.	Als u het controlepunt voor antwoordinvoer herstelt, wordt de vervolgbewerking die het antwoord verbruikt, opnieuw afgespeeld.

Afhandeling van superstep-gebeurtenissen bijwerken

Een nieuwe workflow-uitvoering levert nu één extra paar superstep-gebeurtenissen op, omdat de start-executor in superstep 1 draait:

• superstep_started met iteration == 1
• superstep_completed met iteration == 1

Daaropvolgend executorwerk verschuift met één superstep. Updatetests, telemetrie, voortgangsindicatoren of andere code waarbij wordt uitgegaan van een exact aantal gebeurtenissen of een bepaalde uitvoerder wordt toegewezen aan een vaste iteratie.

Code die reageert op gebeurtenistypen zonder te vertrouwen op het aantal of de iteratie hoeft niet te worden gewijzigd.

De maximale iteratielimiet controleren

De max_iterations limiet bevat nu de superstep waarmee de startuitvoering wordt uitgevoerd. Als een werkstroom eerder de volledige limiet heeft gebruikt, verhoogt u de geconfigureerde waarde met één:

from agent_framework import WorkflowBuilder

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

Er is geen wijziging nodig als de werkstroom al convergeert voordat de geconfigureerde limiet wordt bereikt.

Initiële berichtbroncontroles bijwerken

Als een startuitvoerer de bron-id van het eerste bericht verbruikt, vervangt u de in code vastgelegde "Workflow" waarde door de bron-id voor de interne rand van de startuitvoerer.

Vóór 1.13.0:

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

In 1.13.0 en hoger:

from agent_framework import INTERNAL_SOURCE_ID

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

INTERNAL_SOURCE_ID(executor_id) geeft momenteel "internal:<executor_id>" terug. Gebruik de helper in plaats van deze tekenreeks samen te stellen, zodat uw code de bron-id-indeling van het framework volgt.

Verwerking van controlepunten bijwerken

Eerste invoercontrolepunten

Wanneer controlepunten zijn ingeschakeld, maakt elke nieuwe uitvoering nu een invoercontrolepunt op iteration_count == 0. Dit controlepunt bevat de oorspronkelijke invoer als een in-flight-bericht dat is geadresseerd aan de startuitvoering. Als u deze herstelt, wordt de startexecutor opnieuw uitgevoerd en wordt de volledige workflow opnieuw uitgevoerd.

Na elke voltooide superstap blijft het framework een checkpoint aanmaken. Voor een uitvoering met $N$ supersteps verwacht u $N + 1$ controlepunten: het invoercontrolepunt gevolgd door één controlepunt voor elke voltooide superstap.

Controleer code die ervan uitgaat dat het checkpoint van iteratie 0 de toestand bevat die door de start-executor is geproduceerd. Deze status wordt nu weergegeven in het controlepunt dat is gemaakt na superstep 1.

Controlepunten voor aanvraagreacties

Wanneer u een workflow voortzet met workflow.run(responses=...), maakt het framework nu een checkpoint voor responsinvoer nadat de responses in de wachtrij zijn geplaatst en voordat de superstep wordt uitgevoerd die ze verwerkt. Als u dit controlepunt herstelt, worden de opgenomen antwoorden opnieuw geleverd en worden de rest van de werkstroom opnieuw afgespeeld.

Het controlepunt voor antwoordinvoer heeft hetzelfde iteration_count als het voorgaande controlepunt dat de aanvraag in behandeling bevat. Het is een afzonderlijk controlepunt waarvan previous_checkpoint_id verwijst naar het controlepunt van die aanvraag in behandeling.

Important

Een iteration_count is niet gegarandeerd uniek in een controlepuntgeschiedenis van mensen in de lus. Volg de previous_checkpoint_id keten om de volgorde van controlepunten te bepalen. Als u het meest recente controlepunt nodig hebt, gebruikt u de opslag-API voor controlepunten in plaats van het grootste iteration_countte selecteren.

Controlelijst voor migratie

• Werk asserties en gebeurtenisgebruikers bij die afhankelijk zijn van exacte superstepaantallen of iteratienummers.
• Verhoog max_iterations met één voor werkstromen die de vorige limiet hebben bereikt.
• Vervang de eerste bron-id-controles voor "Workflow" door INTERNAL_SOURCE_ID(start_executor.id).
• Beschouw het iteratie-0-controlepunt als het invoercontrolepunt voorafgaand aan de uitvoering.
• Orden human-in-the-loop-controlepunten op basis van afstamming in plaats van ervan uit te gaan dat iteration_count uniek is.
• Controleer of het opnieuw afspelen van een invoercontrolepunt en een controlepunt voor antwoordinvoer de verwachte uitvoer en bijwerkingen produceert.

Zie Volledig opnieuw afspelen van workflowcontrolepunten toestaan voor implementatiedetails.