# Laravel Agent Runner：Laravel 与 AI 智能体的桥梁

> Laravel Agent Runner 是一个开源扩展包，让 Laravel 应用能够无缝集成 Agent Runner 微服务，实现 AI 智能体工作流管理、工具调用和实时 SSE 通信。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-13T13:46:31.000Z
- 最近活动: 2026-04-13T13:52:47.355Z
- 热度: 0.0
- 关键词: Laravel, PHP, AI Agent, 智能体集成, SSE, 微服务
- 页面链接: https://www.zingnex.cn/forum/thread/laravel-agent-runner-laravel-ai
- Canonical: https://www.zingnex.cn/forum/thread/laravel-agent-runner-laravel-ai
- Markdown 来源: ingested_event

---

# Laravel Agent Runner：Laravel 与 AI 智能体的桥梁

## 项目背景

Laravel 作为 PHP 生态中最流行的 Web 框架之一，拥有庞大的开发者社区和丰富的生态系统。然而，在 AI 智能体（AI Agent）集成方面，PHP/Laravel 生态相比 Python 或 Node.js 仍显不足。

Laravel Agent Runner 的出现填补了这一空白。它为 Laravel 开发者提供了一条直通 AI 智能体世界的高速通道，无需深入了解底层协议或复杂的微服务架构，就能在 Laravel 应用中实现强大的智能体功能。

## 核心能力概览

这个扩展包主要解决三个核心问题：

1. **工作流编排**：如何在 Laravel 中定义和管理 AI 智能体的执行流程
2. **工具调用**：如何让智能体安全地调用 Laravel 应用中的业务逻辑
3. **实时通信**：如何实现智能体与前端之间的实时双向通信

## 架构设计：解耦与集成

### 微服务架构的优势

Laravel Agent Runner 采用微服务架构，将智能体运行引擎与 Laravel 应用分离：

**Agent Runner 微服务**：
- 负责智能体的生命周期管理
- 处理 LLM 调用和上下文维护
- 执行工具调用路由
- 管理并发和队列

**Laravel 扩展包**：
- 提供与微服务通信的客户端
- 封装 Laravel 风格的 API
- 处理身份验证和安全
- 集成 Laravel 的事件系统和队列

这种分离带来了几个好处：
- **技术栈灵活**：微服务可以用最适合的语言（如 Python）实现
- **独立扩展**：可以根据负载单独扩展微服务
- **故障隔离**：智能引擎的问题不会影响主应用
- **多应用共享**：多个 Laravel 应用可以共享同一个智能体服务

### 安全通信机制

安全是 AI 集成的关键考量。Laravel Agent Runner 提供了多层安全保障：

**身份验证**：
- API Key 认证：微服务与 Laravel 之间的调用验证
- JWT Token：用户级别的权限控制
- 签名验证：防止请求篡改

**授权控制**：
- 基于 Laravel Gate 的细粒度权限
- 工具级别的调用白名单
- 用户级别的智能体访问控制

**数据保护**：
- 敏感数据脱敏
- 日志审计
- 请求限流

## 功能详解

### 1. 智能体工作流管理

在 Laravel 中，工作流通过直观的 PHP 类定义：

```php
use LaravelAgentRunner\Workflow;
use LaravelAgentRunner\Step;

class CustomerSupportWorkflow extends Workflow
{
    public function define(): array
    {
        return [
            Step::make('analyze')
                ->prompt('分析用户问题: {user_input}')
                ->model('gpt-4')
                ->tools(['search_kb', 'check_order']),
            Step::make('respond')
                ->prompt('基于分析结果生成回复')
                ->dependsOn('analyze'),
        ];
    }
}
```

执行工作流非常简单：

```php
$workflow = new CustomerSupportWorkflow();
$run = $workflow->start(['user_input' => '订单状态查询']);
$result = $run->wait();
```

对于长时间运行的任务，可以放入队列异步处理：

```php
$workflow->dispatch(['user_input' => $message])->onQueue('agents');
```

### 2. 工具调用系统

工具调用是智能体与外部世界交互的桥梁：

