# Máquina de estados de memoria y revisión Neuron

Este patrón es útil cuando un agente debe conservar el contexto de la conversación durante varias rondas de revisión humana, pero el ciclo de vida general sigue estando orquestado por Queuety.

Queuety gestiona la máquina de estados de revisión, mientras que Neuron gestiona la memoria del agente para el hilo de redacción.

## Por qué la memoria de Neuron resulta útil aquí

Si un revisor rechaza un borrador y pide cambios, la siguiente llamada al agente no debería tener que reconstruir todo el contexto desde cero.

La `SQLChatHistory` de Neuron encaja bien porque el agente puede seguir trabajando en el mismo hilo de conversación mientras Queuety dirige las decisiones del revisor y las rondas de revisión.

## El agente Neuron con historial basado en SQL

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\History\ChatHistoryInterface;
use NeuronAI\Chat\History\SQLChatHistory;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\SystemPrompt;

final class EditorAgent extends Agent
{
    public function __construct(
        private readonly string $threadId,
        private readonly \PDO $pdo,
    ) {}

    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: $_ENV['ANTHROPIC_API_KEY'],
            model: $_ENV['ANTHROPIC_MODEL'],
        );
    }

    protected function chatHistory(): ChatHistoryInterface
    {
        return new SQLChatHistory(
            thread_id: $this->threadId,
            pdo: $this->pdo,
            table: 'neuron_chat_history',
            contextWindow: 50000,
        );
    }

    public function instructions(): string
    {
        return (string) new SystemPrompt(
            background: [
                'You are an editorial agent for long-form product briefs.',
                'Apply reviewer notes without losing the original intent.',
            ],
        );
    }
}
```

## Redacta una vez y revisa con el mismo hilo de memoria

```php
namespace App\StateMachines\Actions;

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

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

        $threadId = $state['neuron_thread_id'] ?? sprintf(
            'brief:%d:editor',
            $state['brief_id'],
        );

        $prompt = "Write the first draft for brief {$state['brief_id']}.";

        if ('reject' === $event) {
            $prompt = sprintf(
                'Revise the draft using these review notes: %s',
                $event_payload['reason'] ?? 'Tighten the draft and address reviewer concerns.',
            );
        }

        $agent = new EditorAgent($threadId, $pdo);
        $message = $agent->chat(
            new UserMessage($prompt)
        )->getMessage();

        return [
            'neuron_thread_id' => $threadId,
            'draft_markdown' => $message->getContent(),
            'review_round' => (int) ($state['review_round'] ?? 0) + 1,
            '_event' => 'draft_ready',
        ];
    }
}
```

## La máquina de estados Queuety

```php
use Queuety\Enums\StateMachineStatus;
use Queuety\Queuety;

$machine_id = Queuety::machine('brief_review_session')
    ->version('brief-review-session.v1')
    ->state('drafting')
    ->action(DraftBriefAction::class)
    ->on('draft_ready', 'awaiting_review')
    ->state('awaiting_review')
    ->on('approve', 'completed')
    ->on('reject', 'drafting')
    ->state('completed', StateMachineStatus::Completed)
    ->dispatch([
        'brief_id' => 42,
    ]);

// Later, once the draft action has finished and the machine waits in `awaiting_review`:
Queuety::machine_event(
    $machine_id,
    'reject',
    [ 'reason' => 'Tighten the introduction and add pricing context.' ]
);

Queuety::machine_event(
    $machine_id,
    'approve',
    [ 'reviewer' => 'editor@example.com' ]
);
```

La primera iteración entra en `drafting`, ejecuta la acción en cola y pasa a `awaiting_review`.

Si el revisor rechaza el borrador, la máquina vuelve a `drafting`. Como la carga útil del evento `reject` se pasa a `DraftBriefAction`, el siguiente borrador puede incorporar las notas del revisor sin perder el historial original del hilo de Neuron.

## Por qué esto es más claro que repetir un flujo de trabajo

Este problema gira en torno al ciclo de vida. Un borrador espera la revisión humana, un revisor puede aprobarlo o rechazarlo, el rechazo devuelve la sesión a la redacción y la aprobación cierra la sesión. Esto encaja mejor con una máquina de estados que con un flujo de trabajo lineal que vuelve a una etapa anterior.

El estado del flujo de trabajo sigue siendo ideal para datos de orquestación como el número de rondas de revisión, los ID de artefactos y de flujos de trabajo, y las decisiones de enrutamiento. La memoria de Neuron es mejor para el contexto de conversación, como los mensajes anteriores, las revisiones iterativas y las respuestas del modelo que deben seguir formando parte del hilo de redacción.

Usar ambos permite que cada sistema se ocupe de aquello para lo que está mejor preparado.

## Cuándo conviene usar un flujo de trabajo

Prefiere un flujo de trabajo cuando el proceso de revisión está bien acotado y se centra en la ejecución, por ejemplo:

Genera un borrador, espera una aprobación y publícalo.

Prefiere una máquina de estados cuando la sesión puede volver varias veces a los mismos estados y los eventos externos dirigen su ciclo de vida.

## Documentación relacionada

- [Máquinas de estados](https://queuety.inline0.dev/es/docs/state-machines)
- [Señales de flujo de trabajo](https://queuety.inline0.dev/es/docs/workflows/signals)
- [Orquestación de agentes](https://queuety.inline0.dev/es/docs/workflows/agent-orchestration)