Tokomono
Ai Suite
3. Workflows

Available Modules

Available Workflow Modules

Every step (node) in a workflow is executed by a dedicated Workflow Module. All available modules are registered in config/ai-suite.php under workflow_modules and are instantiated at runtime by the WorkflowEngine.

You can drag, connect, and test all of these modules live in the Visual Workflow Editor.

Type (type) UI Label Class Live Example Purpose
start Start Point StartModule Claim Handler Entry point of the workflow; reads the initial question from global variables.
agent Agent AgentModule Claim Handler Executes a laravel/ai Agent with dynamic prompt interpolation.
php_code PHP Code PhpCodeModule Claim Handler Runs a custom PHP class (e.g., API calls, calculations, state mutations).
if_else If / Else IfElseModule Claim Handler Evaluates the previous output against connected statement nodes to branch execution.
statement Statement StatementModule Claim Handler Defines a conditional branch (match) or fallback (else) connected to an if_else node.
enum Enum EnumModule Enum Tester Prompts an AI Agent to choose strictly from a PHP Enum's cases.
enum_value Enum Value EnumValueModule Enum Tester Routes execution based on the selected Enum case from an enum node.
response Pre-defined Response ResponseModule Claim Handler Returns a static or dynamically formatted string response from a PHP class without an LLM call.
human_in_the_loop Human in the Loop HumanInTheLoopModule Claim Handler Flags that human review is required and assigns it to a reviewer.
stop Stop Point StopModule LLM as a Judge Explicitly terminates the workflow execution path.

1. Start Point (start) — StartModule

Every workflow begins at the start node (specified via 'start_node' in the workflow definition).

  • What it does: Reads $context->globalVariables['question'] and outputs that value to the first connected node. If 'question' is not present in globalVariables, it defaults to outputting 'Workflow Started'.
  • Configuration (config): None.

2. Agent (agent) — AgentModule

Executes an AI Agent built with the Laravel AI SDK (Laravel\Ai\Contracts\Agent). You can manage all available agents in the Agents Dashboard.

  • What it does:
    1. Prompt resolution: Uses config.prompt if provided. If config.prompt is empty, it automatically uses the string output of the previous step ((string) $context->getPreviousStepOutput()).
    2. Variable interpolation:
      • Replaces {{variable}} with $context->globalVariables['variable'].
      • Replaces {{node_id}} with the output of an earlier node from $context->getHistory('node_id') (see LLMAsAJudgeWorkflow where agen_000000003 compares {{agen_000000001}} and {{agen_000000002}}).
    3. Conversation memory (when a user is authenticated via auth()->check()):
      • When $context->clearConversation === true: starts a fresh conversation via $agent->forUser(auth()->user()) and immediately resets $context->clearConversation = false so subsequent agents in the same workflow run continue within that newly created conversation.
      • When $context->clearConversation === false: continues the user's latest conversation via $agent->continueLastConversation(auth()->user()).
    4. Execution: Calls $agent->prompt($finalPrompt):
      • If the agent implements HasStructuredOutput, $response->toArray() is returned as structured array data (ideal for downstream if_else routing).
      • Otherwise, ['content' => $response->text] is returned.
  • Configuration (config):
    • agentClass (string, required): Fully qualified class name of the Agent (e.g., 'App\Ai\Agents\ClaimsHandlerAgent' — view agent in UI).
    • prompt (string|null, optional): Prompt template supporting {{...}} placeholders.
[
    'id' => 'node_agent',
    'type' => 'agent',
    'config' => [
        'agentClass' => 'App\Ai\Agents\ClaimsHandlerAgent',
        'prompt' => 'Answer nicely based on: {{node_php}}',
    ],
]

3. PHP Code (php_code) — PhpCodeModule

Executes custom PHP business logic inside a workflow (such as database lookups, external API requests, or data transformations). See node_php in Claim Handler or phpc_000000007 in LLM as a Judge.

  • What it does: Resolves the configured actionClass from the Laravel service container and calls $action->handle($context, $previousOutput).
    • Inside handle(), you can read and mutate $context->globalVariables.
    • The value returned by handle() (a string, array, or object) is wrapped in a WorkflowPayloadDto and passed to the next node.
  • Configuration (config):
    • actionClass (string, required): Fully qualified class name implementing Tokomono\AiSuite\Workflows\Contracts\WorkflowPhpCodeModuleInterface (e.g., 'App\Workflows\Modules\Custom\FormatNameToUppercaseModule').

4. If / Else (if_else) & Statement (statement)

