# Neuron Stavový automat relácie

Tento vzor je užitočný, keď sa vytváraná funkcia správa skôr ako relácia než ako jednorazové spustenie.

Stavové automaty Queuety spravujú životný cyklus relácie, workflowy Queuety vykonávajú úlohy na pozadí, ktorým prospieva opakovanie pokusov, režimy dokončenia pri spracovaní každého prvku a agregácia, a Neuron zabezpečuje samotné volania agenta a konverzačnú pamäť.

Toto rozdelenie sa hodí pre podporných asistentov, interných výskumných asistentov, redakčných agentov, ktorí sa môžu pozastaviť kvôli ľudskej kontrole, aj četové vlákna prechádzajúce fázami plánovania, čakania a odpovede.

## Priebeh životného cyklu

V tomto príklade jedna relácia podpory prechádza stavmi `awaiting_user`, `planning`, `waiting_on_research` a `responding`. Automat zachováva explicitný životný cyklus, zatiaľ čo workflow na pozadí zhromažďuje podklady a po dokončení vyšle relácii signál.

## Stavový automat

```php
use Queuety\Queuety;

$session_id = Queuety::machine( 'support_session' )
    ->version( 'support-session.v1' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( DispatchResearchWorkflowAction::class )
    ->on( 'research_dispatched', 'waiting_on_research' )
    ->state( 'waiting_on_research' )
    ->on( 'research_completed', 'responding' )
    ->state( 'responding' )
    ->action( RespondWithNeuronAction::class )
    ->on( 'response_ready', 'awaiting_user' )
    ->dispatch( [
        'thread_id' => 'support:customer-42',
    ] );
```

Keď používateľ odošle správu:

```php
Queuety::machine_event(
    $session_id,
    'user_message',
    [
        'session_machine_id' => $session_id,
        'message' => 'Can you compare our pricing to the main competitors?',
    ]
);
```

Automat prejde do stavu `planning`, zaradí svoju akciu a spustí výskumný workflow.

## Plánovacia akcia: odoslanie workflowu na vykonanie

```php
namespace App\StateMachines\Actions;

use Queuety\Contracts\StateAction;
use Queuety\Enums\WaitMode;
use Queuety\Queuety;

final class DispatchResearchWorkflowAction implements StateAction
{
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string
    {
        $message = trim( (string) ( $event_payload['message'] ?? '' ) );

        $agent_workflow = Queuety::workflow( 'support_research_agent' )
            ->then( ResearchTopicStep::class );

        $research_workflow = Queuety::workflow( 'support_research_packet' )
            ->then( PlanResearchTasksStep::class )
            ->start_agents( 'agent_tasks', $agent_workflow )
            ->wait_for_agents( mode: WaitMode::All, result_key: 'agent_results' )
            ->then( SynthesizeResearchPacketStep::class )
            ->then( NotifySessionResearchReadyStep::class );

        $workflow_id = $research_workflow->dispatch( [
            'machine_id'      => $state['session_machine_id'],
            'thread_id'       => $state['thread_id'],
            'customer_prompt' => $message,
        ] );

        return [
            'latest_user_message'  => $message,
            'research_workflow_id' => $workflow_id,
            '_event'               => 'research_dispatched',
        ];
    }
}
```

Táto akcia stavu sa nepokúša vykonať samotný výskum. Spustí workflow a zaznamená jeho ID do stavu automatu.

## Krok workflowu: odoslanie signálu automatu po dokončení výskumu

```php
namespace App\Workflow\Steps;

use Queuety\Queuety;
use Queuety\Step;

final class NotifySessionResearchReadyStep implements Step
{
    public function handle( array $state ): array
    {
        Queuety::machine_event(
            $state['machine_id'],
            'research_completed',
            [
                'research_packet' => $state['research_packet'],
            ]
        );

        return [];
    }

    public function config(): array
    {
        return [];
    }
}
```

Po dokončení workflow odošle `research_completed` späť do automatu a priloží zostavené podklady ako obsah udalosti.

## Akcia odpovede: zavolanie Neuron s pamäťou relácie

```php
namespace App\StateMachines\Actions;

use App\Neuron\SupportAgent;
use NeuronAI\Chat\Messages\UserMessage;
use Queuety\Contracts\StateAction;

final class RespondWithNeuronAction implements StateAction
{
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string
    {
        // Queuety creates actions with `new RespondWithNeuronAction()`, so build dependencies here.
        $pdo = new \PDO( $_ENV['NEURON_DB_DSN'], $_ENV['NEURON_DB_USER'], $_ENV['NEURON_DB_PASSWORD'] );

        $agent = new SupportAgent(
            threadId: $state['thread_id'],
            pdo: $pdo,
        );

        $message = $agent->chat(
            new UserMessage(
                sprintf(
                    "Answer the user message '%s' using this research packet:\n\n%s",
                    $state['latest_user_message'],
                    json_encode( $state['research_packet'] ?? [], JSON_PRETTY_PRINT )
                )
            )
        )->getMessage();

        return [
            'assistant_reply' => $message->getContent(),
            '_event'          => 'response_ready',
        ];
    }
}
```

Po vytvorení odpovede automat prejde späť do stavu `awaiting_user` s aktualizovanou odpoveďou vo verejnom stave. Tá istá relácia potom môže prijať ďalšiu udalosť `user_message` a pokračovať.

## Prečo je to prehľadnejšie než jeden veľký workflow

Náročná práca sa stále vykonáva vo workflowe, pretože výskumná časť potrebuje plánovanie, špecializované behy, agregáciu a syntézu. Dlhšie trvajúca podporná konverzácia sa riadi stavovým automatom, pretože relácia musí sledovať, či čaká na ťah používateľa, na výsledky výskumu alebo môže odoslať odpoveď.

Toto rozdelenie udržiava behový kód prehľadný a model relácie explicitný.

## Súvisiaca dokumentácia

- [Stavové automaty](https://queuety.inline0.dev/sk/docs/state-machines)
- [Orchestrácia agentov](https://queuety.inline0.dev/sk/docs/workflows/agent-orchestration)
- [Asynchrónne odovzdávanie riadenia](https://queuety.inline0.dev/sk/docs/workflows/async-handoffs)
- [Závislosti workflowov](https://queuety.inline0.dev/sk/docs/workflows/dependencies)