> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-es/flujo-de-trabajo/human-in-the-loop.md).

# Interrupción

El avance clave es que la interrupción no es un error, es una característica.

El patrón de interrupción de Neuron permite que un Workflow pause la ejecución y espere una entrada externa — una decisión humana, o un evento de otro sistema — y se reanude más tarde, incluso en otro proceso, horas o días después.

En esta versión principal, el modelo mental se basa en una regla:

> **Una pausa envía datos&#x20;*****fuera*****&#x20;de un nodo. Una reanudación trae los datos&#x20;*****de vuelta*****.**

* **Saliente — `InterruptRequest`**: la descripción de la pausa. Un nodo la construye para decirle al mundo exterior *qué está esperando* (acciones para aprobar, un nombre de evento, contenido para revisar). Es inmutable y nunca se devuelve al flujo de trabajo.
* **Entrante — el array de carga útil**: la respuesta que satisface la pausa. Un `array` simple, seguro para serialización, `entregado mediante`resume(payload: \[...]) **valor de retorno** de la llamada de suspensión.

### Cómo funciona

Un flujo de trabajo de IA a menudo necesita detenerse a mitad de camino, normalmente para pedirle a un humano aprobación antes de actuar, sin mantener vivo un proceso de PHP mientras el humano decide. Para pausar, un nodo llama `interrupt()`: el flujo de trabajo detiene el recorrido, conserva su progreso y vuelve normalmente al llamador con el estado marcado como interrumpido.

```php
namespace App\Neuron;

use NeuronAI\Workflow\Events\Event;
use NeuronAI\Workflow\Interrupt\Action;
use NeuronAI\Workflow\Interrupt\ApprovalRequest;
use NeuronAI\Workflow\Node;
use NeuronAI\Workflow\WorkflowState;

class ApprovalNode extends Node
{
    public function __invoke(
        PurchaseEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): Event {
        // Suspende el flujo de trabajo, llevando la solicitud HACIA AFUERA.
        $payload = $this->interrupt(
            new ApprovalRequest(
                message: '¿Apruebas esta compra?',
                actions: [
                    new Action(
                        id: 'purchase_1',
                        name: 'Purchase',
                        description: "Compra {$event->item} por {$event->price}$",
                    ),
                ],
            )
        );

        // El código debajo de esta línea se ejecuta SOLO al reanudar.
        // $payload es la respuesta ENTRANTE entregada por resume() — tu nodo la interpreta.
        if (($payload['purchase_1'] ?? null) === 'approve') {
            return new PurchaseApprovedEvent();
        }

        return new PurchaseRejectedEvent();
    }
}
```

El ciclo de vida:

1. **Solicitud** — el nodo construye un `InterruptRequest` describiendo la pausa y llama `interrupt()`.
2. **Suspender** — el ejecutor detiene el recorrido, persiste los pasos del flujo de trabajo y marca el estado devuelto como interrumpido. La solicitud viaja hacia afuera en el estado para que tu aplicación la renderice.
3. **Decisión** — tu aplicación presenta la solicitud a un humano y recoge la respuesta.
4. **Reanudar** — llamas a `resume($payload)` en un flujo de trabajo reconstruido con el mismo `runId`. El recorrido se repite: los nodos completados se omiten y el nodo interrumpido se vuelve a ejecutar con la carga útil inyectada — `interrupt()` devuelve eso en lugar de suspender de nuevo.

#### La capa de persistencia

Suspender y reanudar funciona mediante **repetición**: cada nodo se ejecuta como un paso duradero, y los pasos completados se persisten para que una ejecución reanudada pueda saltar directamente al nodo interrumpido. Eso requiere un backend de persistencia. Sin uno, no hay nada desde lo que reanudar.

```php
use NeuronAI\Workflow\Persistence\FilePersistence;
use NeuronAI\Workflow\Persistence\PersistenceInterface;
use NeuronAI\Workflow\Workflow;

class MyWorkflow extends Workflow
{
    ...
    
    protected function persistence(): PersistenceInterface
    {
        return new FilePersistence(__DIR__);
        // o: new DatabasePersistence($pdo)
        // o: EloquentPersistence para aplicaciones Laravel
    }
}
```

