← Back to blog

AI Orchestration in Laravel: building a multi-agent system with queues, events, and predictive Redis caching

2026-07-26

AI Orchestration in Laravel: Building a Multi-Agent System with Queues, Events, and Predictive Redis Caching

Modern AI applications rarely rely on a single model call. Complex tasks—generating reports, analyzing documents, or executing multi-step reasoning—require coordinated specialized agents. In this guide, I'll show you how to build a production-ready multi-agent orchestration system in Laravel using queues, event sourcing, and predictive Redis caching.

The Architecture Challenge

When building AI systems, naive serial execution falls apart quickly. A research agent might take 30 seconds, while a summarization agent needs its output immediately. A validation agent must run after every generation. Dependencies are dynamic, failures are inevitable, and latency directly impacts user experience.

The solution: an orchestration layer that treats AI agents as asynchronous workers with explicit contracts, predictable retry semantics, and intelligent caching of intermediate results.

Core Components

Our system uses four Laravel primitives:

Step 1: Defining the Agent Contract

Every agent implements a consistent interface. This enforces serialization boundaries and enables the orchestrator to treat agents uniformly.

<?php

namespace App\AI\Contracts;

interface Agent
{
    public function getName(): string;
    
    public function getCapabilities(): array;
    
    public function accepts(Task $task): bool;
    
    public function execute(Task $task): Result;
    
    public function getEstimatedDuration(): int; // seconds
}

The Task value object carries everything an agent needs, including trace context for distributed debugging:

<?php

namespace App\AI;

final class Task
{
    public function __construct(
        public readonly string $traceId,
        public readonly string $correlationId,
        public readonly string $agentName,
        public readonly array $payload,
        public readonly array $dependencies = [],
        public readonly ?string $requiredBy = null,
        public readonly int $priority = 5,
    ) {}
}

Step 2: Queue Prioritization with Custom Job Pipes

Laravel's queue system supports priorities through multiple connections, but we need finer-grained control within a single queue. We implement a custom middleware that reorders jobs based on orchestration metadata.

<?php

namespace App\AI\Queue;

use Illuminate\Queue\Events\JobProcessing;
use Illuminate\Support\Facades\Redis;

class OrchestrationPriorityPipe
{
    public function handle($job, $next)
    {
        if ($job instanceof AgentJob) {
            $score = $this->calculatePriorityScore($job);
            
            Redis::zadd(
                'ai-orchestra:pending:' . $job->queue,
                $score,
                $job->getJobIdentifier()
            );
        }

        return $next($job);
    }

    private function calculatePriorityScore(AgentJob $job): float
    {
        $basePriority = $job->task->priority * 1000;
        
        $dependencyPenalty = count($job->task->dependencies) * 50;
        
        $deadlineUrgency = $job->deadline 
            ? max(0, 500 - (now()->diffInSeconds($job->deadline)))
            : 0;
        
        $cacheHitProbability = $this->predictCacheHit($job);
        $cacheScore = $cacheHitProbability > 0.7 ? -200 : 0;

        return $basePriority - $dependencyPenalty + $deadlineUrgency + $cacheScore;
    }

    private function predictCacheHit(AgentJob $job): float
    {
        $pattern = $this->extractPattern($job->task->payload);
        
        return (float) Redis::get("ai-orchestra:predict:{$pattern}") ?? 0.0;
    }
}

Register this in your queue configuration:

// config/queue.php
'redis' => [
    'driver' => 'redis',
    'connection' => 'default',
    'queue' => 'ai-agents',
    'retry_after' => 3600,
    'block_for' => null,
    'after_commit' => true,
],

// In AppServiceProvider
Queue::createPayloadUsing(function ($connection, $queue, $payload) {
    if (($payload['data']['command'] ?? null) instanceof AgentJob) {
        return ['priority_context' => $payload['data']['command']->toArray()];
    }
    return [];
});

Step 3: The Orchestrator with Event Sourcing

The orchestrator maintains state through Redis Streams, not database tables. This enables replay, time-travel debugging, and horizontal scaling without write contention.

<?php

namespace App\AI;

use Illuminate\Support\Facades\Redis;

