Preskočiť na obsah

Orchestrácia agentov

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na 2cc7b2b

Queuety sa hodí pre systémy agentov, keď chcete adaptívne spracovanie bez toho, aby ste sa vzdali trvalého stavu, opakovaných pokusov, kontroly a explicitnej sémantiky čakania.

Pre väčšinu tokov agentov nepotrebujete DAG engine, ktorého štruktúru možno meniť počas behu. V praxi sa väčšina systémov dá modelovať pomocou malej množiny trvalých koordinačných krokov. for_each() rozširuje prácu v rámci jedného behu pracovného postupu. start_agents() a wait_for_agents() odovzdávajú prácu objavenú počas behu samostatným pracovným postupom najvyššej úrovne. wait_for_decision() a wait_for_input() pozastavia beh a čakajú na zásah človeka. wait_for_workflow(), wait_for_workflows() a wait_for_agent_group() umožňujú jednému behu najvyššej úrovne čakať na iný beh alebo na dosiahnutie spustenej kvóty.

Užitočný mentálny model

Orchestrácia agentov sa najľahšie chápe po vrstvách. Plánovač rozhoduje, aká práca vznikne. Queuety túto prácu premieňa na trvalé úlohy alebo pracovné postupy. Špecializované behy vytvárajú výsledky a ukladajú artefakty. Dohliadajúca fáza zhromažďuje tieto výsledky a rozhoduje, čo sa stane ďalej. V každom okamihu môže človek beh schváliť, zamietnuť alebo opraviť ešte pred jeho pokračovaním.

Dôležitý rozdiel je v tom, že agent rozhoduje, akú prácu vykonať, ale Queuety stále rozhoduje, ako sa táto práca uloží, zopakuje, obnoví a zhrnie. Ak je cieľom orchestrácie dlhodobá relácia, nie ohraničený beh, spojte to so stavovými automatmi Stavové automaty.

Vzor 1: Plánovač/vykonávateľ so samostatnými behmi agentov

Použite start_agents(), keď krok plánovača počas behu objaví úlohy a každá z nich sa má stať vlastným pracovným postupom najvyššej úrovne.

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

V tomto vzore PlanResearchTasksStep zapisuje položky objavené počas behu do $state['agent_tasks'], start_agents() spustí jeden trvalý pracovný postup pre každú úlohu a wait_for_agent_group() pozastaví nadradený postup, kým sa nesplní zvolená podmienka dokončenia. SynthesizeBriefStep potom prijíma dokončené stavy podriadených postupov pod $state['agent_results'].

Toto je najjednoduchší východiskový bod pre systémy typu plánovač/vykonávateľ, pretože každý beh agenta možno samostatne kontrolovať a opakovať.

Vzor 2: Kontrola človekom pred pokračovaním behu

Použite wait_for_decision(), keď sa má pracovný postup zastaviť a čakať na skutočné rozhodnutie áno alebo nie, a wait_for_input(), keď operátor potrebuje odoslať štruktúrovanú spätnú väzbu späť do behu.

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

Ak kontrolór schváli:

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

Ak kontrolór zamietne:

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

Po wait_for_decision() dostane pracovný postup štruktúrované údaje s konečným výsledkom, signálom, ktorý obnovil beh, a prípadnými údajmi od kontrolóra. Získate tak skutočný kontrolný bod so zapojením človeka bez toho, aby proces PHP zostal otvorený počas čakania behu.

Vzor 3: Jeden pracovný postup najvyššej úrovne čaká na iný

Niekedy je najčistejším modelom rozdeliť prácu do viacerých pracovných postupov. Jeden môže dokončiť prieskum a iný môže počkať, kým sa to stane, a až potom spustiť ďalšiu fázu.

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

Tým získate trvalú hranicu medzi fázou prieskumu a fázou publikovania. Každý beh má vlastný prevádzkový životný cyklus, ale druhý pracovný postup sa po dokončení závislosti aj tak automaticky obnoví.

Výber správneho primitíva

for_each() je správnym nástrojom, keď práca patrí do jedného behu pracovného postupu a vetvy sú v skutočnosti iba paralelným vykonávaním krokov nad jedným zdieľaným objektom stavu.

start_agents() je vhodnejšie, keď sa každá objavená úloha má stať vlastným trvalým behom najvyššej úrovne a chcete tieto behy samostatne kontrolovať, opakovať alebo exportovať.

wait_for_workflow() a wait_for_workflows() sa hodia, keď jeden pracovný postup najvyššej úrovne závisí od iného a chcete medzi týmito vrstvami orchestrácie zabezpečiť trvalú asynchrónnu koordináciu.

wait_for_decision() a wait_for_input() patria na miesta, kde človek potrebuje schváliť, zamietnuť alebo usmerniť beh, zatiaľ čo pracovný postup zostane pozastavený bez využívania kapacity pracovníkov.

Odporúčané konvencie stavu

Systémy agentov sa ľahšie ladia, keď sú kľúče stavu predvídateľné. V praxi sa agent_tasks osvedčuje pre výstup plánovača, agent_workflow_ids pre spustené behy najvyššej úrovne, agent_results pre dokončený stav podriadeného pracovného postupu a review alebo decision pre údaje o schválení alebo zamietnutí. Väčšie výstupy, ako sú návrhy, citácie alebo manifesty prieskumu, zvyčajne patria do úložiska artefaktov, nie do hlavného objektu stavu pracovného postupu.

Pracovné postupy agentov potrebujú ochranné opatrenia viac než takmer ktorýkoľvek iný prípad použitia, pretože sú zo svojej podstaty dynamické.

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

Tieto kontroly odpovedajú na praktické otázky dôležité v produkcii: ktorá verzia definície vytvorila beh, či sa duplicitné externé požiadavky môžu spustiť dvakrát, či plánovač môže vytvoriť priveľa vetiev a či stav pracovného postupu môže rásť bez obmedzenia. Pri väčšine systémov agentov začnite týmito ochrannými opatreniami ešte pred ladením počtu pracovníkov alebo topológie frontov.

Pozrite si aj