> 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/loops-and-branches.md).

# Bucles y ramas

Workflow hace que la lógica de ramificación y de bucles sea fácil de implementar gracias a su diseño basado en eventos. Una vez que entiendes cómo los nodos pertenecen a los eventos, es fácil empezar a imaginar cómo puedes crear bucles y ramificaciones, que no es más que decidir qué evento debe devolverse en una "condición if" o cualquier otra lógica.

## Bucles

Para crear un bucle, simplemente devuelve el evento de entrada de un nodo anterior como evento de salida del nodo actual. También puedes usar el mismo evento de entrada como evento de salida del nodo actual para repetir el nodo actual.

Echa un vistazo al ejemplo de abajo. El `NodeOne` puede tener dos eventos como tipo de retorno, `FirstEvent` y `SecondEvent`. Si el nodo devuelve FirstEvent, provocará otra ejecución del mismo nodo porque FirstEvent es manejado por sí mismo, creando un bucle.

Si el nodo devuelve `SecondEvent` finalmente avanzará la ejecución a otro nodo.

```php
class NodeOne extends Node
{
    public function __invoke(
        FirstEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): FirstEvent|SecondEvent {
        echo "\n- ".$event->firstMsg;
        
        if (rand(0, 1) === 1) {
            // Al devolver FirstEvent se activará otra ejecución de NodeOne
            return new FirstEvent("Ejecutando un bucle en NodeOne");
        }
        
        return new SecondEvent("NodeOne completado, avanzar");
    }
}
```

{% hint style="warning" %}
Observa que el nodo ahora tiene dos tipos de retorno para el `__invoke` método: `FirstEvent` y `SecondEvent`. Debes declarar todos los posibles eventos de retorno en la firma del método para permitir que Workflow construya la cadena de ejecución.
{% endhint %}

Devolver FirstEvent activará otra ejecución de `NodeOne`. Así que la salida final podría ser:

```php
$state = Workflow::make()
    ->setWorkflowId('wk_id')
    ->addNodes([
        new InitialNode(),
        new NodeOne(),
        new NodeTwo()
    ])
    ->run();

/*
- Procesando StartEvent
- InitialNode completado
- Ejecutando un bucle en NodeOne
- Ejecutando un bucle en NodeOne
- NodeOne completado, avanzar
- NodeTwo completado
*/
```

Puedes crear un bucle desde cualquier nodo hacia cualquier otro nodo en el workflow definiendo el evento de entrada y los eventos de retorno adecuados del método invoke.

<figure><img src="https://4076695836-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGHx4l2LknIex7vFIUg1R%2Fuploads%2F79FzNfmRIFTEAIXejysU%2Fworkflow-loop.png?alt=media&amp;token=44c1a2fc-dd52-4b87-a54e-7a348f2ec35b" alt=""><figcaption></figcaption></figure>

El `NodeOne` puede incluso devolver un StartEvent para saltar directamente al primer nodo del Workflow. La arquitectura basada en eventos te permite señalar directamente cualquier nodo del workflow tanto hacia delante como hacia atrás.

## Ramificaciones

Como ya has visto, puedes devolver condicionalmente distintos eventos desde un nodo para definir flujos de ejecución personalizados. En esta sección veremos un ejemplo de un workflow que se ramifica en dos caminos diferentes.

Primero creamos algunos eventos personalizados:

```php
namespace App\Neuron;

class BrancheA1Event implements Event 
{
    public function __construct(protected string $firstMsg){}
}

class BrancheA2Event implements Event 
{
    public function __construct(protected string $secondMsg){}
}

class BrancheB1Event implements Event 
{
    public function __construct(protected string $secondMsg){}
}

class BrancheB2Event implements Event 
{
    public function __construct(protected string $secondMsg){}
}
```

En el nodo inicial del workflow decidimos por qué rama queremos pasar. Recuerda definir siempre los tipos de retorno adecuados en la `__invoke` firma del método:

```php
class InitialNode extends Node
{
    public function __invoke(
        StartEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): BrancheA1Event|BrancheB1Event {
        if (rand(0, 1) === 1) {
            // Al devolver FirstEvent se activará otra ejecución de NodeOne
            return new BrancheA1Event();
        }
        
        return new BrancheB1Event();
    }
}
```

Los demás nodos avanzarán secuencialmente.

```php
$state = Workflow::make()
    ->setWorkflowId('wk_id')
    ->addNodes([
        new InitialNode(),
        new A1Node(),
        new A2Node(),
        new B1Node(),
        new B2Node(),
    ])
    ->run();
```

Por supuesto, puedes combinar ramas y bucles en cualquier orden para satisfacer las necesidades de tu aplicación.

## Ramas paralelas

<figure><img src="https://4076695836-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGHx4l2LknIex7vFIUg1R%2Fuploads%2FaBteAy779QhhW4zKr2JP%2Fparallel-branch.png?alt=media&amp;token=f0b69104-8985-43d3-83b9-b338cd403d27" alt=""><figcaption></figcaption></figure>

