Tingkatkan Python titik pemeriksaan alur kerja ke 1.13.0

Agent Framework 1.13.0 berisi perubahan pemecahan kecil pada eksekusi alur kerja Python. Sebagian besar aplikasi tidak memerlukan perubahan. Perubahan ini memengaruhi aplikasi yang bergantung pada jumlah superstep atau nomor iterasi yang tepat, menetapkan max_iterations pada batas konvergensi, memeriksa ID sumber pesan awal, atau membuat asumsi tentang penempatan dan urutan checkpoint.

Background

Sebelum 1.13.0, checkpointing belum sepenuhnya memenuhi janjinya untuk merekam status alur kerja yang diperlukan guna melanjutkan eksekusi dari batas mana pun yang telah direkam. Eksekutor awal dijalankan sebelum loop superstep dan checkpoint, sehingga checkpoint paling awal berisi output eksekutor awal dan state yang telah diperbarui, tetapi bukan masukan alur kerja asli. Demikian pula, respons terhadap peristiwa permintaan dikirimkan dan diproses tanpa terlebih dahulu direkam di titik pemeriksaan. Akibatnya, tidak ada checkpoint yang dapat memutar ulang eksekutor start dari input asli atau menghasilkan kembali kelanjutan dengan campur tangan manusia dari respons yang telah diberikan.

Perubahan perilaku

Versi 1.13.0 menutup celah ini. Eksekutor awal kini dijalankan pada superstep pertama, checkpoint entri mencatat input awal sebelum superstep tersebut, dan checkpoint entri respons mencatat respons yang telah dikirimkan sebelum diproses. Secara keseluruhan, perubahan ini membuat alur kerja yang menggunakan checkpoint dapat dijalankan ulang sepenuhnya berdasarkan inputnya, termasuk kelanjutan yang melibatkan campur tangan manusia.

Important

Perubahan ini tidak memengaruhi titik pemeriksaan yang dibuat sebelum versi 1.13.0. Titik pemeriksaan yang ada tetap didukung dan masih dapat dipulihkan setelah pemutakhiran.

Perubahan yang mungkin memerlukan tindakan

Area	Sebelum 1.13.0	Di versi 1.13.0 dan yang lebih baru	Dampak terhadap pengguna
Mulai pelaksana	Eksekutor awal dijalankan sebelum loop superstep.	Input dimasukkan ke antrean untuk eksekutor awal, yang dijalankan pada superstep pertama.	Setiap eksekusi baru menghasilkan satu peristiwa tambahan superstep_started dan superstep_completed.
Jumlah perulangan	Iterasi 1 menandai superstep pertama setelah start executor dijalankan.	Iterasi 1 menjalankan eksekutor awal. Pekerjaan berikutnya bergeser satu iterasi.	Alur kerja yang sebelumnya membutuhkan perulangan $N$ sekarang membutuhkan $N + 1$.
Sumber pesan masukan	Pesan awal memiliki ID sumber "Workflow" yang sudah ditentukan secara tetap dalam kode.	Pesan awal dikirimkan melalui edge internal eksekutor awal dan memiliki ID sumber INTERNAL_SOURCE_ID(start_executor.id).	Kode yang membaca atau memfilter ID sumber pesan awal harus menggunakan nilai baru.

Penyempurnaan pemutaran ulang

Area	Sebelum 1.13.0	Di versi 1.13.0 dan yang lebih baru	Penyempurnaan
Titik pemeriksaan awal	Checkpoint iterasi-0 dibuat setelah start executor dijalankan. Ini menangkap pesan output eksekutor dan status yang telah diperbarui, tetapi tidak menangkap input aslinya.	Titik pemeriksaan entri dibuat sebelum superstep 1. Ini merekam input asli yang diantrekan untuk pelaksana mulai.	Memulihkan checkpoint entri akan menjalankan ulang seluruh proses eksekusi, termasuk eksekutor awal.
Titik pemeriksaan respons	Respons terhadap peristiwa permintaan dikirimkan tanpa terlebih dahulu direkam di titik pemeriksaan.	Checkpoint entri respons dibuat setelah respons disampaikan dan sebelum superstep yang mengonsumsinya dijalankan.	Memulihkan titik pemeriksaan entri respons memutar ulang kelanjutan yang menggunakan respons.

Memperbarui penanganan peristiwa superstep

Eksekusi alur kerja yang baru kini menghasilkan satu pasangan tambahan peristiwa superstep karena eksekutor awal dijalankan pada superstep 1:

