# Orchestrace agentů

Queuety se hodí pro systémy agentů, pokud chcete adaptivní práci a zároveň zachovat trvalý stav, opakování, možnost kontroly a výslovnou sémantiku čekání.

Pro většinu toků agentů nepotřebujete modul DAG, který lze upravovat za běhu. V praxi lze většinu systémů modelovat pomocí malé sady trvalých kroků orchestrace. `for_each()` rozšiřuje práci uvnitř jednoho běhu workflow. `start_agents()` a `wait_for_agents()` předávají práci nalezenou za běhu do samostatných workflow nejvyšší úrovně. `wait_for_decision()` a `wait_for_input()` pozastavují běh kvůli lidskému zásahu. `wait_for_workflow()`, `wait_for_workflows()` a `wait_for_agent_group()` umožňují jednomu běhu nejvyšší úrovně čekat na jiný běh nebo na spuštění požadovaného počtu běhů.

## Užitečný mentální model

Orchestrace agentů se nejsnáze chápe po vrstvách. Plánovač určí, jaká práce je potřeba. Queuety tuto práci převede na trvalé úlohy nebo workflow. Specializované běhy vytvářejí výsledky a ukládají artefakty. Nadřazená fáze výsledky shromáždí a rozhodne, co se stane dál. V kterémkoli okamžiku může člověk běh před jeho pokračováním schválit, zamítnout nebo opravit.

Podstatné je, že agent rozhoduje, jakou práci provést, ale Queuety stále rozhoduje, jak se tato práce ukládá, opakuje, obnovuje a agreguje. Pokud je cílem orchestrace dlouhodobá relace namísto ohraničeného běhu, zkombinujte tento přístup se [Stavovými automaty](https://queuety.inline0.dev/cs/docs/state-machines).

## Vzor 1: Plánovač a vykonavatel se samostatnými běhy agentů

`start_agents()` použijte, když krok plánovače za běhu objeví úlohy a každá z nich má tvořit vlastní workflow nejvyšší úrovně.

```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 vzoru `PlanResearchTasksStep` zapisuje položky objevené za běhu do `$state['agent_tasks']`, `start_agents()` odešle jedno trvalé workflow pro každou úlohu a `wait_for_agent_group()` pozastaví nadřazený běh, dokud není splněna zvolená podmínka dokončení. `SynthesizeBriefStep` pak obdrží dokončené stavy podřízených běhů v `$state['agent_results']`.

To je nejlepší výchozí bod pro systémy s plánovačem a vykonavatelem, protože každý běh agenta lze samostatně kontrolovat a opakovat.

## Vzor 2: Lidská kontrola před pokračováním běhu

Použijte `wait_for_decision()`, když se má workflow zastavit a čekat na skutečné rozhodnutí ano či ne, a `wait_for_input()`, když operátor potřebuje do běhu poslat strukturovanou zpětnou vazbu.

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

Pokud kontrolující schválí:

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

Pokud kontrolující zamítne:

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

Po `wait_for_decision()` workflow obdrží strukturovaná data s konečným výsledkem, signálem, který obnovil běh, a případnými údaji od kontrolujícího. Získáte tak skutečný kontrolní bod s účastí člověka, aniž by během čekání běžel proces PHP.

## Vzor 3: Jedno workflow nejvyšší úrovně čeká na jiné

Někdy je nejčistším modelem rozdělení do více workflow místo jednoho obrovského workflow. Jedno workflow může dokončit výzkum a jiné workflow na něj může počkat, než zahájí další fázi.

```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 vznikne trvalá hranice mezi fází výzkumu a fází publikování. Každý běh má vlastní provozní životní cyklus, ale druhé workflow se po dokončení závislého běhu přesto automaticky obnoví.

## Výběr správné primitivní konstrukce

`for_each()` je vhodným nástrojem, když práce patří do jednoho běhu workflow a větve jsou ve skutečnosti jen paralelním vykonáváním kroků nad jedním sdíleným objektem stavu.

`start_agents()` se hodí lépe, když každá objevená úloha má mít vlastní trvalý běh nejvyšší úrovně a chcete tyto běhy samostatně kontrolovat, opakovat nebo exportovat.

`wait_for_workflow()` a `wait_for_workflows()` se hodí, když jedno workflow nejvyšší úrovně závisí na jiném a chcete mezi těmito vrstvami orchestrace zajistit trvalou asynchronní koordinaci.

`wait_for_decision()` a `wait_for_input()` použijte tam, kde člověk potřebuje běh schválit, zamítnout nebo usměrnit, zatímco workflow zůstává pozastavené a nespotřebovává kapacitu workerů.

## Doporučené konvence pro stav

Systémy agentů se snáze ladí, když jsou klíče stavu předvídatelné. V praxi se `agent_tasks` hodí pro výstup plánovače, `agent_workflow_ids` pro spuštěné běhy nejvyšší úrovně, `agent_results` pro dokončený stav podřízených workflow a `review` nebo `decision` pro data o schválení či zamítnutí. Větší výstupy, například koncepty, citace nebo manifesty výzkumu, obvykle patří do úložiště artefaktů, nikoli do hlavního objektu stavu workflow.

## Doporučená ochranná opatření pro běhy agentů

Workflow agentů potřebují ochranná opatření více než téměř jakýkoli jiný případ použití, protože jsou ze své 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 );
```

Tyto kontroly odpovídají na praktické otázky důležité v produkčním prostředí: která verze definice vytvořila běh, zda mohou duplicitní externí požadavky spustit běh dvakrát, zda může plánovač vytvořit příliš mnoho větví a zda se stav workflow může neomezeně zvětšovat. U většiny systémů agentů začněte těmito ochrannými opatřeními, než začnete ladit počty workerů nebo topologii front.

## Viz také

- [Příklady](https://queuety.inline0.dev/cs/docs/examples)
- [Spouštěče akcí](https://queuety.inline0.dev/cs/docs/features/action-triggers)
- [Dynamické opakování pro každou položku](https://queuety.inline0.dev/cs/docs/workflows/for-each)
- [Asynchronní předání](https://queuety.inline0.dev/cs/docs/workflows/async-handoffs)
- [Závislosti workflow](https://queuety.inline0.dev/cs/docs/workflows/dependencies)
- [Artefakty](https://queuety.inline0.dev/cs/docs/features/artifacts)
- [Signály workflow](https://queuety.inline0.dev/cs/docs/workflows/signals)
- [Ochranná opatření workflow](https://queuety.inline0.dev/cs/docs/workflows/guardrails)