# Neuron seansi olekumasin

See muster on kasulik, kui loodav lahendus sarnaneb pigem seansi kui ühekordse käivitusega.

Queuety olekumasinad haldavad seansi elutsüklit, Queuety töövood teevad taustatööd, mille puhul on kasulikud korduskatsed, for-each-tsükli lõpetamisrežiimid ja tulemuste koondamine, ning Neuron haldab tegelikke agendikutseid ja vestlusmälu.

See jaotus sobib hästi klienditoe kaasabilistele, ettevõttesisestele uurimisassistentidele, toimetamisagentidele, mis võivad inimese ülevaatuseks peatuda, ning vestluslõimedele, mis liiguvad planeerimise, ootamise ja vastamise etappide vahel.

## Elutsükli ülesehitus

Selles näites liigub üks klienditoe seanss läbi olekute `awaiting_user`, `planning`, `waiting_on_research` ja `responding`. Olekumasin hoiab elutsükli selgesõnalisena, samal ajal kui taustatöövoog kogub uurimismaterjale ja annab seansile töö valmimisest märku.

## Olekumasin

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

Kui kasutaja saadab sõnumi:

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

Masin liigub olekusse `planning`, lisab oma toimingu järjekorda ja käivitab uurimistöövoo.

## Planeerimistoiming: käivitage töövoog

```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',
        ];
    }
}
```

See olekutoiming ei tee ise uurimistööd. See käivitab töövoo ja salvestab töövoo ID masina olekusse.

## Töövoo etapp: andke masinale märku, kui uurimistöö on valmis

```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 [];
    }
}
```

Töövoo lõppedes saadab see masinasse tagasi `research_completed` ja lisab sündmuse andmetesse sünteesitud materjalikogumi.

## Vastamistoiming: kutsuge Neuron välja seansi mäluga

```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',
        ];
    }
}
```

Pärast vastuse loomist liigub masin tagasi olekusse `awaiting_user`, lisades uuendatud vastuse avalikku olekusse. Seejärel saab sama seanss vastu võtta veel ühe `user_message` sündmuse ja jätkata.

## Miks see on selgem lahendus kui üks suur töövoog

Põhitöö on endiselt töövoo kujul, sest uurimisosa vajab planeerimist, spetsialistide käitusi, tulemuste koondamist ja sünteesi. Pikaajaline klienditoe vestlus sobib olekumasina kujule, sest seanss peab jälgima, kas ootab kasutaja järgmist sõnumit, uurimistöö valmimist või vastuse saatmise luba.

See jaotus hoiab käitusaegse loogika arusaadavana ja seansimudeli selgesõnalisena.

## Seotud dokumentatsioon

- [Olekumasinad](https://queuety.inline0.dev/et/docs/state-machines)
- [Agentide orkestreerimine](https://queuety.inline0.dev/et/docs/workflows/agent-orchestration)
- [Asünkroonsed üleandmised](https://queuety.inline0.dev/et/docs/workflows/async-handoffs)
- [Töövoo sõltuvused](https://queuety.inline0.dev/et/docs/workflows/dependencies)