class AgentOrchestrator
{
    private const STREAM_PREFIX = 'ai-orchestra:events:';
    private const CONSUMER_GROUP = 'orchestrator-workers';

    public function dispatch(Task $task): string
    {
        $executionId = uuid_create();
        
        $this->appendEvent($executionId, 'TaskDispatched', [
            'agent' => $task->agentName,
            'payload_hash' => hash('xxh3', json_encode($task->payload)),
            'dependencies' => $task->dependencies,
        ]);

        foreach ($this->resolveReadyAgents($executionId) as $readyTask) {
            dispatch(new AgentJob($readyTask))
                ->onQueue("ai-{$readyTask->agentName}")
                ->priority($readyTask->priority);
        }

        return $executionId;
    }

    public function handleAgentCompletion(string $executionId, Result $result): void
    {
        $this->appendEvent($executionId, 'AgentCompleted', [
            'agent' => $result->agentName,
            'output_hash' => hash('xxh3', json_encode($result->output)),
            'duration_ms' => $result->durationMs,
            'tokens_used' => $result->tokensUsed,
        ]);

        // Predictive: pre-stage downstream inputs
        $this->predictAndCacheDownstreamInputs($executionId, $result);

        // Evaluate next ready agents
        foreach ($this->resolveReadyAgents($executionId) as $readyTask) {
            // Check if result already cached from prediction
            if ($cached = $this->getPredictedResult($readyTask)) {
                $this->handleAgentCompletion($executionId, $cached);
                continue;
            }

            dispatch(new AgentJob($readyTask))
                ->onQueue("ai-{$readyTask->agentName}");
        }

        if ($this->isExecutionComplete($executionId)) {
            event(new ExecutionCompleted($executionId));
        }
    }

    private function appendEvent(string $executionId, string $type, array $data): void
    {
        Redis::xadd(
            self::STREAM_PREFIX . $executionId,
            '*',
            array_merge([
                'type' => $type,
                'timestamp' => hrtime(true),
                'orchestrator_node' => gethostname(),
            ], $data)
        );
    }

    private function resolveReadyAgents(string $executionId): array
    {
        $events = Redis::xrange(self::STREAM_PREFIX . $executionId, '-', '+');
        $completed = [];
        $dispatched = [];
        $defined = [];

        foreach ($events as $id => $event) {
            match ($event['type']) {
                'ExecutionDefined' => $defined[] = json_decode($event['agent_definition'], true),
                'TaskDispatched' => $dispatched[] = $event['agent'],
                'AgentCompleted' => $completed[] = $event['agent'],
            };
        }

        return array_filter($defined, function ($agent) use ($completed, $dispatched) {
            $depsSatisfied = empty(array_diff($agent['dependencies'], $completed));
            $notYetRun = !in_array($agent['name'], array_merge($dispatched, $completed));
            return $depsSatisfied && $notYetRun;
        });
    }
}

Step 4: Event Sourcing with Redis Streams

Redis Streams provide the backbone for our event log. Unlike simple pub/sub, streams persist messages and support consumer groups for parallel processing with acknowledgment.

<?php

namespace App\AI\Events;

use Illuminate\Support\Facades\Redis;

class StreamEventStore
{
    public function subscribeToExecution(string $executionId, callable $handler): void
    {
        $stream = 'ai-orchestra:events:' . $executionId;
        $consumer = gethostname() . '-' . getmypid();

        Redis::command('xgroup', [
            'create',
            $stream,
            'orchestrator-workers',
            '$',
            'mkstream'
        ]);

        while (true) {
            $messages = Redis::xreadgroup(
                'orchestrator-workers',
                $consumer,
                [$stream => '>'],
                1,
                5000
            );

            foreach ($messages[$stream] ?? [] as $id => $event) {
                try {
                    $handler($id, $event);
                    Redis::xack($stream, 'orchestrator-workers', [$id]);
                } catch (\Throwable $e) {
                    // Dead letter handling based on retry count
                    $retryCount = Redis::hincrby(
                        "ai-orchestra:retries:$executionId",
                        $id,
                        1
                    );

                    if ($retryCount > 3) {
                        Redis::xadd('ai-orchestra:dead-letters', '*', [
                            'original_stream' => $stream,
                            'event_id' => $id,
                            'error' => $e->getMessage(),
                        ]);
                        Redis::xack($stream, 'orchestrator-workers', [$id]);
                    }
                }
            }
        }
    }
}

