Orkestrasi Agen

Lihat sebagai Markdown Edit di GitHub Dokumentasi di 2cc7b2b

Queuety cocok untuk sistem agen ketika Anda menginginkan pekerjaan adaptif tanpa mengorbankan status persisten, percobaan ulang, inspeksi, dan semantik penantian yang eksplisit.

Anda tidak memerlukan mesin DAG yang dapat diedit saat runtime untuk sebagian besar alur agen. Dalam praktiknya, sebagian besar sistem dapat dimodelkan dengan sejumlah kecil mekanisme orkestrasi persisten. for_each() mengembangkan pekerjaan di dalam satu proses alur kerja. start_agents() dan wait_for_agents() menyerahkan pekerjaan yang ditemukan saat runtime ke alur kerja tingkat atas yang independen. wait_for_decision() dan wait_for_input() menjeda proses untuk kendali manusia. wait_for_workflow(), wait_for_workflows(), dan wait_for_agent_group() memungkinkan satu proses tingkat atas menunggu proses lain atau kuorum yang telah dimulai.

Model mental yang berguna

Orkestrasi agen paling mudah dipahami jika dibagi menjadi beberapa lapisan. Perencana menentukan pekerjaan yang ada. Queuety mengubah pekerjaan itu menjadi job atau alur kerja persisten. Proses spesialis menghasilkan hasil dan menyimpan artefak. Tahap pengawasan menggabungkan hasil tersebut dan menentukan langkah berikutnya. Kapan pun, manusia dapat menyetujui, menolak, atau mengoreksi proses sebelum dilanjutkan.

Perbedaan pentingnya adalah agen menentukan pekerjaan yang harus dilakukan, tetapi Queuety tetap menentukan cara pekerjaan itu disimpan, dicoba ulang, dilanjutkan, dan digabungkan. Jika sasaran orkestrasi adalah sesi berumur panjang, bukan proses terbatas, padukan ini dengan Mesin Status.

Pola 1: Perencana/pelaksana dengan proses agen independen

Gunakan start_agents() ketika langkah perencana menemukan tugas saat runtime dan setiap tugas harus menjadi alur kerja tingkat atas tersendiri.

PHP

use Queuety\Enums\WaitMode;
use Queuety\Queuety;

$agent_run = Queuety::workflow( 'agent_run' )
    ->then( FetchSourcesStep::class )
    ->then( DraftFindingStep::class );

Queuety::workflow( 'brief_research' )
    ->version( 'brief-research.v1' )
    ->idempotency_key( 'brief:42:research' )
    ->max_transitions( 20 )
    ->then( PlanResearchTasksStep::class )
    ->start_agents( 'agent_tasks', $agent_run, group_key: 'researchers' )
    ->wait_for_agent_group( 'researchers', WaitMode::Quorum, 2, 'agent_results' )
    ->then( SynthesizeBriefStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );

Dalam pola ini, PlanResearchTasksStep menulis item yang ditemukan saat runtime ke $state['agent_tasks'], start_agents() men-dispatch satu alur kerja persisten untuk setiap tugas, dan wait_for_agent_group() menahan proses induk hingga kondisi penyelesaian yang dipilih terpenuhi. SynthesizeBriefStep kemudian menerima status anak yang telah selesai di bawah $state['agent_results'].

Ini adalah titik awal paling sederhana untuk sistem perencana/pelaksana karena setiap proses agen tetap dapat diperiksa dan dicoba ulang secara mandiri.

Pola 2: Peninjauan manusia sebelum proses dilanjutkan

Gunakan wait_for_decision() ketika alur kerja harus berhenti untuk keputusan ya atau tidak yang nyata, dan wait_for_input() ketika operator perlu mengirim masukan terstruktur kembali ke proses.

PHP

use Queuety\Queuety;

$workflow_id = Queuety::workflow( 'brief_review' )
    ->then( DraftBriefStep::class )
    ->wait_for_decision( result_key: 'review' )
    ->then( HandleReviewDecisionStep::class )
    ->wait_for_input( result_key: 'revision_notes' )
    ->then( ApplyRevisionNotesStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );

Jika peninjau menyetujui:

PHP

Queuety::approve_workflow(
    $workflow_id,
    [
        'reviewer' => 'editor@example.com',
        'notes' => 'Looks good, publish after legal check',
    ],
    'approved'
);