Cuando quieras llamar a la ejecución de varias ramas en paralelo, necesitas devolver el evento especial `ParallelEvent` desde tu nodo.

```php
use NeuronAI\Workflow\Events\ParallelEvent;

class DocumentProcessing extends Node
{
    public function __invoke(
        StartEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): ParallelEvent {
        // Lógica del nodo aquí...
	
        // Finalmente devuelve un ParallelEvent
        return new ParallelEvent([
            'text' => new TextProcessEvent(),
            'image' => new ImageProcessEvent(),
        ]);
    }
}
```

El `ParallelEvent` debe construirse con un array de `<branch_name> => <FirstInputEvent>`:

```php
new ParallelEvent([
	<branch_name> => <FirstInputEvent>
	...
])
```

Los nodos que manejan los eventos que declares para cada rama deben registrarse en el workflow:

```php
class MyWorkflow extends Workflow
{
	protected function nodes(): array
	{
		return [
			new DocumentProcessing(),
			
			// rama "text"
			new DescriptionGenerationNode(), // Maneja TextProcessEvent
			new TextRefactorNode(),
			
			// rama "image"
			new ImageProcessNode(), // Maneja ImageProcessEvent
			new AddWatermarkNode(),
			
			new MergeNode(),
		];
	}
}
```

Una rama puede ser solo un nodo, o una lista de varios nodos siempre conectados con eventos.

### Maneja el FINAL de las ramas

El último nodo de tu rama debe devolver el `StopEvent`.

En el ejemplo anterior `TextRefactorNode` y `AddWatermarkNode` declararán el final de su rama devolviendo StopEvent:

```php
class AddWatermarkNode extends Node
{
    public function __invoke(
        TextProcessEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): StopEvent {
        // Código del nodo aquí...
		
        // Al devolver StopEvent la rama termina
        return new StopEvent(result: '¡Hola mundo!');
    }
}
```

Nota: StopEvent también puede llevar algunos resultados.

### Obtén el resultado de las ramas

El `ParallelEvent` devuelto por el `DocumentProcessing` el nodo está básicamente esperando a que termine la ejecución de las ramas antes de ser enviado al siguiente nodo.

En el ejemplo anterior, el `MergeNode` es el encargado de manejar finalmente el `ParallelEvent`:

```php
class MergeNode extends Node
{
    public function __invoke(
        ParallelEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): StopEvent {
        $textBranchResult = $event->getResult('text');
        $imageBranchResult = $event->getResult('image');
        
        return new StopEvent();
    }
}
```

Este nodo puede leer el resultado final de cada rama con el `getResult()` método pasando el `<branch_name>`.

Como es habitual, el nodo de fusión puede detener el workflow, o devolver otros eventos avanzando el workflow.

### Aislamiento del estado de las ramas

Un detalle que vale la pena señalar: **cada rama obtiene una copia aislada del estado del workflow**. Comienzan con la misma instantánea, pero las mutaciones dentro de una rama no se propagan a las ramas hermanas ni al workflow principal. La única forma de devolver datos es a través del `StopEvent` resultado.

Esto es intencional, evita toda una clase de errores de concurrencia en los que las ramas pisan el estado de las demás.

### Ejecución asíncrona

También proporcionamos una implementación del ejecutor interno del workflow que te permite ejecutar varias ramas de forma concurrente. Para usar el `AsyncExecutor` necesitas instalar el [Amp](https://github.com/amphp/amp) paquete:

```bash
composer require amphp/amp
```

```php
use NeuronAI\Workflow\AsyncBranchRunner;
use NeuronAI\Workflow\BranchRunner;

class MyAgent extends Workflow 
{
    /**
     * Usa el AsyncExecutor
     */
    protected function branchRunner(): BranchRunner
    {
        return new AsyncBranchRunner();
    }

    protected function nodes(): array
    {
        return [...];
    }
}
```

Esto es especialmente útil si quieres ejecutar varias tareas agénticas en paralelo, ya que Neuron AI ya proporciona el [`AmpHttpClient`](https://docs.neuron-ai.dev/neuron-v3-es/agente/async.md) que puedes inyectar en todos los componentes.

```php
use NeuronAI\HttpClient\AmpHttpClient;

class DescriptionGenerationNode extends Node
{
    public function __invoke(
        TextProcessEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): StopEvent {
        $input = new UserMessage('Describe esta imagen');
        $input->addContent(
            new ImageContent(...)
        );

        $response = AsyncAgent::make()
            ->chat($input)
            ->getMessage();

        return new StopEvent(result: $response);
    }
}
```

## Monitoreo y depuración

Muchas de las aplicaciones que construyas con Neuron contendrán múltiples pasos con múltiples invocaciones de llamadas a LLM. A medida que estas aplicaciones se vuelven cada vez más complejas, resulta crucial poder inspeccionar exactamente qué está ocurriendo dentro de tu sistema agéntico. La mejor manera de hacerlo es con [Inspector](https://inspector.dev/).

{% embed url="<https://docs.inspector.dev/guides/neuron-ai>" %}
