# Aģentu orķestrēšana

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](https://queuety.inline0.dev/lv/docs/state-machines).

## 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.

## Skatiet arī

- [Piemēri](https://queuety.inline0.dev/lv/docs/examples)
- [Darbību aktivizētāji](https://queuety.inline0.dev/lv/docs/features/action-triggers)
- [Dinamiska izpilde katram vienumam](https://queuety.inline0.dev/lv/docs/workflows/for-each)
- [Asinhrona nodošana](https://queuety.inline0.dev/lv/docs/workflows/async-handoffs)
- [Darbplūsmu atkarības](https://queuety.inline0.dev/lv/docs/workflows/dependencies)
- [Artefakti](https://queuety.inline0.dev/lv/docs/features/artifacts)
- [Darbplūsmas signāli](https://queuety.inline0.dev/lv/docs/workflows/signals)
- [Darbplūsmas ierobežojumi](https://queuety.inline0.dev/lv/docs/workflows/guardrails)