Agenttien orkestrointi

Näytä Markdown-muodossa Muokkaa palvelussa GitHub Dokumentaatio: 2cc7b2b

Queuety sopii agenttijärjestelmiin, kun haluat mukautuvaa työtä luopumatta pysyvästä tilasta, uudelleenyrityksistä, tarkastelusta ja selkeästä odotussemantiikasta.

Useimmissa agenttityönkuluissa ei tarvita ajonaikaisesti muokattavaa DAG-moottoria. Käytännössä useimmat järjestelmät voidaan mallintaa pienellä joukolla pysyviä orkestrointitoimintoja. for_each() laajentaa työtä yhden työnkulun suorituksen sisällä. start_agents() ja wait_for_agents() siirtävät ajon aikana löydetyt työt erillisiin ylätason työnkulkuihin. wait_for_decision() ja wait_for_input() keskeyttävät suorituksen ihmisen päätöstä varten. wait_for_workflow(), wait_for_workflows() ja wait_for_agent_group() antavat yhden ylätason suorituksen odottaa toista suoritusta tai käynnistettyä päätösvaltaista joukkoa.

Hyödyllinen ajatusmalli

Agenttien orkestrointia on helpointa hahmottaa tasoittain. Suunnittelija päättää, mitä työtä on tehtävänä. Queuety muuntaa työn pysyviksi töiksi tai työnkuluiksi. Erikoistuneet suoritukset tuottavat tuloksia ja tallentavat artefakteja. Valvova vaihe kokoaa tulokset ja päättää, mitä seuraavaksi tapahtuu. Ihminen voi milloin tahansa hyväksyä tai hylätä suorituksen tai korjata sitä ennen sen jatkumista.

Keskeinen ero on, että agentti päättää, mitä työtä tehdään, mutta Queuety huolehtii edelleen siitä, miten työ tallennetaan, yritetään uudelleen, sitä jatketaan ja sen tulokset kootaan. Kun orkestroinnin kohteena on rajatun suorituksen sijaan pitkäikäinen istunto, yhdistä tähän Tilakoneet.

Kuvio 1: Suunnittelija ja suorittaja itsenäisillä agenttisuorituksilla

Käytä start_agents()-toimintoa, kun suunnitteluvaihe löytää tehtäviä ajon aikana ja jokaisesta tehtävästä halutaan oma ylätason työnkulku.

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

Tässä kuviossa PlanResearchTasksStep kirjoittaa ajon aikana löydetyt kohteet kohtaan $state['agent_tasks'], start_agents() käynnistää kullekin tehtävälle oman pysyvän työnkulkunsa, ja wait_for_agent_group() pysäyttää ylätason suorituksen, kunnes valittu valmistumisehto täyttyy. SynthesizeBriefStep saa sitten valmiiden aliprosessien tilat kohdan $state['agent_results'] alla.

Tämä on selkein lähtökohta suunnittelija-suorittaja-järjestelmille, sillä jokainen agentin suoritus säilyy itsenäisesti tarkasteltavana ja uudelleen yritettävänä.

Kuvio 2: Ihmistarkistus ennen suorituksen jatkamista

Käytä wait_for_decision()-toimintoa, kun työnkulun on pysähdyttävä todellista kyllä- tai ei-päätöstä varten, ja wait_for_input()-toimintoa, kun käyttäjän on lähetettävä jäsenneltyä palautetta takaisin suoritukseen.

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

Jos tarkistaja hyväksyy:

PHP

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

Jos tarkistaja hylkää:

PHP

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

Kun wait_for_decision() on valmis, työnkulku saa rakenteisen tietosisällön, joka sisältää lopputuloksen, suorituksen jatkaneen signaalin ja mahdolliset sen mukana tulleet tarkastajan tiedot. Näin saat aidon ihmisen osallistavan tarkistuspisteen pitämättä PHP-prosessia käynnissä odotuksen aikana.

Kuvio 3: Yksi ylätason työnkulku odottaa toista

Joskus selkein ratkaisu ei ole yksi valtava työnkulku. Yksi työnkulku voi tehdä tutkimuksen valmiiksi, ja toinen voi odottaa sitä ennen seuraavan vaiheen aloittamista.

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

Näin tutkimusvaiheen ja julkaisuvaiheen väliin muodostuu pysyvä raja. Kummallakin suorituksella on oma toimintansa elinkaari, mutta toinen työnkulku jatkuu silti automaattisesti, kun riippuvuus on valmis.

Sopivan perustyökalun valinta

for_each() on oikea työkalu, kun työ kuuluu yhden työnkulun suorituksen sisään ja haarat ovat käytännössä vain vaiheiden rinnakkaista suorittamista yhteistä tilaa vasten.

start_agents() sopii paremmin, kun jokaisesta löydetystä tehtävästä halutaan oma pysyvä ylätason suoritus ja suorituksia halutaan tarkastella, yrittää uudelleen tai viedä erikseen.

wait_for_workflow() ja wait_for_workflows() sopivat, kun yksi ylätason työnkulku riippuu toisesta ylätason työnkulusta ja haluat pysyvän, asynkronisen koordinoinnin näiden orkestrointikerrosten välille.

wait_for_decision() ja wait_for_input() sopivat kohtiin, joissa ihmisen on hyväksyttävä, hylättävä tai ohjattava suoritusta työnkulun pysyessä tauolla kuluttamatta työntekijäkapasiteettia.

Suositellut tilakäytännöt

Agenttijärjestelmiä on helpompi virheenkorjata, kun tilan avaimet ovat ennakoitavia. Käytännössä agent_tasks toimii hyvin suunnittelijan tulosteelle, agent_workflow_ids aloitetuille ylätason suorituksille, agent_results valmiille alityönkulun tilalle ja review tai decision hyväksymis- tai hylkäystietosisällöille. Suuremmat tulosteet, kuten luonnokset, viitteet tai tutkimuksen manifestit, kuuluvat yleensä artefaktivarastoon työnkulun päätilan sijaan.

Suositellut suojatoimet agenttien suorituksille

Agenttityönkulut hyötyvät suojatoimista enemmän kuin lähes mikään muu käyttötapaus, koska ne ovat luonteeltaan dynaamisia.

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

Nämä hallintakeinot vastaavat tuotantokäytössä olennaisiin kysymyksiin: mikä määritelmäversio tuotti suorituksen, voiko ulkoinen pyyntö käynnistää sen kahdesti, voiko suunnittelija luoda liian monta haaraa ja voiko työnkulun tila kasvaa rajattomasti. Useimmissa agenttijärjestelmissä ota nämä suojatoimet käyttöön ennen työntekijämäärän tai jonotopologian hienosäätöä.