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 类定义：

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'),
        ];
    }
}

执行工作流非常简单：

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

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

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

2. 工具调用系统

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

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()];
    }
}

工具注册：

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

3. 实时 SSE 通信

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

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('帮我查一下订单');

后端实现：

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

实际应用场景

智能客服系统

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

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 辅助创作功能：

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'),
        ];
    }
}

数据分析助手

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

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']),
        ];
    }
}

安装与配置

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

环境变量配置：

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

运行迁移：

php artisan migrate

技术亮点

与 Laravel 生态的深度集成

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

性能优化

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

适用场景

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

结语

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