• superstep_started dengan iteration == 1
• superstep_completed dengan iteration == 1

Pekerjaan eksekutor berikutnya bergeser satu superstep. Memperbarui pengujian, telemetri, indikator kemajuan, atau kode lain yang mengasumsikan jumlah peristiwa yang tepat atau memetakan pelaksana tertentu ke perulangan tetap.

Kode yang merespons jenis peristiwa tanpa mengandalkan jumlah atau iterasinya tidak perlu berubah.

Tinjau batas perulangan maksimum

Batas max_iterations sekarang mencakup superstep yang menjalankan eksekutor awal. Jika alur kerja sebelumnya menggunakan batas penuhnya, tingkatkan nilai yang dikonfigurasi dengan satu:

from agent_framework import WorkflowBuilder

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

Tidak ada perubahan yang diperlukan jika alur kerja sudah bertemu sebelum mencapai batas yang dikonfigurasi.

Memperbarui pemeriksaan sumber pesan awal

Jika eksekutor awal menggunakan ID sumber dari pesan awal, ganti nilai "Workflow" yang di-hardcode dengan ID sumber untuk edge internal eksekutor awal.

Sebelum 1.13.0:

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

Dalam 1.13.0 dan yang lebih baru:

from agent_framework import INTERNAL_SOURCE_ID

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

INTERNAL_SOURCE_ID(executor_id) saat ini mengembalikan "internal:<executor_id>". Gunakan pembantu alih-alih membuat string ini sehingga kode Anda mengikuti format ID sumber kerangka kerja.

Memperbarui penanganan titik pemeriksaan

Titik pemeriksaan input awal

Ketika titik pemeriksaan diaktifkan, setiap proses baru sekarang membuat titik pemeriksaan entri di iteration_count == 0. Titik pemeriksaan ini berisi input asli sebagai pesan dalam penerbangan yang ditujukan ke pelaksana mulai. Memulihkannya akan menjalankan ulang eksekutor awal dan menjalankan kembali seluruh eksekusi alur kerja.

Setelah setiap superstep selesai, framework terus membuat checkpoint. Untuk satu proses eksekusi dengan $N$ superstep, akan ada $N + 1$ checkpoint: checkpoint awal, diikuti oleh satu checkpoint untuk setiap superstep yang telah selesai.

Tinjau kode yang menganggap checkpoint iterasi-0 berisi state yang dihasilkan oleh eksekutor awal. Status itu sekarang muncul di titik pemeriksaan yang dibuat setelah superstep 1.

Titik pemeriksaan permintaan-respons

Saat Anda melanjutkan alur kerja dengan workflow.run(responses=...), kerangka kerja sekarang membuat titik pemeriksaan entri respons setelah mengantrekan respons dan sebelum menjalankan superstep yang mengonsumsinya. Memulihkan titik pemeriksaan ini memberikan kembali respons yang direkam dan memutar ulang sisa alur kerja.

Titik pemeriksaan entri respons memiliki iteration_count yang sama dengan titik pemeriksaan sebelumnya yang berisi permintaan tertunda. Ini adalah checkpoint terpisah yang previous_checkpoint_id-nya mengarah ke checkpoint permintaan tertunda tersebut.

Important

iteration_count tidak dijamin unik dalam riwayat checkpoint human-in-the-loop. previous_checkpoint_id Ikuti rantai untuk menentukan urutan titik pemeriksaan. Jika Anda memerlukan titik pemeriksaan terbaru, gunakan API penyimpanan titik pemeriksaan alih-alih memilih yang terbesar iteration_count.

Daftar periksa migrasi

• Perbarui asersi dan konsumen peristiwa yang bergantung pada jumlah superstep atau nomor iterasi yang tepat.
• Tingkatkan max_iterations sebesar satu hanya untuk alur kerja yang telah mencapai batas sebelumnya.
• Ganti pemeriksaan ID sumber awal untuk "Workflow" dengan INTERNAL_SOURCE_ID(start_executor.id).
• Perlakukan titik pemeriksaan iterasi-0 sebagai titik pemeriksaan input pra-eksekusi.
• Urutkan checkpoint human-in-the-loop berdasarkan lineage, alih-alih menganggap iteration_count unik.
• Verifikasi bahwa memutar ulang titik pemeriksaan entri dan titik pemeriksaan entri respons menghasilkan output dan efek samping yang diharapkan.

Untuk detail implementasi, lihat Mengizinkan pemutaran ulang penuh titik pemeriksaan alur kerja.