# LaraGraph：为Laravel打造的LangGraph风格状态化工作流引擎

> 受LangGraph启发的PHP工作流引擎，将循环图结构适配到Laravel的无状态架构中，支持多智能体流水线、人机协作流程和并行任务处理。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-11T23:15:52.000Z
- 最近活动: 2026-04-11T23:23:29.463Z
- 热度: 161.9
- 关键词: LaraGraph, Laravel, LangGraph, 工作流引擎, PHP, 多智能体, 人机协作, 队列, 状态管理
- 页面链接: https://www.zingnex.cn/forum/thread/laragraph-laravellanggraph
- Canonical: https://www.zingnex.cn/forum/thread/laragraph-laravellanggraph
- Markdown 来源: ingested_event

---

## 项目背景与定位

在Python生态中，LangGraph已经成为构建复杂LLM工作流的事实标准。它通过有向图模型支持循环、分支、并行等复杂执行模式，为AI代理工作流提供了强大的编排能力。然而，PHP/Laravel生态长期缺乏同等级别的工作流解决方案。

LaraGraph的诞生填补了这一空白。它明确以LangGraph为灵感来源，将循环图工作流的概念引入PHP世界，同时充分考虑了Laravel的架构特点——特别是其无状态请求模型和队列系统。这种"移植而非照搬"的思路，使得LaraGraph既保留了LangGraph的核心能力，又完美融入了Laravel的技术生态。

## 核心概念与术语

LaraGraph采用了一套清晰的术语体系来描述工作流：

- **Node（节点）**：工作单元，接收当前状态并返回状态变更
- **Edge（边）**：节点之间的有向连接，支持条件判断
- **State（状态）**：普通PHP数组，在节点执行过程中累积变更
- **Pointer（指针）**：跟踪当前运行中节点的位置
- **WorkflowRun（工作流运行）**：单次工作流执行的持久化记录

这种建模方式与LangGraph高度一致，降低了Python开发者迁移到PHP的学习成本。

## 架构设计：适配PHP的无状态特性

PHP的传统执行模型是无状态的——每个HTTP请求都是独立的进程，请求结束后状态即被销毁。这与Python常驻内存的服务模型有着本质区别。LaraGraph的设计巧妙地解决了这一矛盾：

### 数据库持久化

每个WorkflowRun都是数据库中的一条记录，包含当前状态、活跃节点指针和执行状态。这使得工作流可以在任意请求边界处暂停，并在后续请求中恢复。

### 队列驱动执行

节点执行完全由队列驱动。每个节点作为一个独立的ExecuteNode作业分发到队列，这意味着：
- 并行分支可以真正并发执行，利用整个工作池的计算能力
- 长时间运行的节点不会阻塞Web请求
- 失败节点可以自动重试，具备天然的容错能力

### 归约器模式

状态合并采用归约器（Reducer）模式，提供了三种策略：

1. **SmartReducer（默认）**：列表数组追加，标量和关联数组覆盖
2. **MergeReducer**：所有键的深层递归合并
3. **OverwriteReducer**：浅层array_merge，总是覆盖

SmartReducer是大多数代理工作流的合理默认选择——消息历史自然累积，而状态、分数等标量值简单覆盖。

## 工作流构建API

LaraGraph提供了流畅的Builder API来定义工作流：

```php
$workflow = Workflow::create()
    ->addNode('fetch', FetchNode::class)
    ->addNode('transform', TransformNode::class)
    ->addNode('store', StoreNode::class)
    ->transition(Workflow::START, 'fetch')
    ->transition('fetch', 'transform')
    ->transition('transform', 'store')
    ->transition('store', Workflow::END);
```

这种链式调用风格符合Laravel开发者的习惯，代码可读性极佳。

### 条件边与分支

支持基于闭包或Symfony表达式语言的动态路由：

```php
// 闭包方式
->transition('classify', 'approve', fn(array $state) => $state['score'] > 50)
->transition('classify', 'reject', fn(array $state) => $state['score'] <= 50)

// 表达式方式（可序列化，适合快照工作流）
->transition('classify', 'approve', "state['score'] > 50")
->transition('classify', 'reject', "state['score'] <= 50")
```

表达式语言内置了丰富的函数：last、first、count、empty、get（点号安全访问）、has_value等，足以应对大多数路由逻辑。

### 并行执行与扇出

通过从同一源节点添加多个转移边，可以实现并行分支：

```php
->transition('split', 'branch-a')
->transition('split', 'branch-b')
```

branch-a和branch-b将作为独立的队列作业并发执行。

对于动态扇出（运行时才知道需要多少并行分支），可以使用Send对象：

```php
->branch('planner', function(array $state): array {
    return array_map(
        fn(string $query) => new Send('worker', ['query' => $query]),
        $state['queries']
    );
}, targets: ['worker'])
```

每个Send分发一个独立的ExecuteNode作业，目标节点通过$context->isolatedPayload接收payload。

## 人机协作（Human-in-the-Loop）

LaraGraph对人工介入提供了原生支持，这是许多业务场景的关键需求：

### 执行前中断

```php
->addNode('review', ReviewNode::class)
->interruptBefore('review');
```

在节点执行前暂停工作流，等待人工审核。恢复后节点正常执行。

### 执行后中断

```php
->interruptAfter('drafter');
```

在节点执行后、输出边评估前暂停，适合需要人工检查结果的场景。

### 恢复与状态注入

```php
Laragraph::resume($run->id, ['approved' => true]);
```

恢复时可以合并额外状态，实现人工决策的注入。

## 与Laravel AI生态的集成

LaraGraph提供了与Prism（Laravel的LLM集成包）的深度集成：

- **PrismNode**：直接封装Prism LLM调用
- **ToolNode**：支持工具使用代理
- **自动工具循环**：处理LLM的工具调用和结果反馈循环
- **手动工具路由**：开发者完全控制工具调用流程

此外，AsGraphNode trait允许将任何Laravel AI的生成器转换为LaraGraph节点，实现无缝集成。

## 适用场景分析

LaraGraph特别适合以下PHP/Laravel项目：

1. **内容审核流水线**：抓取→AI分类→人工审核→发布/拒绝
2. **多步骤数据处理**：ETL流程、数据清洗、格式转换
3. **AI代理编排**：多代理协作、工具调用链、RAG流程
4. **审批工作流**：多级审批、条件分支、会签/或签
5. **定时任务编排**：复杂的依赖关系、失败重试、超时处理

对于简单的顺序执行或纯CRUD操作，LaraGraph可能显得过于重型。但当业务逻辑涉及复杂的分支、并行、人工介入时，它提供了必要的抽象和基础设施。

## 总结

LaraGraph是PHP生态中一个令人振奋的新成员。它证明了即使是与Python有着不同执行模型的PHP，同样可以支持复杂的状态化工作流。通过巧妙利用Laravel的队列系统和数据库层，LaraGraph实现了与LangGraph相似的能力，同时保持了与Laravel生态的深度融合。

对于需要在Laravel项目中构建AI工作流、审批流程或复杂数据管道的开发者，LaraGraph提供了一个值得认真考虑的解决方案。它的设计既借鉴了Python生态的先进经验，又充分尊重了PHP的技术现实，是跨语言思想迁移的一个成功案例。