Actualizar los puntos de control del flujo de trabajo de Python a la versión 1.13.0

Agent Framework 1.13.0 contiene cambios importantes menores en Python ejecución del flujo de trabajo. La mayoría de las aplicaciones no requieren cambios. Los cambios afectan a las aplicaciones que dependen de un número exacto de superpasos o de iteraciones, establecen max_iterations en el límite de convergencia, inspeccionan el ID de origen del mensaje inicial o hacen suposiciones sobre la ubicación y el orden de los puntos de control.

Background

Antes de la versión 1.13.0, los puntos de control no cumplen completamente su promesa de capturar el estado de flujo de trabajo necesario para reanudar la ejecución desde cualquier límite registrado. El ejecutor de inicio se ejecutó antes del bucle de superpaso y puntos de control, por lo que el primer punto de control contenía la salida del ejecutor de inicio y el estado actualizado, pero no la entrada original del flujo de trabajo. De forma similar, las respuestas a los eventos de solicitud se entregaron y procesaron sin registrarse primero en un punto de control. Como resultado, ningún punto de control podía volver a ejecutar el ejecutor inicial a partir de la entrada original ni reproducir una continuación con intervención humana a partir de la respuesta proporcionada.

Cambios de comportamiento

La versión 1.13.0 cierra estas lagunas. El ejecutor inicial ahora se ejecuta en el primer superpaso, un punto de control de entrada registra la entrada inicial antes de ese superpaso y un punto de control de entrada de respuestas registra las respuestas entregadas antes de que se procesen. En conjunto, estos cambios hacen que un flujo de trabajo con puntos de control pueda reproducirse por completo a partir de su entrada, incluidas las continuaciones con intervención humana.

Cambios que podrían requerir acción

Mejoras de rejugabilidad

Actualización del control de eventos de superstep

Una nueva ejecución de flujo de trabajo ahora genera un par más de eventos de superstep porque el ejecutor de inicio se ejecuta en superstep 1:

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

El trabajo del ejecutor posterior cambia por un superpaso. Actualice pruebas, telemetría, indicadores de progreso u otro código que asuma un recuento exacto de eventos o asigne un ejecutor determinado a una iteración fija.

El código que responde a los tipos de eventos sin depender de su recuento o iteración no necesita cambiar.

Revisión del límite máximo de iteración

El max_iterations límite ahora incluye el superpaso que ejecuta el ejecutor de inicio. Si un flujo de trabajo usó previamente su límite completo, aumente el valor configurado en uno:

from agent_framework import WorkflowBuilder

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

No se necesita ningún cambio si el flujo de trabajo ya converge antes de alcanzar el límite configurado.

Actualizar comprobaciones de origen de mensajes iniciales

Si un ejecutor de inicio consume el identificador de origen del mensaje inicial, reemplace el valor fijo "Workflow" por el identificador de origen de la arista interna del ejecutor de inicio.

Antes de la versión 1.13.0:

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

En 1.13.0 y versiones 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) devuelve actualmente "internal:<executor_id>". Use el asistente en lugar de construir esta cadena para que el código siga el formato de identificador de origen del marco.

Actualización de la gestión de puntos de control

Puntos de control de entrada iniciales

Cuando se habilitan los puntos de control, cada nueva ejecución crea ahora un punto de control de entrada en iteration_count == 0. Este punto de control contiene la entrada original como un mensaje en curso dirigido al ejecutor de inicio. Al restaurarlo, se vuelve a ejecutar el ejecutor inicial y se reproduce la ejecución completa del flujo de trabajo.

Después de completar cada superpaso, el marco continúa creando un punto de control. Para una ejecución con $N$ superpasos, espere $N + 1$ puntos de control: el punto de control inicial, seguido de un punto de control por cada superpaso completado.

Revise el código que supone que el punto de control de iteración-0 contiene el estado generado por el ejecutor de inicio. Ese estado aparece ahora en el punto de control creado después del superpaso 1.

Puntos de control de solicitud-respuesta

Al continuar un flujo de trabajo con workflow.run(responses=...), el framework ahora crea un punto de control de entrada de respuestas después de poner las respuestas en cola y antes de ejecutar el superpaso que las consume. La restauración de este punto de control vuelve a entrega las respuestas grabadas y reproduce el resto del flujo de trabajo.

El punto de control de entrada de respuesta tiene el mismo iteration_count que el punto de control anterior que contiene la solicitud pendiente. Es un punto de control independiente cuyo previous_checkpoint_id apunta a ese punto de control de solicitud en espera.

Lista de comprobación para la migración

• Actualice las aserciones y los consumidores de eventos que dependen de recuentos exactos de superpasos o números de iteración.
• Aumente max_iterations en uno solo para los flujos de trabajo que alcanzaron el límite anterior.
• Reemplace las comprobaciones de identificador de origen iniciales de "Workflow" por INTERNAL_SOURCE_ID(start_executor.id).
• Considere el punto de control de la iteración 0 como el punto de control de entrada previo a la ejecución.
• Ordene los puntos de control con intervención humana por linaje en lugar de asumir que iteration_count es único.
• Compruebe que, al volver a ejecutar un punto de control de entrada y un punto de control de respuesta-entrada, se producen la salida y los efectos secundarios esperados.

Para obtener más información sobre la implementación, consulte Permitir la reproducibilidad completa del punto de control de flujo de trabajo.