# Orchestrácia agentov

Queuety sa hodí pre systémy agentov, keď chcete adaptívne spracovanie bez toho, aby ste sa vzdali trvalého stavu, opakovaných pokusov, kontroly a explicitnej sémantiky čakania.

Pre väčšinu tokov agentov nepotrebujete DAG engine, ktorého štruktúru možno meniť počas behu. V praxi sa väčšina systémov dá modelovať pomocou malej množiny trvalých koordinačných krokov. `for_each()` rozširuje prácu v rámci jedného behu pracovného postupu. `start_agents()` a `wait_for_agents()` odovzdávajú prácu objavenú počas behu samostatným pracovným postupom najvyššej úrovne. `wait_for_decision()` a `wait_for_input()` pozastavia beh a čakajú na zásah človeka. `wait_for_workflow()`, `wait_for_workflows()` a `wait_for_agent_group()` umožňujú jednému behu najvyššej úrovne čakať na iný beh alebo na dosiahnutie spustenej kvóty.

## Užitočný mentálny model

Orchestrácia agentov sa najľahšie chápe po vrstvách. Plánovač rozhoduje, aká práca vznikne. Queuety túto prácu premieňa na trvalé úlohy alebo pracovné postupy. Špecializované behy vytvárajú výsledky a ukladajú artefakty. Dohliadajúca fáza zhromažďuje tieto výsledky a rozhoduje, čo sa stane ďalej. V každom okamihu môže človek beh schváliť, zamietnuť alebo opraviť ešte pred jeho pokračovaním.

Dôležitý rozdiel je v tom, že agent rozhoduje, akú prácu vykonať, ale Queuety stále rozhoduje, ako sa táto práca uloží, zopakuje, obnoví a zhrnie. Ak je cieľom orchestrácie dlhodobá relácia, nie ohraničený beh, spojte to so stavovými automatmi [Stavové automaty](https://queuety.inline0.dev/sk/docs/state-machines).

## Vzor 1: Plánovač/vykonávateľ so samostatnými behmi agentov

Použite `start_agents()`, keď krok plánovača počas behu objaví úlohy a každá z nich sa má stať vlastným pracovným postupom najvyššej úrovne.

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

V tomto vzore `PlanResearchTasksStep` zapisuje položky objavené počas behu do `$state['agent_tasks']`, `start_agents()` spustí jeden trvalý pracovný postup pre každú úlohu a `wait_for_agent_group()` pozastaví nadradený postup, kým sa nesplní zvolená podmienka dokončenia. `SynthesizeBriefStep` potom prijíma dokončené stavy podriadených postupov pod `$state['agent_results']`.

Toto je najjednoduchší východiskový bod pre systémy typu plánovač/vykonávateľ, pretože každý beh agenta možno samostatne kontrolovať a opakovať.

## Vzor 2: Kontrola človekom pred pokračovaním behu

Použite `wait_for_decision()`, keď sa má pracovný postup zastaviť a čakať na skutočné rozhodnutie áno alebo nie, a `wait_for_input()`, keď operátor potrebuje odoslať štruktúrovanú spätnú väzbu späť do behu.

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

Ak kontrolór schváli:

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

Ak kontrolór zamietne:

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

Po `wait_for_decision()` dostane pracovný postup štruktúrované údaje s konečným výsledkom, signálom, ktorý obnovil beh, a prípadnými údajmi od kontrolóra. Získate tak skutočný kontrolný bod so zapojením človeka bez toho, aby proces PHP zostal otvorený počas čakania behu.

## Vzor 3: Jeden pracovný postup najvyššej úrovne čaká na iný

Niekedy je najčistejším modelom rozdeliť prácu do viacerých pracovných postupov. Jeden môže dokončiť prieskum a iný môže počkať, kým sa to stane, a až potom spustiť ďalšiu fázu.

```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ým získate trvalú hranicu medzi fázou prieskumu a fázou publikovania. Každý beh má vlastný prevádzkový životný cyklus, ale druhý pracovný postup sa po dokončení závislosti aj tak automaticky obnoví.

## Výber správneho primitíva

`for_each()` je správnym nástrojom, keď práca patrí do jedného behu pracovného postupu a vetvy sú v skutočnosti iba paralelným vykonávaním krokov nad jedným zdieľaným objektom stavu.

`start_agents()` je vhodnejšie, keď sa každá objavená úloha má stať vlastným trvalým behom najvyššej úrovne a chcete tieto behy samostatne kontrolovať, opakovať alebo exportovať.

`wait_for_workflow()` a `wait_for_workflows()` sa hodia, keď jeden pracovný postup najvyššej úrovne závisí od iného a chcete medzi týmito vrstvami orchestrácie zabezpečiť trvalú asynchrónnu koordináciu.

`wait_for_decision()` a `wait_for_input()` patria na miesta, kde človek potrebuje schváliť, zamietnuť alebo usmerniť beh, zatiaľ čo pracovný postup zostane pozastavený bez využívania kapacity pracovníkov.

## Odporúčané konvencie stavu

Systémy agentov sa ľahšie ladia, keď sú kľúče stavu predvídateľné. V praxi sa `agent_tasks` osvedčuje pre výstup plánovača, `agent_workflow_ids` pre spustené behy najvyššej úrovne, `agent_results` pre dokončený stav podriadeného pracovného postupu a `review` alebo `decision` pre údaje o schválení alebo zamietnutí. Väčšie výstupy, ako sú návrhy, citácie alebo manifesty prieskumu, zvyčajne patria do úložiska artefaktov, nie do hlavného objektu stavu pracovného postupu.

## Odporúčané ochranné opatrenia pre behy agentov

Pracovné postupy agentov potrebujú ochranné opatrenia viac než takmer ktorýkoľvek iný prípad použitia, pretože sú zo svojej podstaty dynamické.

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

Tieto kontroly odpovedajú na praktické otázky dôležité v produkcii: ktorá verzia definície vytvorila beh, či sa duplicitné externé požiadavky môžu spustiť dvakrát, či plánovač môže vytvoriť priveľa vetiev a či stav pracovného postupu môže rásť bez obmedzenia. Pri väčšine systémov agentov začnite týmito ochrannými opatreniami ešte pred ladením počtu pracovníkov alebo topológie frontov.

## Pozrite si aj

- [Príklady](https://queuety.inline0.dev/sk/docs/examples)
- [Spúšťače akcií](https://queuety.inline0.dev/sk/docs/features/action-triggers)
- [Dynamické cykly pre každý prvok](https://queuety.inline0.dev/sk/docs/workflows/for-each)
- [Asynchrónne odovzdávanie](https://queuety.inline0.dev/sk/docs/workflows/async-handoffs)
- [Závislosti pracovných postupov](https://queuety.inline0.dev/sk/docs/workflows/dependencies)
- [Artefakty](https://queuety.inline0.dev/sk/docs/features/artifacts)
- [Signály pracovného postupu](https://queuety.inline0.dev/sk/docs/workflows/signals)
- [Ochranné opatrenia pracovného postupu](https://queuety.inline0.dev/sk/docs/workflows/guardrails)