Aģentu orķestrēšana

Skatīt kā Markdown Rediģēt vietnē GitHub Dokumentācija vietnē 2cc7b2b

Queuety ir piemērots aģentu sistēmām, kurām vajadzīga pielāgojama darbplūsma, saglabājot noturīgu stāvokli, atkārtotus mēģinājumus, pārskatāmību un skaidri definētu gaidīšanas semantiku.

Vairumam aģentu darbplūsmu nav vajadzīgs izpildes laikā rediģējams DAG dzinis. Praksē lielāko daļu sistēmu var modelēt ar nelielu skaitu noturīgu orķestrēšanas darbību. for_each() izvērš darbu vienā darbplūsmas izpildē. start_agents() un wait_for_agents() nodod izpildes laikā atklāto darbu neatkarīgām augstākā līmeņa darbplūsmām. wait_for_decision() un wait_for_input() aptur izpildi, gaidot cilvēka iesaisti. wait_for_workflow(), wait_for_workflows() un wait_for_agent_group() ļauj vienai augstākā līmeņa izpildei gaidīt citu izpildi vai sāktu izpildes kvorumu.

Noderīgs domāšanas modelis

Aģentu orķestrēšanu ir visvieglāk izprast pa slāņiem. Plānotājs nosaka, kāds darbs jāveic. Queuety pārvērš šo darbu noturīgos uzdevumos vai darbplūsmās. Speciālistu izpildes rada rezultātus un saglabā artefaktus. Pārraudzības posms apkopo rezultātus un nosaka turpmāko rīcību. Jebkurā brīdī cilvēks var apstiprināt, noraidīt vai labot izpildi, pirms tā turpinās.

Svarīgi, ka aģents nosaka veicamo darbu, bet Queuety joprojām nosaka, kā šis darbs tiek saglabāts, mēģināts izpildīt atkārtoti, atsākts un apkopots. Ja orķestrēšanas mērķis ir ilgstoša sesija, nevis ierobežota izpilde, izmantojiet to kopā ar Stāvokļu mašīnas.

1. raksts: plānotājs un izpildītājs ar neatkarīgām aģentu izpildēm

Izmantojiet start_agents(), ja plānotāja solis izpildes laikā atklāj uzdevumus un katram uzdevumam jāveido sava augstākā līmeņa darbplūsma.

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

Šajā rakstā PlanResearchTasksStep ieraksta izpildes laikā atklātos vienumus $state['agent_tasks'], start_agents() nosūta katram uzdevumam atsevišķu noturīgu darbplūsmu, bet wait_for_agent_group() aptur vecāku izpildi, līdz ir izpildīts izvēlētais pabeigšanas nosacījums. Pēc tam SynthesizeBriefStep saņem pabeigto pakārtoto izpildes stāvokli sadaļā $state['agent_results'].

Šis ir vienkāršākais sākumpunkts plānotāja un izpildītāja sistēmām, jo katru aģenta izpildi var atsevišķi pārbaudīt un mēģināt izpildīt atkārtoti.

2. raksts: cilvēka pārskatīšana pirms izpildes turpināšanas

Izmantojiet wait_for_decision(), ja darbplūsma jāaptur, lai saņemtu reālu atbildi "jā" vai "nē", un wait_for_input(), ja operatoram jānosūta strukturētas atsauksmes atpakaļ izpildes procesam.

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

Ja pārskatītājs apstiprina:

PHP

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

Ja pārskatītājs noraida:

PHP

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

Pēc wait_for_decision() darbplūsma saņem strukturētu datu kopu ar gala iznākumu, signālu, kas atsāka izpildi, un visiem tam pievienotajiem pārskatītāja datiem. Tādējādi tiek izveidots īsts cilvēka iesaistes kontrolpunkts, kamēr izpildes gaidīšanas laikā nav jāuztur atvērts PHP process.

3. modelis: viena augstākā līmeņa darbplūsma gaida citu

Dažkārt labākais risinājums nav viena milzīga darbplūsma. Viena darbplūsma var pabeigt izpēti, bet cita var to sagaidīt, pirms sāk nākamo posmu.

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ādējādi starp izpētes un publicēšanas posmu tiek izveidota noturīga robeža. Katrai izpildei ir savs darbības dzīves cikls, taču otrā darbplūsma joprojām atsākas automātiski, kad atkarīgā darbplūsma ir pabeigta.

Pareizās pamatvienības izvēle

for_each() ir īstais rīks, ja darbs pieder vienai darbplūsmas izpildei un atzari patiesībā ir tikai paralēla darbību izpilde ar vienu koplietotu stāvokļa kopu.

start_agents() ir piemērotāks, ja katram atklātajam uzdevumam jābūt savai noturīgai augstākā līmeņa izpildei un šīs izpildes vēlaties pārbaudīt, atkārtot vai eksportēt atsevišķi.

wait_for_workflow() un wait_for_workflows() ir piemēroti, ja viena augstākā līmeņa darbplūsma ir atkarīga no citas un vēlaties noturīgu asinhronu koordinēšanu starp šiem orķestrēšanas slāņiem.

wait_for_decision() un wait_for_input() izmantojiet vietās, kur cilvēkam jāapstiprina, jānoraida vai jāvada izpilde, kamēr darbplūsma paliek apturēta un nepatērē darbinieku kapacitāti.

Ieteicamās stāvokļa konvencijas

Aģentu sistēmas ir vieglāk atkļūdot, ja stāvokļa atslēgas ir paredzamas. Praksē agent_tasks labi noder plānotāja izvadei, agent_workflow_ids — uzsāktajām augstākā līmeņa izpildēm, agent_results — pabeigtas pakārtotās darbplūsmas stāvoklim, bet review vai decision — apstiprinājuma vai noraidījuma datiem. Lielākas izvades, piemēram, melnrakstus, citātus vai izpētes manifestus, parasti labāk glabāt artefaktu krātuvē, nevis galvenajā darbplūsmas stāvokļa kopā.

Ieteicamie ierobežojumi aģentu izpildēm

Aģentu darbplūsmām ierobežojumi ir vajadzīgi vairāk nekā gandrīz jebkuram citam lietojumam, jo tās pēc būtības ir dinamiskas.

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

Šīs kontroles palīdz rast atbildes uz ražošanas vidē svarīgiem praktiskiem jautājumiem: kura definīcijas versija izveidoja izpildi, vai dublēti ārējie pieprasījumi var to palaist divreiz, vai plānotājs var izveidot pārāk daudz atzaru un vai darbplūsmas stāvoklis var augt bez ierobežojuma. Lielākajā daļā aģentu sistēmu sāciet ar šiem ierobežojumiem, pirms pielāgojat darbinieku skaitu vai rindas topoloģiju.