# Neuron Sesijas stāvokļu mašīna

Šī pieeja noder, ja veidojamais risinājums vairāk līdzinās sesijai, nevis vienreizējai izpildei.

Queuety stāvokļu mašīnas pārvalda sesijas dzīves ciklu, Queuety darbplūsmas veic fona darbu, kam noder atkārtoti mēģinājumi, “katram elementam” pabeigšanas režīmi un apkopošana, savukārt Neuron apstrādā pašu aģentu izsaukumus un sarunas atmiņu.

Šāds sadalījums ir piemērots atbalsta kopilotiem, iekšējiem izpētes asistentiem, redakcionālajiem aģentiem, kuru darbs var tikt apturēts cilvēka pārskatīšanai, un tērzēšanas sarunām, kas pāriet starp plānošanas, gaidīšanas un atbildes posmiem.

## Dzīves cikla struktūra

Šajā piemērā viena atbalsta sesija pāriet caur `awaiting_user`, `planning`, `waiting_on_research` un `responding`. Mašīna skaidri pārvalda šo dzīves ciklu, bet fona darbplūsma apkopo izpētes datus un paziņo sesijai, kad darbs ir pabeigts.

## Stāvokļu mašīna

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

Kad lietotājs nosūta ziņojumu:

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

Mašīna pāriet uz `planning`, ievieto savu darbību rindā un sāk izpētes darbplūsmu.

## Plānošanas darbība: palaidiet darbplūsmu

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

Šī stāvokļa darbība neveic pašu izpēti. Tā palaiž darbplūsmu un ieraksta darbplūsmas ID mašīnas stāvoklī.

## Darbplūsmas darbība: paziņojiet mašīnai, kad izpēte ir gatava

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

Kad darbplūsma beidzas, tā nosūta `research_completed` atpakaļ uz mašīnu un pievieno apkopoto materiālu kopu kā notikuma datus.

## Atbildes darbība: izsauciet Neuron ar sesijas atmiņu

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

Kad atbilde ir izveidota, mašīna atgriežas stāvoklī `awaiting_user` ar atjaunināto atbildi publiskajā stāvoklī. Tajā pašā sesijā var pieņemt nākamo `user_message` notikumu un turpināt darbu.

## Kāpēc šī pieeja ir vienkāršāka par vienu lielu darbplūsmu

Sarežģītais darbs joprojām tiek veikts darbplūsmās, jo izpētes posmam vajadzīga plānošana, specializētas izpildes, apkopošana un sintēze. Ilgstošā atbalsta saruna tiek pārvaldīta ar stāvokļu mašīnu, jo sesijā jāseko, vai tā gaida lietotāja ziņojumu, izpētes rezultātus vai iespēju sniegt atbildi.

Šāds sadalījums uztur izpildes kodu pārskatāmu un sesijas modeli skaidri definētu.

## Saistītā dokumentācija

- [Stāvokļu mašīnas](https://queuety.inline0.dev/lv/docs/state-machines)
- [Aģentu orķestrēšana](https://queuety.inline0.dev/lv/docs/workflows/agent-orchestration)
- [Asinhronās nodošanas](https://queuety.inline0.dev/lv/docs/workflows/async-handoffs)
- [Darbplūsmu atkarības](https://queuety.inline0.dev/lv/docs/workflows/dependencies)