La persistencia por defecto `InMemoryPersistence` admite suspender y reanudar **dentro del mismo proceso** (útil en pruebas); usa `FilePersistence`, `DatabasePersistence`, o `EloquentPersistence` cuando la reanudación ocurre en una solicitud posterior o en un worker en segundo plano.

La solicitud se envía y se olvida. El `InterruptRequest` solicitud en sí no se persiste; solo se almacena una marca de "interrumpido" por paso. Al reanudar, el nodo se vuelve a ejecutar y reconstruye la solicitud de forma determinista (repetición mediante nueva ejecución).

Dos consecuencias:

* Puedes poner con seguridad instancias de objetos vivos en una solicitud personalizada; nada se serializa nunca.
* Si tu aplicación necesita mostrar más tarde "¿qué está esperando esta ejecución?", guarda la solicitud tú mismo en el momento de la suspensión (ver abajo); el framework te la entrega a través del estado devuelto.

### Capturar la interrupción

Después de una suspensión, tu aplicación tiene que detectar que el flujo de trabajo se pausó, mostrar la solicitud a un humano y conservar un identificador para volver más tarde. Dado que `run()` devuelve normalmente, esto es una simple comprobación sobre el estado devuelto: `isInterrupted()` te indica que el flujo de trabajo se pausó, `getInterruptRequest()` te da la solicitud saliente para renderizar, y el `runId` es el token de reanudación.

```php
use NeuronAI\Workflow\Persistence\FilePersistence;
use NeuronAI\Workflow\Persistence\PersistenceInterface;
use NeuronAI\Workflow\Workflow;

class MyWorkflow extends Workflow
{
    protected function nodes(): array
    {
        return [
            new FirstNode(),
            new ApprovalNode(),
            new FinalNode(),
        ];
    }
    
    protected function persistence(): PersistenceInterface
    {
        return new FilePersistence(__DIR__);
    }
}

// Ejecutar el flujo de trabajo
$state = $workflow->setWorkflowId('wk_id')->run();

// Comprobar si fue interrumpido
if ($state->isInterrupted()) {
    $request = $state->getInterruptRequest();  // la solicitud SALIENTE — renderízala
    $runId = $workflow->getRunId();            // el token de reanudación — guárdalo

    // p. ej. guárdalo para tu UI, junto con el token de reanudación
    $stmt = $pdo->prepare("INSERT INTO pending_approvals (run_id, request) VALUES (?, ?)");
    $stmt->execute([$runId, json_encode($request)]);
}
```

Cada `InterruptRequest` es `JsonSerializable`, así que `json_encode($request)` le da a tu frontend todo lo que necesita para renderizar la pausa.

#### Reanudación

Una vez que tengas la respuesta del humano, reconstruye el flujo de trabajo con el **mismo `runId`** , y entrega la carga útil entrante. Nunca reconstruyes ni devuelves la solicitud — la carga útil por sí sola es la respuesta. `resume()` no toma ningún identificador de paso: el framework encuentra el paso interrumpido repitiendo la ejecución.

```php
// Un proceso nuevo, una nueva solicitud HTTP — horas después.
$workflow = Workflow::make(runId: $runId)->setWorkflowId('wk_id');

// La carga útil entrante — un array simple con la respuesta a la pausa.
$finalState = $workflow->resume(['purchase_1' => 'approve']);
```

Si el flujo de trabajo se suspende de nuevo más adelante (múltiples puntos de aprobación), el estado devuelto vuelve a quedar interrumpido y el ciclo se repite con el mismo `runId`.

### Interrupción condicional

Usa `interruptIf()` para suspender solo cuando se cumpla una condición. La condición puede ser un booleano o una callback; cuando no se cumple, el método devuelve `null` y la ejecución continúa.

```php
$payload = $this->interruptIf(
    $order->total > 1000,
    new ApprovalRequest(
        message: 'Pedido de alto valor — se requiere aprobación.',
        actions: [new Action('order_1', 'Aprobar pedido', "Total: {$order->total}$")],
    )
);

// O evalúa perezosamente
$payload = $this->interruptIf(
    fn (): bool => $state->get('confidence', 1.0) < 0.5,
    new ApprovalRequest(/* ... */)
);
```

