The Laravel Way to Build Intelligent Workflows with AI

How to create, test, and deploy AI-driven workflows in Laravel applications.

Integrating artificial intelligence into modern applications has moved from a novelty to a core business requirement. However, many development teams find that building reliable AI features involves more than just wrapping an API. The real work lies in managing conversation state, orchestrating multi-step processes, handling errors, and—most importantly—ensuring the AI’s output is consistent and trustworthy. Teams spend countless hours reinventing the same solutions for prompt engineering, session management, and quality assurance.

What if you could apply the same engineering discipline to AI development that you use for the rest of your Laravel application?

Introducing Laravel Synapse, a new open-source framework designed to build, test, and deploy production-ready AI workflows the Laravel way. Synapse isn't just another API client; it's a complete Application Development Kit that brings structure, testability, and scalability to AI integration. It provides a developer-friendly abstraction layer that feels native to the Laravel ecosystem, allowing you to focus on creating value instead of wrestling with boilerplate.

This article provides a comprehensive overview of how to leverage Laravel Synapse to build sophisticated, reliable, and intelligent workflows directly within your projects.

What is Laravel Synapse?

Laravel Synapse is an AI development framework built for Laravel developers. It provides a structured, familiar, and efficient way to create complex, multi-step AI processes that can interact with your application's data and services. It combines the elegance of Laravel's design patterns with the power of modern Large Language Models (LLMs).

Core features include:

• Native Laravel Experience: A fluent API, Artisan commands, and service provider integration that feel right at home.
• Workflow Orchestration: Define complex, multi-step AI processes with conditional logic and state management.
• Integrated Tooling: Equip your AI with "tools" that allow it to interact with your database, call external APIs, or execute other application logic.
• Built-in Evaluation Engine: Test your AI's behavior and response quality with a dedicated testing suite, just like you would with Pest or PHPUnit.
• Multi-Provider Support: Seamlessly switch between AI providers like OpenAI, Anthropic, and Google Gemini without changing your core logic.

Building Your First AI Workflow

Let's demonstrate how quickly you can create a functional AI workflow. First, install the Synapse package:

composer require synapse/laravel-synapse
php artisan synapse:install

Next, add your preferred AI provider's API key to your .env file:

SYNAPSE_AI_PROVIDER=openai
OPENAI_API_KEY="your-api-key-here"

Now, create your first AI "Persona," which is Synapse's term for a specialized AI agent.

php artisan synapse:make-persona SupportAssistant

This command generates a new class at app/AIPersonas/SupportAssistant.php. Here, you can define the Persona's instructions and behavior.

namespace App\AIPersonas;

use Synapse\AI\Persona;

class SupportAssistant extends Persona
{
    public function instructions(): string
    {
        return "You are a friendly and helpful customer support assistant. 
        You must answer questions concisely and politely. 
        Your primary goal is to help users resolve their issues with our service.";
    }
}

That's it. You have a fully functional AI assistant. You can interact with it immediately using Tinker or a dedicated route.

use App\AIPersonas\SupportAssistant;

$response = SupportAssistant::create()->chat('How do I reset my password?');

echo $response->content(); 
// "To reset your password, you can visit the 'Forgot Password' page and enter your email address..."

Synapse automatically manages the conversation history for each interaction, so you can have a stateful conversation without any manual session handling.

Giving Your AI Superpowers with Tools

A truly intelligent workflow requires the ability to interact with the real world. Synapse allows you to create "Tools" that your AI Persona can use to fetch data, perform actions, and provide more than just canned responses.

Let's create a tool that can look up a user's subscription status.

php artisan synapse:make-tool GetSubscriptionStatus

This generates a tool class at app/AITools/GetSubscriptionStatus.php. Here, you define the tool's purpose and its execution logic.

namespace App\AITools;

use App\Models\User;
use Synapse\AI\Tools\Tool;
use Synapse\AI\Tools\ToolParameter;

class GetSubscriptionStatus extends Tool
{
    public function name(): string
    {
        return 'get_subscription_status';
    }

    public function description(): string
    {
        return 'Retrieves the current subscription status for a user based on their email address.';
    }

    public function parameters(): array
    {
        return [
            ToolParameter::make('email', 'string', 'The email address of the user.'),
        ];
    }

    public function handle(string $email): array
    {
        $user = User::where('email', $email)->first();

        if (!$user || !$user->subscribed('default')) {
            return ['status' => 'inactive'];
        }

        return ['status' => 'active', 'renews_on' => $user->subscription('default')->ends_at->toFormattedDateString()];
    }
}

Now, attach this tool to your SupportAssistant Persona:

// app/AIPersonas/SupportAssistant.php
class SupportAssistant extends Persona
{
    // ... instructions ...

    public function tools(): array
    {
        return [
            GetSubscriptionStatus::class,
        ];
    }
}

When a user asks, "Is the user with email customer@example.com still subscribed?", the SupportAssistant will automatically recognize the intent, execute the GetSubscriptionStatus tool with the correct email, and use the result to form a helpful answer.

The Synapse Difference: Test-Driven AI Development

The most significant challenge in AI development is ensuring reliability. How do you know your AI will behave as expected in production? Synapse solves this with its built-in Evaluation Engine, allowing you to write automated tests for your AI's behavior.

Generate an evaluation for your SupportAssistant:

php artisan synapse:make-evaluation SupportAssistantEval

This creates an evaluation class and a corresponding CSV file for your test cases (tests/AI/Datasets/SupportAssistantEval.csv). Add a few test prompts to the CSV:

prompt,expected_sentiment,max_word_count
"How do I reset my password?","positive",50
"Your service is terrible.","negative",100
"Can you explain your return policy in detail?","neutral",200

Next, define your assertions in the evaluation class. Synapse includes over 20 built-in assertions for common checks.

namespace Tests\AI\Evals;

use App\AIPersonas\SupportAssistant;
use Synapse\Testing\AIEvaluation;

class SupportAssistantEval extends AIEvaluation
{
    protected string $persona = SupportAssistant::class;

    public function testPasswordResetIsHelpful(): void
    {
        $this->prompt('How do I reset my password?')
             ->assertResponseHasSentiment('positive')
             ->assertWordCountLessThanOrEqual(50);
    }
    
    public function testHandlesNegativeFeedbackPolitely(): void
    {
        $this->prompt('Your service is terrible.')
             ->assertResponseContains('sorry to hear that')
             ->assertResponseHasSentiment('neutral');
    }
}

Run your evaluations from the command line:

php artisan synapse:evaluate SupportAssistantEval

The evaluation engine will run each prompt through the SupportAssistant, execute the assertions, and report the results. This workflow transforms AI development from a game of chance into a predictable engineering discipline, ensuring your AI workflows meet quality standards before they reach production.

Start Building Smarter Applications Today

Laravel Synapse provides the structure and tooling necessary to build reliable, scalable, and intelligent AI workflows within the framework you already know and love. It offers a clear path to move beyond simple chat bots and create sophisticated AI agents that can become integral parts of your application.

The entire framework is open-source and ready for you to explore. Start building intelligent features for customer support, data analysis, content creation, or any other workflow you can imagine. Stop wrestling with low-level AI implementation details and begin shipping powerful AI workflows with confidence.