# Agendi orkestreerimine

Queuety sobib hästi agendisüsteemidele, kui soovid kohanduvat tööd koos püsiva oleku, korduskatsete, kontrollimise ja selgesõnalise ooteloogikaga.

Enamiku agendivoogude jaoks pole vaja käitusajal muudetavat DAG-mootorit. Praktikas saab enamiku süsteeme modelleerida väikese hulga püsivate orkestreerimisvõtetega. `for_each()` laiendab tööd ühe töövoo käituse sees. `start_agents()` ja `wait_for_agents()` annavad käitusajal leitud töö üle sõltumatutele tipptaseme töövoogudele. `wait_for_decision()` ja `wait_for_input()` peatavad töövoo inimese sekkumise ootamiseks. `wait_for_workflow()`, `wait_for_workflows()` ja `wait_for_agent_group()` võimaldavad ühel tipptaseme käitusel oodata teist käitust või käivitatud kvoorumi täitumist.

## Kasulik mõttemudel

Agendi orkestreerimist on kõige lihtsam käsitleda kihtidena. Planeerija määrab, millist tööd teha. Queuety muudab selle töö püsivateks ülesanneteks või töövoogudeks. Spetsialistide käitused annavad tulemusi ja salvestavad artefakte. Järelevalveetapp koondab tulemused ja otsustab, mida järgmisena teha. Inimene saab igal ajal käituse enne jätkamist kinnitada, tagasi lükata või seda parandada.

Oluline erinevus seisneb selles, et agent otsustab, mida teha, kuid Queuety määrab endiselt, kuidas seda tööd talletatakse, uuesti proovitakse, jätkatakse ja koondatakse. Kui orkestreerimise siht on piiratud kestusega käituse asemel pikaajaline seanss, kasuta seda koos [olekumasinatega](https://queuety.inline0.dev/et/docs/state-machines).

## Muster 1: planeerija ja täitja sõltumatute agendikäitustega

Kasuta `start_agents()`, kui planeerimisetapp leiab käitusajal ülesandeid ja iga ülesanne peaks saama omaette tipptaseme töövoo.

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

Selles mustris kirjutab `PlanResearchTasksStep` käitusajal leitud üksused asukohta `$state['agent_tasks']`, `start_agents()` käivitab iga ülesande jaoks ühe püsiva töövoo ning `wait_for_agent_group()` peatab ematöövoo, kuni valitud lõpetamistingimus on täidetud. Seejärel saab `SynthesizeBriefStep` lõpetatud alamkäituste olekud võtme `$state['agent_results']` all.

See on planeerija ja täitja süsteemide parim lähtekoht, sest iga agendikäitust saab eraldi uurida ja uuesti proovida.

## Muster 2: inimese ülevaatus enne käituse jätkumist

Kasuta `wait_for_decision()`, kui töövoog peab peatuma selge jah- või ei-otsuse saamiseks, ning `wait_for_input()`, kui operaator peab saama käitusele struktureeritud tagasisidet saata.

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

Kui ülevaataja kinnitab:

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

Kui ülevaataja lükkab tagasi:

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

Pärast `wait_for_decision()` saab töövoog struktureeritud koormuse, mis sisaldab lõpptulemust, käituse jätkanud signaali ja ülevaataja esitatud andmeid. Nii saad tõelise inimese osalusel kontrollpunkti, ilma et peaksid ootamise ajaks hoidma avatud PHP protsessi.

## Muster 3: üks tipptaseme töövoog ootab teist

Mõnikord pole parim lahendus üks hiiglaslik töövoog. Üks töövoog võib uurimistöö lõpetada ja teine oodata selle lõppu, enne kui alustab järgmist etappi.

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

Nii tekib püsiv piir uurimis- ja avaldamisetapi vahele. Kummalgi käitusel on oma elutsükkel, kuid teine töövoog jätkub sõltuvuse täitumisel automaatselt.

## Sobiva primitiivi valimine

`for_each()` on õige tööriist, kui töö kuulub ühe töövoo käituse sisse ning harud on tegelikult lihtsalt sammutaseme paralleeltäitmine ühes ühises olekukogumis.

`start_agents()` sobib paremini, kui iga leitud ülesanne peaks saama omaette püsiva tipptaseme käituse ja soovid neid käitusi eraldi uurida, uuesti proovida või eksportida.

`wait_for_workflow()` ja `wait_for_workflows()` sobivad siis, kui üks tipptaseme töövoog sõltub teisest tipptaseme töövoost ning soovid nende orkestreerimiskihtide vahel püsivat asünkroonset koordineerimist.

`wait_for_decision()` ja `wait_for_input()` sobivad kohtadesse, kus inimene peab käituse kinnitama, tagasi lükkama või seda suunama, samal ajal kui töövoog on peatatud ega kasuta töötaja võimekust.

## Soovitatavad olekukokkulepped

Agendisüsteeme on lihtsam siluda, kui olekuvõtmed on etteaimatavad. Praktikas sobib `agent_tasks` planeerija väljundile, `agent_workflow_ids` käivitatud tipptaseme käitustele, `agent_results` lõpetatud alamkäituste olekule ning `review` või `decision` kinnitamise või tagasilükkamise koormustele. Suuremad väljundid, näiteks mustandid, viited või uurimistöö manifestid, kuuluvad tavaliselt artefaktide salvestuskohta, mitte töövoo põhiandmete hulka.

## Soovitatavad kaitsemeetmed agendikäitustele

Agenditöövood vajavad kaitsemeetmeid rohkem kui peaaegu ükski teine kasutusjuht, sest need on olemuselt dünaamilised.

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

Need juhtnupud vastavad tootmiskeskkonnas olulistele praktilistele küsimustele: milline definitsiooni versioon käituse käivitas, kas korduvad välised päringud võivad selle mitu korda käivitada, kas planeerija saab luua liiga palju harusid ja kas töövoo olek võib piiramatult kasvada. Enamiku agendisüsteemide puhul alusta nendest kaitsemeetmetest, enne kui hakkad töötajate arvu või järjekorra ülesehitust häälestama.

## Vt ka

- [Näited](https://queuety.inline0.dev/et/docs/examples)
- [Toimingu käivitajad](https://queuety.inline0.dev/et/docs/features/action-triggers)
- [Dünaamiline For-Each](https://queuety.inline0.dev/et/docs/workflows/for-each)
- [Asünkroonsed üleandmised](https://queuety.inline0.dev/et/docs/workflows/async-handoffs)
- [Töövoogude sõltuvused](https://queuety.inline0.dev/et/docs/workflows/dependencies)
- [Artefaktid](https://queuety.inline0.dev/et/docs/features/artifacts)
- [Töövoo signaalid](https://queuety.inline0.dev/et/docs/workflows/signals)
- [Töövoo kaitsemeetmed](https://queuety.inline0.dev/et/docs/workflows/guardrails)