Custom Modules & Synchronization

1. Custom PHP Code Module (php_code)

Use the Artisan generator command to create a new PHP Code Module in app/Workflows/Modules/Custom:

php artisan ai-suite:makePhpCodeModule MyCustomModule

The generated class implements Tokomono\AiSuite\Workflows\Contracts\WorkflowPhpCodeModuleInterface and will automatically appear in the PHP Code node dropdown inside the Workflow Editor:

<?php

namespace App\Workflows\Modules\Custom;

use Tokomono\AiSuite\Workflows\Contracts\WorkflowPhpCodeModuleInterface;
use Tokomono\AiSuite\Workflows\Data\WorkflowContextDto;

class MyCustomModule implements WorkflowPhpCodeModuleInterface
{
    public function handle(WorkflowContextDto $context, mixed $previousOutput = null): mixed
    {
        // 1. Read text or structured data from the previous step ($previousOutput is a WorkflowPayloadDto)
        $inputText = (string) $previousOutput;
        $inputArray = $previousOutput?->data ?? [];

        // 2. Read or mutate global variables
        $orderId = $context->globalVariables['order_id'] ?? null;
        $context->globalVariables['processed'] = true;

        // 3. Return a string or an array for the next step
        // Returning an array allows downstream If/Else Statement nodes to filter on 'matchKey'
        return [
            'status' => 'AGENT',
            'score' => 95,
        ];
    }

    public static function getName(): string
    {
        return 'My Custom Module';
    }
}

---

2. Pre-defined Response Module (response)

Create a class implementing Tokomono\AiSuite\Workflows\Contracts\WorkflowResponseModuleInterface (for example in app/Workflows/Modules/Responses). It will automatically appear in the Pre-defined Response node dropdown inside the Workflow Editor:

<?php

namespace App\Workflows\Modules\Responses;

use Tokomono\AiSuite\Workflows\Contracts\WorkflowResponseModuleInterface;
use Tokomono\AiSuite\Workflows\Data\WorkflowContextDto;

class StandardRejectionResponse implements WorkflowResponseModuleInterface
{
    public function handle(WorkflowContextDto $context, mixed $previousOutput = null): string
    {
        $name = $context->globalVariables['name'] ?? 'customer';

        return "Dear {$name}, unfortunately this request is not covered by your policy.";
    }

    public static function getName(): string
    {
        return 'Standard Rejection';
    }
}

---

3. Workflow Classes & Database Synchronization

Every workflow class in app/Ai/Workflows implements Tokomono\AiSuite\Contracts\WorkflowInterface:

• getHash(): string — Unique 8-character identifier used to synchronize the file with the database (sync_hash).
• getName(): string — Display name in the Workflows UI.
• getDescription(): ?string — Optional workflow description.
• isTest(): bool — Indicates whether the workflow is a test workflow.
• getDefinition(): array — Returns the graph definition containing 'start_node', 'nodes', and 'edges'.

Synchronizing Workflows with the Database

Whenever you add or modify a workflow class in code, synchronize it with the database by running:

php artisan ai:sync-workflows

This command scans all directories configured in config('ai-suite.workflow_directories') (by default app/Ai/Workflows), creates missing Workflow records, and automatically publishes a new WorkflowVersion whenever the PHP file's md5_file hash changes. Conversely, when you click Publish in the Visual Workflow Editor in local development, the PHP file's getDefinition() method is updated automatically.