The if_else module and statement module work together to create conditional branches in your workflow. You can inspect a working setup in the Claim Handler Workflow (node_if_else connected to stmt_test, stmt_hitl, and stmt_else).

How they work together

  1. IfElseModule (if_else): Acts as a decision junction. It takes the output of the previous step ($context->getPreviousStepOutput()) and passes it as nextRoute to the WorkflowEngine.
  2. StatementModule (statement): You connect one or more statement nodes to the outgoing edges of an if_else node. The WorkflowEngine evaluates each connected statement node:
    • statementType: 'match': Compares the previous step's output against matchValue using the configured operator.
      • When matchKey is empty (null or ''), it compares against the full string output.
      • When matchKey is set (e.g., 'score' or 'user.status'), the engine uses data_get() to extract that key from the previous step's structured array output.
      • Numeric values are automatically cast to int/float before comparison.
    • statementType: 'else': Selected as the fallback route when no 'match' statement evaluates to true.
  3. Error handling: If no match statement matches and no else statement is connected, execution stops and sets $context->error = 'Could not make decision in IF_ELSE module'.
  • Configuration for if_else (config):
    • hasElse (bool, default true): Indicates whether the If/Else node includes an else fallback branch.
  • Configuration for statement (config):
    • statementType (string): 'match' (conditional check) or 'else' (fallback branch).
    • matchKey (string|null): Array key (supports dot notation) to inspect in the previous output, or null to compare the entire string output.
    • operator (string): Supported comparison operators:
      • '===' (strictly equal)
      • '==' (equal)
      • '!==' (not equal)
      • '>', '>=', '<', '<=' (numeric comparisons)
      • 'contains' (case-insensitive substring check)
    • matchValue (mixed): The expected value to compare against (e.g., 'AGENT', 'HUMAN', 10).

5. Enum (enum) & Enum Value (enum_value)

The enum and enum_value modules work together to let an AI Agent classify input into one of the cases of a PHP Enum and route the workflow accordingly. Check the live Enum Tester Workflow for a complete example.

How they work together

  1. EnumModule (enum):
    • Reads all cases from the configured PHP Enum ($enumClass::cases()).
    • Automatically appends a strict instruction to the prompt: "You MUST choose exactly one of the following values: ...".
    • Prompts the configured agentClass (e.g., Jev). If the agent implements HasStructuredOutput, it extracts $response['value'], $response['decision'], $response['next_route'], or $response['route']; otherwise it uses $response->text.
    • If agentClass is not configured on the enum node, it passes the previous step's output directly as the enum value to match.
  2. EnumValueModule (enum_value):
    • Each case of the Enum is represented by an enum_value node connected to the enum node.
    • The WorkflowEngine routes execution to the enum_value node whose config.matchValue matches the selected enum value.
  • Configuration for enum (config):
    • enumClass (string|null): Fully qualified PHP Enum class name (e.g., 'App\Enums\DecisionEnum').
    • agentClass (string|null): AI Agent class responsible for selecting the enum case (e.g., 'App\Ai\Agents\Jev').
    • prompt (string|null): Optional additional instructions prepended to the previous step's output.
  • Configuration for enum_value (config):
    • matchValue (string): The exact Enum case value this branch handles (e.g., 'ja', 'nee', 'misschien').

6. Pre-defined Response (response) — ResponseModule

Returns a pre-defined text response using a PHP class without making an LLM call (for example, a standard rejection message or customer service forwarding notice). Used in both Claim Handler and Enum Tester.

  • What it does: Calls handle($context, $previousOutput): string on the configured actionClass and outputs the returned string.
  • Configuration (config):
    • actionClass (string, required): Fully qualified class name implementing Tokomono\AiSuite\Workflows\Contracts\WorkflowResponseModuleInterface (e.g., 'App\Workflows\Modules\Responses\CustomerServiceResponse').

7. Human in the Loop (human_in_the_loop) — HumanInTheLoopModule

Marks a step where human review or manual intervention is required (see node_hitl in Claim Handler).

  • What it does: Halts the automated branch at this node and outputs 'Workflow paused for Human in the Loop intervention.'.
  • Configuration (config):
    • message (string): Instructions or context for the human reviewer (e.g., 'Please review this result').
    • assignee (string): Email address or identifier of the assigned reviewer (e.g., 'admin@example.com').

8. Stop Point (stop) — StopModule

Marks the explicit end of a workflow branch (see stop_000000008 and stop_000000009 in LLM as a Judge).

  • What it does: Terminates execution along that path and records 'Workflow Stopped' as the final step output in $context->steps.
  • Configuration (config): None.