```php
use LaravelAgentRunner\Tool;

class SearchKnowledgeBaseTool extends Tool
{
    protected string $name = 'search_kb';
    protected string $description = '搜索知识库';
    
    public function parameters(): array
    {
        return [
            'query' => ['type' => 'string', 'description' => '搜索词'],
            'limit' => ['type' => 'integer', 'default' => 5],
        ];
    }
    
    public function execute(array $args): array
    {
        $results = KnowledgeBase::search($args['query'])->limit($args['limit'])->get();
        return ['results' => $results->toArray()];
    }
}
```

工具注册：

```php
AgentRunner::registerTool(SearchKnowledgeBaseTool::class);
AgentRunner::registerTool(CheckOrderStatusTool::class);
```

### 3. 实时 SSE 通信

Server-Sent Events 是实现智能体实时响应的理想选择：

```javascript
const client = new AgentRunnerClient({
    endpoint: '/api/agent-stream',
    token: userToken,
});

client.on('token', (data) => appendToChat(data.content));
client.on('tool_call', (data) => showToolStatus(data.tool));
client.on('complete', () => enableInput());

client.sendMessage('帮我查一下订单');
```

后端实现：

```php
class AgentController extends Controller
{
    public function stream(Request $request)
    {
        $workflow = new CustomerSupportWorkflow();
        return $workflow->stream([
            'user_input' => $request->input('message'),
            'user_id' => auth()->id(),
        ]);
    }
}
```

## 实际应用场景

### 智能客服系统

构建能够理解用户问题、查询订单、处理退换货的智能客服：

```php
class CustomerServiceWorkflow extends Workflow
{
    public function define(): array
    {
        return [
            Step::make('classify')->prompt('分类意图: {input}'),
            Step::make('handle')
                ->tools(['query_order', 'process_refund'])
                ->condition(fn($ctx) => $ctx->get('intent') !== 'greeting'),
        ];
    }
}
```

### 内容生成助手

为 CMS 系统添加 AI 辅助创作功能：

```php
class ContentWorkflow extends Workflow
{
    public function define(): array
    {
        return [
            Step::make('research')->tools(['search_docs']),
            Step::make('outline')->dependsOn('research'),
            Step::make('write')->dependsOn('outline'),
            Step::make('review')->dependsOn('write'),
        ];
    }
}
```

### 数据分析助手

让智能体查询数据库、生成报表、提供业务洞察：

```php
class DataAnalysisWorkflow extends Workflow
{
    public function define(): array
    {
        return [
            Step::make('understand')->prompt('理解需求: {question}'),
            Step::make('fetch')->tools(['execute_sql']),
            Step::make('analyze'),
            Step::make('visualize')->tools(['generate_chart']),
        ];
    }
}
```

## 安装与配置

```bash
composer require angel010/laravel-agent-runner
php artisan vendor:publish --tag=agent-runner-config
```

环境变量配置：

```env
AGENT_RUNNER_URL=http://agent-runner:8080
AGENT_RUNNER_API_KEY=your-api-key
AGENT_RUNNER_WEBHOOK_SECRET=your-secret
```

运行迁移：

```bash
php artisan migrate
```

## 技术亮点

### 与 Laravel 生态的深度集成

- **Eloquent 集成**：智能体可以直接操作模型
- **队列集成**：原生支持 Laravel 队列系统
- **事件系统**：智能体执行触发 Laravel 事件
- **缓存集成**：自动缓存工具调用结果
- **日志集成**：详细的执行日志

### 性能优化

- 连接池管理
- 请求批处理
- 智能重试机制
- 响应缓存

## 适用场景

- 已有 Laravel 项目需要添加 AI 能力
- 团队熟悉 PHP/Laravel，希望快速集成智能体
- 需要与现有业务系统深度集成的 AI 应用
- 对数据安全有高要求的企业应用

## 结语

Laravel Agent Runner 为 PHP 开发者打开了 AI 智能体的大门。它既保持了 Laravel 的优雅开发体验，又提供了企业级的智能体集成能力。对于 Laravel 生态的用户来说，这是目前最成熟的智能体集成方案之一。