Tokomono
Ai Suite
3. Workflows

Building & Testing Workflows in the UI

Building & Testing Workflows in the UI

The Visual Workflow Editor (/ai-suite#/workflows) lets you create, wire up, test, version, and publish multi-step AI and PHP workflows directly in the browser.

1. Step-by-Step: Creating a New Workflow

  1. In the top navigation bar, click Workflows.
  2. Click the blue + New Workflow button in the top-right corner.
  3. In the Create New Workflow modal, fill in the fields:
    • Name (required): The display name of your workflow (e.g., Order Return Handler). This also generates a matching PHP class in app/Ai/Workflows/{StudlyName}Workflow.php with a unique 8-character sync_hash.
    • Description (optional): A short summary displayed in the Workflows overview table.
    • Test Mode (toggle, enabled by default): Marks the workflow with an orange Test badge so it does not run in production until disabled.
  4. Click Create. You are automatically redirected to the Visual Workflow Editor (/ai-suite#/workflows/{id}/edit) with an initial Start Point node placed on the canvas.

2. Step-by-Step: Building the Workflow Graph in the Visual Editor

The Visual Workflow Editor (/ai-suite#/workflows/{id}/edit) is divided into three main areas:

  • Left Sidebar (Modules): Draggable workflow building blocks.
  • Center Canvas: Interactive node-and-edge graph (supports pan, zoom, and fit-to-view controls in the bottom-left corner).
  • Right Sidebar (Configuration & Test Workflow): Context-sensitive node/edge/workflow settings on top, and an interactive test chat at the bottom.

Adding & Connecting Modules (Nodes & Edges)

  1. Drag a Module to the Canvas: Drag any module from the left Modules sidebar (Start Point, Agent, PHP Code, If / Else, Statement, Enum, Enum Value, Pre-defined Response, Human in the Loop, Stop Point) and drop it onto the canvas.
  2. Connect Two Nodes: Drag a connection line (edge) from a node's output handle (bottom or right circle) to the target node's input handle (top or left circle).
  3. Reconnect or Delete an Edge:
    • Drag an existing edge's endpoint to move it to a different handle.
    • To remove a connection, click the edge line on the canvas and click Delete Edge in the right Configuration panel.

Configuring Individual Nodes

Click any node on the canvas to open its settings in the right Configuration panel:

  • ID (Unique within workflow): Every node gets an auto-generated ID (such as agen_000000001 or phpc_000000002). You can type a custom ID (e.g., node_php) and press Enter or click outside the field—all connected edges update automatically. Downstream Agent nodes can reference this node's output in their prompt using {{node_id}}.
  • Agent Node (agent): Select the Agent Class from the dropdown. If the agent has a database record, click View or edit instructions for this agent → to jump directly to its CRAFT prompt editor (/ai-suite#/agent/{id}/edit).
  • If / Else (if_else) & Statement (statement) Nodes:
    1. Connect the output of an If / Else node to one or more Statement nodes.
    2. Click each Statement node to configure its branching rule:
      • Statement Type: Select Match (If / Elseif) for a condition, or Else (Fallback) for the default route when no match condition is met.
      • Match Key (Dot-notation, optional): Enter a JSON/array key (e.g., score or data.status) if the preceding node returns structured array output, or leave empty to compare against the full text output.
      • Operator: Choose ===, ==, !==, >, >=, <, <=, or contains.
      • Match Value: Enter the value to compare against (e.g., AGENT, HUMAN, or 8).
  • Enum (enum) & Enum Value (enum_value) Nodes:
    1. Click the Enum node and select a structured Agent Class (agents with Structured Output enabled), an Enum Class (App\Enums\...), and an optional Prompt instruction.
    2. Drag one or more Enum Value nodes onto the canvas and connect edges from the Enum node to each Enum Value node.
    3. Click each connected Enum Value node and choose the corresponding enum case from the Value (Match) dropdown.
  • PHP Code Node (php_code): Select the Class to execute (any class implementing WorkflowPhpCodeModuleInterface) from the dropdown.
  • Pre-defined Response Node (response): Select the Pre-defined Response Class (any class implementing WorkflowResponseModuleInterface) from the dropdown.
  • Deleting a Node: With a node selected, click Delete Node at the bottom of the right Configuration panel.

Editing Workflow-Level Settings (Name & Test Mode)

Click on an empty area of the canvas to deselect all nodes and edges. The right Configuration panel displays Workflow Instellingen, where you can:

  • Rename the workflow in the Name field.
  • Toggle the Test Mode checkbox (Test vs Live).

3. Step-by-Step: Testing a Workflow in the Built-in Test Chat

At the bottom of the right sidebar is the Test Workflow chat panel (you can drag the horizontal divider bar up or down to resize it).

  1. Select a Test User (Optional):
    • Click User: Test User in the Test Workflow header to open the Select User dialog.
    • Search by name, email, or ID and click a user to impersonate during the test run (or click Clear Selection). When a user is selected, Agent nodes can persist and continue conversation history for that user.
  2. Reset Conversation Memory (Optional):
    • Click Start New Conversation in the Test Workflow header to clear the chat history and set clear_conversation = true for the next test run.
  3. Run a Test Message:
    • Type a test prompt into Type your message... and click Test (or press Enter).
    • Your message is passed as globalVariables['question'] into the Start Point node, and the current canvas definition is executed immediately (even before saving a draft).
  4. Inspect the Visual Execution Path:
    • Every node that was executed during the run is highlighted on the canvas with a thicker colored border.
    • Every traversed edge animates in blue when execution succeeds, or red along the path where an error occurred.
  5. Inspect the Step-by-Step JSON Execution Log:
    • Inside the workflow's response bubble in the chat, click Show log.
    • A Log side panel opens next to the right sidebar displaying the full JSON array of WorkflowStepDto entries (nodeName, outputData.content, outputData.data, meta.module_type, and meta.next_route).
    • Press Esc or click × in the top-right of the Log panel to close it.

4. Step-by-Step: Saving Drafts & Publishing a Workflow

Workflows use a two-step Draft → Publish lifecycle so you can experiment safely in the editor without immediately overwriting your live workflow or PHP class file:

  1. Save as Draft (Opslaan als concept):
    • Whenever you make changes on the canvas or in workflow settings, an amber * Onopgeslagen wijzigingen (Unsaved changes) badge appears in the top bar.
    • Click Opslaan als concept (Save as draft) in the top-right bar. This stores a new draft record in workflow_versions.
  2. Publish a Version (Publish):
    • Once all changes are saved as a draft, the blue Publish button becomes enabled.
    • Click Publish to open the Publish Workflow modal.
    • Select the version you want to make active from the Versie dropdown (versions are listed newest-first with (Concept) or (Huidig) labels) and click Publish.
    • What happens on Publish:
      • The selected WorkflowVersion is marked as published and becomes the workflow's activeVersion.
      • In local development, the getDefinition() method inside app/Ai/Workflows/{ClassName}.php is automatically updated with the published node and edge graph.
      • In configured staging/test environments (when tokomono/git-sync is installed), publishing triggers a GitSync Pull Request.

5. Deleting a Workflow

  1. Navigate to Workflows.
  2. Click the red trash icon in the Actions column of the workflow you want to remove.
  3. Confirm deletion in the confirmation modal.