Step 5: Predictive Redis Caching

The biggest latency win comes from predicting what your agents will need before they ask. After observing execution patterns, we cache probabilistically.

<?php

namespace App\AI\Cache;

use Illuminate\Support\Facades\Redis;

class PredictiveCache
{
    private const PREDICTION_TTL = 300; // 5 minutes

    public function predictAndStage(string $executionId, Result $result): void
    {
        $pattern = $this->buildPattern($result);
        $downstreamAgents = $this->getLikelyDownstream($result->agentName);

        foreach ($downstreamAgents as $agent => $probability) {
            if ($probability < 0.6) continue;

            $likelyInput = $this->transformForAgent($result->output, $agent);
            $cacheKey = $this->buildCacheKey($agent, $likelyInput);

            Redis::setex(
                "ai-orchestra:predicted:$cacheKey",
                self::PREDICTION_TTL,
                serialize($likelyInput)
            );

            // Update prediction model
            Redis::zincrby(
                "ai-orchestra:pattern:$pattern:downstream",
                1,
                $agent
            );
        }
    }

    public function getCachedResult(Task $task): ?Result
    {
        $cacheKey = $this->buildCacheKey($task->agentName, $task->payload);
        
        $cached = Redis::get("ai-orchestra:predicted:$cacheKey");
        if (!$cached) {
            // Try semantic similarity match for non-deterministic inputs
            return $this->fuzzyCacheLookup($task);
        }

        return unserialize($cached);
    }

    private function fuzzyCacheLookup(Task $task): ?Result
    {
        $embedding = $this->getEmbedding($task->payload);
        $candidates = Redis::ftsearch(
            'ai-orchestra:embeddings',
            "*=>[KNN 3 @embedding $embedding AS score]"
        );

        foreach ($candidates as $candidate) {
            if ($candidate['score'] > 0.92) {
                return Result::fromCache($candidate['result']);
            }
        }

        return null;
    }
}

Step 6: Defining an Execution Graph

Bring it together with a fluent definition API:

<?php

$execution = (new ExecutionBuilder('report-generation'))
    ->defineAgent('researcher', ResearchAgent::class)
    ->defineAgent('writer', WritingAgent::class, dependsOn: ['researcher'])
    ->defineAgent('fact-checker', FactCheckAgent::class, dependsOn: ['writer'])
    ->defineAgent('editor', EditorAgent::class, dependsOn: ['writer'])
    ->defineAgent('publisher', PublishAgent::class, dependsOn: ['editor', 'fact-checker'])
    ->withDeadline(now()->addMinutes(2))
    ->onFailure(function (FailureEvent $e) {
        // Escalate to human reviewer
        dispatch(new EscalateToHuman($e));
    })
    ->dispatch([
        'topic' => 'Laravel queue optimization patterns',
        'tone' => 'technical',
        'length' => 1500,
    ]);

Production Considerations

Monitoring with Stream Inspectors

<?php

// Artisan command for real-time execution monitoring
class MonitorExecution extends Command
{
    public function handle()
    {
        $executionId = $this->argument('execution');

        Redis::xread([
            "ai-orchestra:events:$executionId" => '$'
        ], 0, function ($id, $event) {
            $type = str_pad($event['type'], 20);
            $agent = $event['agent'] ?? '-';
            $elapsed = (hrtime(true) - $event['timestamp']) / 1e6;

            $this->line("<fg=cyan>{$type}</> <fg=yellow>{$agent}</> +{$elapsed}ms");
        });
    }
}

Conclusion

Building multi-agent AI systems in Laravel requires thinking beyond simple job dispatch. By combining Redis Streams for event sourcing, prioritized queues for scheduling, and predictive caching for latency reduction, you create an orchestration layer that scales with complexity rather than collapsing under it.

The patterns here—explicit contracts, event-sourced state, and probabilistic optimization—apply equally to other orchestration problems. Start with a single agent, add the stream logging, then layer in prediction. The infrastructure investment pays dividends as your AI capabilities grow.