Aracı Düzenleme

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: 2cc7b2b

Queuety; kalıcı durum, yeniden denemeler, inceleme ve açık bekleme semantiğinden ödün vermeden uyarlanabilir iş istediğiniz aracı sistemleri için uygundur.

Çoğu ajan akışı için çalışma zamanında düzenlenebilen bir DAG motoruna ihtiyacınız yoktur. Uygulamada çoğu sistem, az sayıda kalıcı orkestrasyon adımıyla modellenebilir. for_each() işleri tek bir iş akışı çalıştırmasının içinde genişletir. start_agents() ve wait_for_agents(), çalışma zamanında keşfedilen işleri bağımsız üst düzey iş akışlarına devreder. wait_for_decision() ve wait_for_input() insan denetimi için duraklatır. wait_for_workflow(), wait_for_workflows() ve wait_for_agent_group(), bir üst düzey çalıştırmanın başka bir çalıştırmayı veya başlatılmış bir yeter sayıyı beklemesini sağlar.

Yararlı bir zihinsel model

Ajan orkestrasyonunu katmanlar halinde düşünmek en kolayıdır. Bir planlayıcı hangi işlerin yapılacağını belirler. Queuety bu işleri kalıcı görevlere veya iş akışlarına dönüştürür. Uzman çalıştırmalar sonuç üretir ve yapıtları saklar. Denetleyici bir aşama bu sonuçları bir araya getirir ve sırada ne olacağına karar verir. Herhangi bir noktada, devam etmeden önce bir kişi çalıştırmayı onaylayabilir, reddedebilir veya düzeltebilir.

Önemli ayrım şudur: hangi işin yapılacağına ajan karar verir, ancak bu işin nasıl kalıcı hale getirileceğine, yeniden deneneceğine, sürdürüleceğine ve bir araya getirileceğine yine Queuety karar verir. Orkestrasyon hedefi sınırlı bir çalıştırma yerine uzun ömürlü bir oturumsa, bunu Durum Makineleri ile birlikte kullanın.

Örüntü 1: Bağımsız ajan çalıştırmalarıyla planlayıcı/yürütücü

Planlayıcı adımı çalışma zamanında görevler keşfediyorsa ve her görev kendi üst düzey iş akışına dönüşmeliyse start_agents() kullanın.

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 ] );

Bu örüntüde PlanResearchTasksStep, çalışma zamanında keşfedilen öğeleri $state['agent_tasks'] içine yazar, start_agents() her görev için kalıcı bir iş akışı başlatır ve wait_for_agent_group() seçilen tamamlanma koşulu karşılanana kadar üst iş akışını bekletir. Ardından SynthesizeBriefStep, tamamlanan alt iş akışı durumlarını $state['agent_results'] altında alır.

Bu, planlayıcı/yürütücü sistemleri için en iyi başlangıç noktasıdır; çünkü her ajan çalıştırması ayrı ayrı incelenebilir ve yeniden denenebilir.

Örüntü 2: Çalıştırma devam etmeden önce insan incelemesi

İş akışının gerçek bir evet-hayır kararı için durması gerekiyorsa wait_for_decision(), operatörün çalıştırmaya yapılandırılmış geri bildirim göndermesi gerekiyorsa wait_for_input() kullanın.

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 ] );

İnceleyen kişi onaylarsa:

PHP

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

İnceleyen kişi reddederse:

PHP

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

wait_for_decision() sonrasında iş akışı; nihai sonucu, çalıştırmayı sürdüren sinyali ve inceleyenin ilettiği tüm verileri içeren yapılandırılmış bir yük alır. Böylece çalıştırma beklerken PHP sürecini açık tutmadan gerçek bir insan denetimli kontrol noktası elde edersiniz.

Örüntü 3: Bir üst düzey iş akışının diğerini beklemesi

Bazen en temiz model, tek ve dev bir iş akışı değildir. Bir iş akışı araştırmayı tamamlayabilir; başka bir iş akışı ise sonraki aşamayı başlatmadan önce bunu bekleyebilir.

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 ] );

Bu, araştırma aşaması ile yayın aşaması arasında kalıcı bir sınır oluşturur. Her çalıştırmanın kendi operasyonel yaşam döngüsü vardır, ancak bağımlılık tamamlandığında ikinci iş akışı yine otomatik olarak devam eder.

Doğru temel yapı taşını seçme

İş tek bir iş akışı çalıştırmasının içinde yer alıyorsa ve dallar aslında ortak bir durum kümesi üzerinde adım düzeyinde paralel yürütmeden ibaretse for_each() doğru araçtır.

Keşfedilen her görev kendi kalıcı üst düzey çalıştırması olmalıysa ve bu çalıştırmaları ayrı ayrı incelemek, yeniden denemek veya dışa aktarmak istiyorsanız start_agents() daha uygundur.

Bir üst düzey iş akışı başka bir üst düzey iş akışına bağlıysa ve bu orkestrasyon katmanları arasında kalıcı, eşzamansız koordinasyon istiyorsanız wait_for_workflow() ve wait_for_workflows() uygun seçimdir.

İş akışı, çalışan kapasitesini tüketmeden duraklatılmış halde kalırken bir kişinin çalıştırmayı onaylaması, reddetmesi veya yönlendirmesi gereken noktalarda wait_for_decision() ve wait_for_input() kullanılır.

Önerilen durum düzenleri

Durum anahtarları öngörülebilir olduğunda ajan sistemlerinde hata ayıklamak kolaylaşır. Uygulamada agent_tasks planlayıcı çıktısı, agent_workflow_ids başlatılan üst düzey çalıştırmalar, agent_results tamamlanan alt iş akışı durumu, review veya decision ise onay ya da ret yükleri için işe yarar. Taslaklar, atıflar veya araştırma manifestoları gibi daha büyük çıktılar genellikle ana iş akışı durum kümesi yerine yapıt deposunda tutulmalıdır.

Ajan çalıştırmaları için önerilen korumalar

Ajan iş akışları, doğaları gereği dinamik olduklarından, neredeyse diğer tüm kullanım alanlarından daha fazla korumadan yararlanır.

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 );

Bu denetimler, üretim ortamında önem taşıyan pratik sorulara yanıt verir: Bir çalıştırmayı hangi tanım sürümünün ürettiği, yinelenen harici isteklerin çalıştırmayı iki kez başlatıp başlatamayacağı, bir planlayıcının çok fazla dal oluşturup oluşturamayacağı ve iş akışı durumunun sınırsız büyüyüp büyüyemeyeceği. Çoğu ajan sistemi için çalışan sayılarını veya kuyruk yapısını ayarlamadan önce bu korumalarla başlayın.