Flow Builder Documentation

What is the Flow Builder?

The Flow Builder is a visual programming interface for creating, testing, and managing complex backend workflows. Instead of writing code or complex JSON, you can build a process by dragging and dropping nodes onto a canvas and connecting them with edges to define the sequence and data flow. It's an intuitive UI for orchestrating operations like calling Python functions, making AI requests, and manipulating data.

Core Components

The Flow Builder UI consists of four main sections:

  • The Canvas: The central workspace where you build your flow. It uses React Flow to visualize the nodes (steps) and edges (connections).
  • The Left Panel (Nodes & Variables): This panel has two tabs:
    • Nodes Tab: A library of all available nodes, organized by category. You can drag nodes from here onto the canvas.
    • Variables Tab: A view of all available data in the flow, including Global Variables (user-defined) and Node Variables (automatically created for each step's output).
  • The Right Panel (Settings Panel): This panel appears when you select a node. It allows you to configure the node's specific parameters, with fields dynamically generated from a predefined schema.
  • The Header: Contains the flow's name and primary action buttons like "Save" and "Run Flow".

Key Concepts

  • Nodes: Each node represents a single step in the workflow, such as an AI prompt or a function call.
  • Edges: The connecting lines between nodes that define the order of execution.
  • Variables: How data is stored and passed between nodes.
    • Node Variables: Automatically created for a node's output, formatted as {steps.node_api_name.output}.
    • Global Variables: User-defined inputs, formatted as {inputs.variable_name}.
  • Execution: When a flow runs, the frontend converts the visual graph into a sequence of steps. This list is sent to a backend, which executes each step, resolves inputs from previous outputs, and returns the complete set of outputs to the UI for inspection.

How to Create a Node

Creating a new node for the Flow Builder is a standardized process involving four files and a final registration step.

Step 1: Create the Node Directory

First, navigate to the .../Flow/nodes/ directory and create a new, capitalized, and descriptive folder for your node, for example: .../Flow/nodes/MyNewNode/

Step 2: Define Default Properties (MyNewNode.props.js)

This file defines the node's core metadata for the UI and the default data structure that the backend will use.

export const MyNewNodeProps = {
  // --- Metadata for the UI and Registry ---
  api_name: "my_new_node", // A unique, lowercase, snake_case key
  name: "My New Node",     // The human-friendly name
  description: "This node performs a specific awesome action.",
  category: "Custom",      // The category for the left panel

  // --- Data for the Backend Workflow ---
  step_type: "function_call", // Must be a type the backend recognizes
  payload: {
    function_name: "my_python_function",
    kwargs: {
      "parameter_one": "default value",
    }
  },
  inputs: null
};

Step 3: Define the Settings Schema (MyNewNode.schema.js)

This file uses a JSON Schema to define the configuration fields that will appear in the right-side Settings Panel when the node is selected.

export const MyNewNodeSchema = {
  title: "My New Node",
  description: "Configuration for My New Node.",
  properties: {
    "api_name": {
      "type": "string",
      "title": "API Name (Unique)",
      "description": "A unique, human-readable name for this step."
    },
    // The key here, "parameter_one", must match a key in your props.js payload
    "parameter_one": {
        "type": "string",
        "title": "Parameter One",
        "description": "The first parameter for this node's function."
    }
  },
  required: ["api_name"]
};

Step 4: Create the Visual Component (MyNewNode.node.jsx)

This React component renders the visual representation of your node on the canvas. It receives a data prop containing all its properties.

import React, { memo } from 'react';
import { Handle, Position } from '@xyflow/react';

export const MyNewNode = memo(({ data }) => {
  return (
    <div style={{
        border: '1px solid #1E90FF',
        borderRadius: '5px',
        padding: '10px',
        background: 'white',
        width: 180,
    }}>
      {/* Input handle (dot on the left) */}
      <Handle type="target" position={Position.Left} />
      
      <div>
        <strong>{data.name}</strong>
        <p style={{ fontSize: '12px', margin: 0, color: '#555' }}>
            {data.description}
        </p>
      </div>

      {/* Output handle (dot on the right) */}
      <Handle type="source" position={Position.Right} />
    </div>
  );
});

Step 5: Create the Unified Export (index.js)

This file bundles all the node's components into a single object for the registry.

import { MyNewNode } from './MyNewNode.node';
import { MyNewNodeProps } from './MyNewNode.props';
import { MyNewNodeSchema } from './MyNewNode.schema';

export const MyNewNodeComponent = {
  component: MyNewNode,
  props: MyNewNodeProps,
  schema: MyNewNodeSchema,
  // If you have a custom settings UI, you would export it here
};

Step 6: Register the Node

Finally, open the central registry file and import your new node component, then add it to the allNodeDefinitions array.

// ... other imports
import { MyNewNodeComponent } from './nodes/MyNewNode';

// ...

const allNodeDefinitions = [
  TriggerComponent,
  SayComponent,
  MyNewNodeComponent, // 2. Add your node to this list
  // ...
];

// ... rest of the file

Once these steps are completed, your new node will appear in the left panel and be fully functional within the Flow Builder.