Preskoči na vsebino

Orkestracija agentov

Prikaži kot Markdown Uredi na GitHub Dokumentacija za 2cc7b2b

Queuety je primeren za sisteme agentov, kadar želite prilagodljivo delo, ne da bi se odrekli trajnemu stanju, ponovnim poskusom, pregledovanju in izrecnemu čakanju.

Za večino potekov dela agentov ne potrebujete mehanizma DAG, ki ga je mogoče urejati med izvajanjem. V praksi je večino sistemov mogoče modelirati z majhnim naborom trajnih orkestracijskih operacij. for_each() razširi delo znotraj enega zagona poteka dela. start_agents() in wait_for_agents() predajata med izvajanjem odkrita opravila neodvisnim potekom dela na najvišji ravni. wait_for_decision() in wait_for_input() začasno ustavita potek dela in prepustita nadzor človeku. wait_for_workflow(), wait_for_workflows() in wait_for_agent_group() omogočajo, da en zagon na najvišji ravni počaka na drugega ali na zagnano skupino, ki doseže kvorum.

Uporaben miselni model

Orkestracijo agentov najlažje razumemo po plasteh. Načrtovalnik določi, katero delo je treba opraviti. Queuety to delo pretvori v trajna opravila ali poteke dela. Specialistični zagoni ustvarijo rezultate in shranijo artefakte. Nadzorna stopnja združi rezultate in določi, kaj se zgodi naslednje. Človek lahko kadar koli odobri, zavrne ali popravi zagon, preden se nadaljuje.

Pomembna razlika je v tem, da agent določi, katero delo je treba opraviti, Queuety pa še vedno določi, kako se to delo shrani, ponovno poskusi, nadaljuje in združi. Če je cilj orkestracije dolgotrajna seja in ne omejen zagon, to povežite s State Machines.

Vzorec 1: Načrtovalnik in izvajalnik z neodvisnimi zagoni agentov

Uporabite start_agents(), kadar korak načrtovalnika med izvajanjem odkrije opravila in naj vsako postane lasten potek dela na najvišji ravni.

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

Pri tem vzorcu PlanResearchTasksStep zapiše med izvajanjem odkrite elemente v $state['agent_tasks'], start_agents() sproži en trajen potek dela za vsako opravilo, wait_for_agent_group() pa zadrži nadrejeni potek, dokler ni izpolnjen izbrani pogoj dokončanja. SynthesizeBriefStep nato prejme dokončana stanja podrejenih potekov pod $state['agent_results'].

To je najčistejše izhodišče za sisteme načrtovalnika in izvajalnika, saj je vsak zagon agenta mogoče pregledati in ponoviti neodvisno.

Vzorec 2: Človeški pregled pred nadaljevanjem zagona

Uporabite wait_for_decision(), kadar naj se potek dela ustavi zaradi odločitve, ki zahteva jasen odgovor da ali ne, in wait_for_input(), kadar mora upravljavec v zagon poslati strukturirane povratne informacije.

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

Če pregledovalec odobri:

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

Če pregledovalec zavrne:

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

Po wait_for_decision() potek dela prejme strukturiran tovor s končnim izidom, signalom, ki je nadaljeval zagon, in morebitnimi podatki pregledovalca. Tako dobite pravo kontrolno točko s človekom v zanki, ne da bi med čakanjem zagona ohranjali odprt proces PHP.

Vzorec 3: En potek dela na najvišji ravni čaka na drugega

Včasih je najčistejši model tak, da nimate enega ogromnega poteka dela. En potek dela lahko dokonča raziskavo, drug pa počaka nanj, preden začne naslednjo stopnjo.

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

Tako dobite trajno mejo med raziskovalno in založniško stopnjo. Vsak zagon ima svoj operativni življenjski cikel, drugi potek dela pa se vseeno samodejno nadaljuje, ko je odvisnost izpolnjena.

Izbira ustreznega gradnika

for_each() je prava izbira, kadar delo spada v en zagon poteka dela, veje pa so zgolj vzporedno izvajanje korakov nad eno skupno zbirko stanja.

start_agents() je primernejši, kadar naj vsako odkrito opravilo postane lasten trajen zagon na najvišji ravni in želite te zagone pregledovati, ponavljati ali izvažati ločeno.

wait_for_workflow() in wait_for_workflows() sta primerna, kadar je en potek dela na najvišji ravni odvisen od drugega in želite trajno asinhrono usklajevanje med temi plastmi orkestracije.

wait_for_decision() in wait_for_input() sodita na mesta, kjer mora človek odobriti, zavrniti ali usmeriti zagon, medtem ko potek dela ostane začasno ustavljen in ne zaseda zmogljivosti izvajalcev.

Priporočene konvencije za stanja

Sisteme agentov je lažje odpravljati napake, če so ključi stanja predvidljivi. V praksi se agent_tasks dobro obnese za izhod načrtovalnika, agent_workflow_ids za zagnane poteke na najvišji ravni, agent_results za dokončano stanje podrejenega poteka ter review ali decision za tovore odobritve oziroma zavrnitve. Večji izhodi, kot so osnutki, navedki ali manifesti raziskav, običajno sodijo v shrambo artefaktov, ne pa v glavno zbirko stanja poteka dela.

Poteki dela agentov imajo koristi od varovalnih ukrepov bolj kot skoraj kateri koli drug primer uporabe, saj so po naravi dinamični.

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

Ti nadzori odgovarjajo na praktična vprašanja, ki so pomembna v produkciji: katera različica definicije je ustvarila zagon, ali ga lahko podvojene zunanje zahteve sprožijo dvakrat, ali lahko načrtovalnik ustvari preveč vej in ali lahko stanje poteka dela neomejeno raste. Pri večini sistemov agentov najprej uvedite te varovalne ukrepe, šele nato začnite prilagajati število izvajalcev ali topologijo čakalnih vrst.

Glejte tudi