İçeriğe geç

Neuron Oturum Durum Makinesi

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: 2cc7b2b

Bu kalıp, oluşturduğunuz yapı tek seferlik bir çalıştırmadan çok bir oturum gibi davrandığında kullanışlıdır.

Oturumun yaşam döngüsünü Queuety durum makineleri yönetir, Queuety iş akışları yeniden denemelerden, her öğe için işlem tamamlanma kiplerinden ve toplamadan yararlanan arka plan işlerini yürütür, gerçek aracı çağrılarını ve konuşma belleğini ise Neuron yönetir.

Bu ayrım; destek yardımcıları, kurum içi araştırma asistanları, insan incelemesi için duraklayabilen editoryal aracılar ve planlama, bekleme ve yanıt aşamaları arasında ilerleyen sohbet dizileri için uygundur.

Yaşam döngüsünün yapısı

Bu örnekte bir destek oturumu awaiting_user, planning, waiting_on_research ve responding durumlarından geçer. Makine bu yaşam döngüsünü açıkça tanımlı tutarken, arka plan iş akışı araştırma bilgilerini toplar ve tamamlandığında oturuma sinyal gönderir.

Durum makinesi

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

Bir kullanıcı mesaj gönderdiğinde:

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

Makine planning durumuna geçer, işlemini kuyruğa alır ve araştırma iş akışını başlatır.

Planlama işlemi: iş akışını başlatma

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

Bu durum işlemi araştırmayı kendisi yapmaya çalışmaz. Bir iş akışı başlatır ve iş akışı kimliğini makine durumuna kaydeder.

İş akışı adımı: araştırma hazır olduğunda makineye sinyal gönderme

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

İş akışı tamamlandığında research_completed makineye geri gönderilir ve sentezlenmiş dosya olay yükü olarak eklenir.

Yanıtlama işlemi: oturum belleğiyle Neuron çağrısı

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

Yanıt oluşturulduktan sonra makine, güncellenmiş yanıt genel durumdayken yeniden awaiting_user durumuna geçer. Aynı oturum başka bir user_message olayını kabul edip devam edebilir.

Bu neden tek ve büyük bir iş akışından daha temiz

Yoğun işlem hâlâ iş akışı biçimindedir; çünkü araştırma tarafında planlama, uzman çalıştırmaları, toplama ve sentez gerekir. Uzun süreli destek konuşması ise durum makinesi biçimindedir; çünkü oturumun bir kullanıcı mesajını mı, araştırmayı mı beklediğini yoksa yanıt göndermesine izin verilip verilmediğini izlemesi gerekir.

Bu ayrım çalışma zamanı kodunu okunabilir, oturum modelini de açık tutar.