Jika peninjau menolak:

PHP

Queuety::reject_workflow(
    $workflow_id,
    [
        'reviewer' => 'editor@example.com',
        'reason' => 'Needs citations and a stronger conclusion',
    ],
    'rejected'
);

Setelah wait_for_decision(), alur kerja menerima payload terstruktur berisi hasil akhir, sinyal yang melanjutkan proses, serta data peninjau apa pun yang menyertainya. Ini memberi Anda titik pemeriksaan dengan keterlibatan manusia yang sesungguhnya tanpa membiarkan proses PHP tetap terbuka saat alur kerja menunggu.

Pola 3: Satu alur kerja tingkat atas menunggu alur kerja lain

Terkadang model paling sederhana bukan satu alur kerja raksasa. Satu alur kerja dapat menyelesaikan riset, lalu alur kerja lain dapat menunggunya sebelum memulai tahap berikutnya.

PHP

use Queuety\Enums\WaitMode;
use Queuety\Queuety;

$research_id = Queuety::workflow( 'research_brief' )
    ->then( PlanResearchTasksStep::class )
    ->start_agents( 'agent_tasks', $agent_run )
    ->wait_for_agents( mode: WaitMode::All, result_key: 'agent_results' )
    ->then( SynthesizeBriefStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );

Queuety::workflow( 'publish_brief' )
    ->wait_for_workflow( $research_id, 'research' )
    ->wait_for_decision( result_key: 'editor_review' )
    ->then( PublishBriefStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );

Dengan begitu, ada batas persisten antara tahap riset dan tahap publikasi. Setiap proses memiliki siklus operasionalnya sendiri, tetapi alur kerja kedua tetap dilanjutkan secara otomatis saat dependensinya selesai.

Memilih primitif yang tepat

for_each() adalah alat yang tepat ketika pekerjaan berada di dalam satu proses alur kerja dan cabangnya sebenarnya hanya eksekusi paralel pada tingkat langkah dengan satu wadah status bersama.

start_agents() lebih tepat ketika setiap tugas yang ditemukan harus menjadi proses tingkat atas persisten tersendiri dan Anda ingin memeriksa, mencoba ulang, atau mengekspor proses tersebut secara terpisah.

wait_for_workflow() dan wait_for_workflows() cocok ketika satu alur kerja tingkat atas bergantung pada alur kerja tingkat atas lainnya dan Anda menginginkan koordinasi asinkron yang persisten di antara lapisan orkestrasi tersebut.

wait_for_decision() dan wait_for_input() tepat digunakan ketika manusia perlu menyetujui, menolak, atau mengarahkan proses sementara alur kerja tetap dijeda tanpa memakai kapasitas worker.

Konvensi status yang disarankan

Sistem agen lebih mudah di-debug jika kunci status dapat diprediksi. Dalam praktiknya, agent_tasks cocok untuk keluaran perencana, agent_workflow_ids untuk proses tingkat atas yang dimulai, agent_results untuk status alur kerja anak yang telah selesai, dan review atau decision untuk payload persetujuan atau penolakan. Keluaran yang lebih besar seperti draf, sitasi, atau manifes riset biasanya lebih tepat disimpan di penyimpanan artefak daripada di wadah status utama alur kerja.

Panduan pengaman yang disarankan untuk proses agen

Alur kerja agen membutuhkan panduan pengaman lebih dari hampir semua kasus penggunaan lainnya karena sifatnya dinamis.

PHP

Queuety::workflow( 'agent_research' )
    ->version( 'agent-research.v2' )
    ->idempotency_key( 'brief:42:agent-research' )
    ->max_transitions( 20 )
    ->max_for_each_items( 12 )
    ->max_state_bytes( 32768 );

Kontrol tersebut menjawab pertanyaan praktis yang penting dalam produksi: versi definisi mana yang menghasilkan suatu proses, apakah permintaan eksternal duplikat dapat men-dispatch proses dua kali, apakah perencana dapat membuat terlalu banyak cabang, dan apakah status alur kerja dapat tumbuh tanpa batas. Untuk sebagian besar sistem agen, mulailah dengan panduan pengaman tersebut sebelum menyesuaikan jumlah worker atau topologi antrean.