### Esperando un evento externo

A veces la respuesta no viene de un humano sino de otro sistema, un webhook de pago, una carga de documento, una devolución de llamada de una API de terceros. Para este caso `awaitEvent()` suspende el flujo de trabajo hasta que se entrega un evento con el nombre dado. Es azúcar sintáctico sobre `interrupt()` con un `WaitForEventRequest`, así que no se necesita una clase personalizada.

```php
class WaitForPaymentNode extends Node
{
    public function __invoke(
        OrderCreatedEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): Event {
        // Suspende hasta que se entregue 'payment.confirmed'.
        $payment = $this->awaitEvent('payment.confirmed');

        $state->set('transaction_id', $payment['transaction_id']);
        return new OrderPaidEvent();
    }
}
```

Entregar el evento es simplemente una reanudación desde donde el evento llegue a tu aplicación — normalmente un controlador webhook:

```php
// Tu controlador webhook, cuando el proveedor de pagos responde:
$workflow = OrderWorkflow::make(runId: $order->workflow_run_id)
    ->setPersistence($persistence);

$workflow->signal('payment.confirmed', ['transaction_id' => $webhook['tx_id']])->run();
```

El nombre del evento en la solicitud es lo que usa tu aplicación para enrutar el evento correcto a la ejecución correcta. El framework no despacha eventos por sí mismo; tu código decide a qué ejecución suspendida `runId` pertenece un evento entrante.

### Solicitud de interrupción personalizada

La `ApprovalRequest` integrada modela decisiones de aprobar o rechazar sobre una lista de acciones. Cuando tu pausa necesita una forma distinta — digamos, un humano editando contenido generado antes de guardarlo — crea una subclase de un tipo de solicitud existente y añade el contexto saliente que tu UI necesita. Extiende `WaitForEventRequest` (una respuesta humana es un evento externo entregado al flujo de trabajo); especializas la carga útil, no la categoría de la pausa.

```php
namespace App\Neuron;

use NeuronAI\Workflow\Interrupt\WaitForEventRequest;

class ContentReviewRequest extends WaitForEventRequest
{
    public const EVENT_NAME = 'content.review';
    
    public function __construct(
        protected string $message,
        protected string $content,
        ?DateTimeImmutable $expiresAt = null,
    ) {
        parent::__construct(self::EVENT_NAME, $expiresAt);
    }

    public function getMessage(): string
    {
        return $this->message;
    }

    public function getContent(): string
    {
        return $this->content;
    }

    public function jsonSerialize(): array
    {
        return [
            'type' => $this->type(),
            'note' => $this->note,
            'content' => $this->content,
        ];
    }
}
```

La solicitud solo describe la pausa y puede usarse para llevar información que tu aplicación necesite para presentar el proceso interrumpido al usuario.

Úsala en un nodo. La respuesta volverá como carga útil:

```php
class ContentReviewNode extends Node
{
    public function __invoke(
        DraftEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): Event {
        // Genera el artículo una sola vez, de forma duradera (ver memoize abajo).
        $draft = $this->memoize('draft', fn (): string => ContentCreatorAgent::make()
            ->chat(new UserMessage($event->prompt))
            ->getMessage()
            ->getContent());

        // Suspender: envía el borrador HACIA AFUERA para revisión.
        $payload = $this->interrupt(
            new ContentReviewRequest('Revisa este artículo antes de publicarlo.', $draft)
        );

        // Reanudar: el texto editado vuelve ADENTRO como carga útil.
        $state->set('content', $payload['edited_content']);

        return new PublishEvent();
    }
}
```

Y en el lado de la aplicación:

```php
$state = $workflow->setWorkflowId('wk_id')->run();

if ($state->isInterrupted()) {
    /** @var ContentReviewRequest $request */
    $request = $state->getInterruptRequest();
    // renderiza $request->getContent() en la UI de tu editor...
}

// Más tarde, entrega el texto editado como carga útil:
$finalState = $workflow->signal(
    event: ContentReviewRequest::EVENT_NAME, 
    payload: ['edited_content' => $editedText]
)->run();
```

