Neuronセッションのステートマシン

Markdownとして表示 GitHubで編集ドキュメント: 2cc7b2b

構築するものが単発の実行というよりもセッションに近い場合に、このパターンが役立ちます。

Queuetyのステートマシンがセッションのライフサイクルを管理し、Queuetyのワークフローが再試行、for-each完了モード、集約に適したバックグラウンド処理を担い、Neuronが実際のエージェント呼び出しと会話メモリを扱います。

この分担は、サポート用コパイロット、社内調査アシスタント、人によるレビューのために一時停止することがある編集エージェント、計画・待機・応答の各段階を移行するチャットスレッドに適しています。

ライフサイクルの流れ

この例では、1つのサポートセッションがawaiting_user、planning、waiting_on_research、respondingの各状態を移行します。ステートマシンがこのライフサイクルを明示し、バックグラウンドワークフローが調査情報を集め、完了時にセッションへ通知します。

ステートマシン

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

ユーザーがメッセージを送信すると、次のようになります。

PHP

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

ステートマシンはplanningへ遷移し、アクションをキューに入れて調査ワークフローを開始します。

計画アクション：ワークフローをディスパッチする

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

この状態アクションは調査そのものを行いません。ワークフローをディスパッチし、そのワークフローIDをステートマシンの状態に記録します。

ワークフローのステップ：調査完了時にステートマシンへ通知する

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

ワークフローが完了すると、research_completedをステートマシンに送り、イベントペイロードとして要約した資料を含めます。

応答アクション：セッションメモリを使ってNeuronを呼び出す

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

応答が生成されると、ステートマシンは公開状態の更新済み返信とともにawaiting_userへ戻ります。同じセッションで次のuser_messageイベントを受け付け、そのまま続行できます。

1つの大きなワークフローより適切な理由

調査側では計画、専門エージェントの実行、集約、要約が必要なため、負荷の高い処理には引き続きワークフローが適しています。一方、長期間続くサポート会話にはステートマシンが適しています。セッションがユーザーの応答待ち、調査待ち、応答を返せる状態のどれなのかを管理する必要があるためです。

この分担によってランタイムを把握しやすくし、セッションモデルを明示できます。