> 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-zh/gong-zuo-liu/loops-and-branches.md).

# 循环与分支

由于其事件驱动设计，Workflow 让分支和循环逻辑变得很容易实现。一旦你理解了节点如何归属于事件，就很容易开始想象如何创建循环和分支；本质上只是决定在“if 条件”或其他逻辑中应该返回哪个事件。

## 循环

要创建循环，只需将前一个节点的进入事件作为当前节点的退出事件返回。你也可以使用与当前节点相同的进入事件作为其退出事件，从而让当前节点循环执行。

看看下面的示例。这个 `NodeOne` 可以将两个事件作为返回类型， `FirstEvent` 和 `SecondEvent`. 如果节点返回 FirstEvent，就会触发同一个节点的再次执行，因为 FirstEvent 由它自己处理，从而形成一个循环。

如果节点返回 `SecondEvent` 它最终会将执行推进到另一个节点。

```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) {
            // 返回 FirstEvent 会触发 NodeOne 的再次执行
            return new FirstEvent("在 NodeOne 上运行循环");
        }
        
        return new SecondEvent("NodeOne 完成，向前推进");
    }
}
```

{% hint style="warning" %}
注意，这个节点现在为以下内容有两个返回类型： `__invoke` 方法： `FirstEvent` 和 `SecondEvent`. 你必须在方法签名中声明所有可能的返回事件，才能让 Workflow 构建执行链。
{% endhint %}

返回 FirstEvent 会触发对以下内容的再次执行： `NodeOne`。因此最终输出可能是：

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

/*
- 处理 StartEvent
- InitialNode 完成
- 在 NodeOne 上运行循环
- 在 NodeOne 上运行循环
- NodeOne 完成，向前推进
- NodeTwo 完成
*/
```

通过定义 invoke 方法中合适的输入事件和返回事件，你可以在工作流中从任意节点创建到任意其他节点的循环。

<figure><img src="https://99736354-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>

该 `NodeOne` 甚至可以返回一个 StartEvent，直接跳转到 Workflow 的第一个节点。事件驱动架构允许你直接指向工作流中的任意节点，无论是向前还是向后。

## 分支

正如你已经看到的，你可以根据条件从节点返回不同的事件，以定义自定义的执行流程。在这一部分，我们将看到一个分支到两个不同路径的工作流示例。

首先，让我们创建一些自定义事件：

```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){}
}
```

在工作流的初始节点中，我们决定要走哪条分支。记得始终在 `__invoke` 方法签名中定义合适的返回类型：

```php
class InitialNode extends Node
{
    public function __invoke(
        StartEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): BrancheA1Event|BrancheB1Event {
        if (rand(0, 1) === 1) {
            // 返回 FirstEvent 会触发 NodeOne 的再次执行
            return new BrancheA1Event();
        }
        
        return new BrancheB1Event();
    }
}
```

其他节点将按顺序向前执行。

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

当然，你可以按任意顺序组合分支和循环，以满足应用的需求。

## 并行分支

<figure><img src="https://99736354-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>

当你想并行调用多个分支的执行时，需要从你的节点返回特殊事件 `ParallelEvent` ，从你的节点中返回。

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

class DocumentProcessing extends Node
{
    public function __invoke(
        StartEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): ParallelEvent {
        // 节点逻辑在这里...
	
        // 最后返回一个 ParallelEvent
        return new ParallelEvent([
            'text' => new TextProcessEvent(),
            'image' => new ImageProcessEvent(),
        ]);
    }
}
```

该 `ParallelEvent` 必须使用一个数组来构造 `<branch_name> => <FirstInputEvent>`:

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

处理你为每个分支声明的事件的节点，必须注册到工作流中：

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

一个分支可以只是一个节点，也可以是始终通过事件连接的多个节点列表。

### 处理分支的结束

你分支中的最后一个节点必须返回框架内置的 `StopEvent`.

在上面的示例中 `TextRefactorNode` 和 `AddWatermarkNode` 将通过返回 StopEvent 来声明其分支结束：

```php
class AddWatermarkNode extends Node
{
    public function __invoke(
        TextProcessEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): StopEvent {
        // 节点代码在这里...
		
        // 返回 StopEvent，分支结束
        return new StopEvent(result: '你好，世界！');
    }
}
```

注意：StopEvent 也可以携带一些结果。

### 获取分支结果

该 `ParallelEvent` 由 `DocumentProcessing` 节点基本上是在等待分支执行结束，然后才会被传递到下一个节点。

在上面的示例中， `MergeNode` 负责最终处理 `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();
    }
}
```

这个节点可以通过 `getResult()` 方法传入 `<branch_name>`.

与往常一样，合并节点可以停止工作流，或者返回其他事件让工作流继续向前。

### 分支状态隔离

有一点值得注意： **每个分支都会获得工作流状态的一个隔离副本**。它们从同一个快照开始，但分支内部的修改不会传播到兄弟分支或主工作流。把数据传回去的唯一方式是通过 `StopEvent` result。

这样设计是有意为之，它避免了大量并发 bug，即分支相互覆盖彼此的状态。

### 异步执行

我们还提供了内部工作流执行器的实现，允许你并发运行多个分支。要使用 `AsyncExecutor` ，你需要安装 [Amp](https://github.com/amphp/amp) 包：

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

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

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

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

如果你想并行运行多个智能体任务，这尤其有用，因为 Neuron AI 已经提供了 [`AmpHttpClient`](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/async.md) ，你可以将其注入到所有组件中。

```php
use NeuronAI\HttpClient\AmpHttpClient;

class DescriptionGenerationNode extends Node
{
    public function __invoke(
        TextProcessEvent $event, 
        WorkflowState $state,
        WorkflowResources $resources
    ): StopEvent {
        $input = new UserMessage('描述这张图片');
        $input->addContent(
            new ImageContent(...)
        );

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

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

## 监控与调试

你使用 Neuron 构建的许多应用都将包含多个步骤以及多次 LLM 调用。随着这些应用变得越来越复杂，能够检查你的智能体系统内部究竟发生了什么就变得至关重要。做到这一点的最佳方式是使用 [检查器](https://inspector.dev/).

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