### Consumir la retroalimentación

La respuesta a la interrupción es la **carga útil** que pasas al método run(), y la forma principal de consumirla es el valor de retorno del verbo de suspensión, exactamente donde ocurrió la pausa:

```php
$payload = $this->interrupt(new ContentReviewRequest(...));
// reanudando: $payload es la respuesta entregada
```

Si necesitas bifurcar *antes de* llegar a la llamada interrupt — por ejemplo, para omitir por completo la lógica previa a la interrupción al reanudar — el nodo expone directamente el contexto de reanudación:

```php
public function __invoke(
    InputEvent $event, 
    WorkflowState $state,
    WorkflowResources $resources
): Event {
    // isResuming() es verdadero cuando esta ejecución del nodo fue activada por resume():
    // la carga útil entrante ha sido inyectada y es legible desde el principio.
    if ($this->isResuming()) {
        $payload = $this->getResumePayload();

        if (($payload['review_1'] ?? null) === 'approve') {
            $state->set('is_sufficient', true);
            return new OutputEvent();
        }
    }

    // Primera pasada (o rechazada): realiza el trabajo y suspende.
    $this->interrupt(
        new ApprovalRequest(
            message: '¿Debo continuar?',
            actions: [new Action('review_1', 'Responder revisión', $state->get('review'))],
        )
    );

    return new InputEvent(); // inalcanzable en la primera pasada; se alcanza en la reanudación rechazada
}
```

En la mayoría de los nodos no necesitarás esto: envuelve el trabajo previo a la interrupción en `memoize()` y deja que el nodo se vuelva a ejecutar. El trabajo memorizado se recupera, no se repite, y el estilo lineal `interrupt()`-devuelve-la-respuesta sigue siendo legible.

### Pasos duraderos y `memoize()`

Cuando un flujo de trabajo se reanuda, el nodo interrumpido **se vuelve a ejecutar desde el principio** — cualquier sentencia antes de la llamada interrupt se ejecutaría otra vez, volviendo a cobrar una llamada a un LLM o reenviando un correo. Dos capas de durabilidad te protegen.

**Entre nodos, obtienes durabilidad gratis.** Cada nodo se ejecuta como un paso duradero: los pasos completados se persisten y se omiten en la repetición. Los nodos *antes de* interrumpido nunca se vuelve a ejecutar.

**Dentro de un nodo, usa `memoize()`.** Ejecuta un closure y persiste su valor de retorno a mitad del nodo, antes de que el nodo devuelva. Cuando el nodo se vuelve a ejecutar — al reanudar, o después de un fallo — el valor registrado se devuelve *sin* volver a ejecutar el closure.

```php
class SentimentNode extends Node
{
    public function __invoke(
        ReviewEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): Event {
        // Se ejecuta como máximo una vez, incluso a través de reanudaciones/fallos de este nodo.
        $sentiment = $this->memoize('sentiment', fn (): SentimentResult => MyAgent::make()
            ->structured(new UserMessage($event->review), SentimentResult::class));

        if ($sentiment->isNegative()) {
            $payload = $this->interrupt(
                new ApprovalRequest(
                    message: 'Se detectó una reseña negativa. ¿Debería responderla?',
                    actions: [new Action('review_1', 'Responder reseña', $sentiment->content)],
                )
            );

            // Al reanudar, el $sentiment memorizado fue recuperado al instante arriba,
            // y interrupt() devolvió la respuesta aquí.
            if (($payload['review_1'] ?? null) === 'approve') {
                return new AnswerReviewEvent();
            }
        }

        return new SkipReviewEvent();
    }
}
```

`memoize()` toma:

* un **nombre**, único dentro del nodo (el framework lo acota automáticamente a la ejecución concreta del nodo);
* un **Closure** que envuelve el trabajo cuyo resultado debe sobrevivir a una nueva ejecución.

> `checkpoint()` de la versión principal anterior está obsoleto y ahora delega en `memoize()`. A diferencia del antiguo checkpoint en memoria, `memoize()` es **duradero**: el valor se persiste, así que también protege contra fallos — no solo interrupciones.
