Nodes & Edges¶

Nodes are the building blocks of workflows. Edges are the typed connections between them. Together, they form a directed graph with validated data flow that Pipelit compiles and executes.

Nodes¶

Every element on the workflow canvas is a node. Each node has a component_type that determines its behavior, a unique node_id within the workflow, and a configuration that controls how it runs.

Node categories¶

Pipelit organizes its node types into seven categories:

graph TD
    subgraph Triggers["Triggers (6 types)"]
        direction LR
        TC[Chat] ~~~ TT[Telegram] ~~~ TM[Manual]
        TS[Schedule] ~~~ TW[Workflow] ~~~ TE[Error]
    end

    subgraph AI["AI (4 types)"]
        direction LR
        Agent ~~~ Categorizer ~~~ Router ~~~ Extractor
    end

    subgraph Tools["Tools (5 types)"]
        direction LR
        RunCmd[Run Command] ~~~ HTTP[HTTP Request] ~~~ WebSearch[Web Search]
        Calc[Calculator] ~~~ DT[Date & Time]
    end

    subgraph Logic["Logic (9 types)"]
        direction LR
        Switch ~~~ Code ~~~ Merge
        Filter ~~~ Loop ~~~ Wait
        HC[Human Confirm] ~~~ Agg[Aggregator] ~~~ Sub[Subworkflow]
    end

    subgraph SubComp["Sub-Components (3 types)"]
        direction LR
        AIM[AI Model] ~~~ OP[Output Parser] ~~~ CE[Code Execute]
    end

    subgraph SelfAware["Self-Awareness (11 types)"]
        direction LR
        CAU[Create Agent User] ~~~ PA[Platform API] ~~~ WhoAmI
        TOTP[Get TOTP] ~~~ Epic[Epic Tools] ~~~ Task[Task Tools]
        SA[Spawn & Await] ~~~ WC[Workflow Create] ~~~ WD[Workflow Discover]
        ST[Scheduler Tools] ~~~ SH[System Health]
    end

    subgraph Memory["Memory (3 types)"]
        direction LR
        MR[Memory Read] ~~~ MW[Memory Write] ~~~ IU[Identify User]
    end

Executable vs. non-executable nodes¶

Not all nodes run during execution:

• Trigger nodes initiate execution but do not execute themselves -- they produce output that flows to downstream nodes.
• Sub-component nodes (ai_model, output_parser) are configuration-only. They attach to AI nodes to provide model and parser settings.
• Tool nodes (run_command, http_request, etc.) are executable -- they run when an agent invokes them during its reasoning loop.

Typed ports¶

Every node declares typed input ports and output ports. Ports define what data a node accepts and what it produces.

DataType enum¶

Pipelit uses a type system for port definitions:

Port examples¶

Here are the port definitions for a few common node types:

Type compatibility¶

When you connect two nodes, Pipelit checks that the source output type is compatible with the target input type. The compatibility rules are:

• Same type -- always compatible
• Any to Any -- the ANY type is universally compatible as source or target
• String coercions -- STRING can connect to MESSAGE or MESSAGES inputs
• Message coercions -- MESSAGE can connect to MESSAGES inputs

Incompatible connections are rejected at edge creation time with a 422 error.

Edges¶

Edges are directed connections between nodes. They carry data from a source node's output to a target node's input.

Edge types¶

Edge labels¶

Edge labels identify the purpose of a connection. They determine which handle the edge connects to on the target node.

Edge validation¶

Pipelit validates edges at two levels:

1. At creation time -- When you draw an edge on the canvas or call the API, the system checks type compatibility between the source output and target input. Invalid connections return a 422 error.

2. At workflow validation time -- The POST /api/v1/workflows/{slug}/validate/ endpoint (or the Validate button) runs comprehensive checks across all edges:

   • All source and target nodes exist
   • Conditional edges have a condition_value and originate from switch nodes
   • Type compatibility holds for all direct edges
   • Nodes that require a model connection have one

Sub-component connections¶

AI nodes require sub-component connections to function:

Sub-component connections use the diamond-shaped handles at the bottom of AI nodes. You connect an ai_model node via the blue handle, tool nodes via the green handle, and so on.

flowchart TB
    Model[AI Model<br/>GPT-4o] -.->|"llm (blue)"| Agent
    Search[Web Search] -.->|"tool (green)"| Agent
    Command[Run Command] -.->|"tool (green)"| Agent
    MemRead[Memory Read] -.->|"memory (amber)"| Agent
    Trigger[Chat Trigger] --> Agent
    Agent --> Output[Code: Format]

Node output convention¶

When a component finishes executing, it returns a flat dictionary of its port values (e.g., {"output": "Hello!", "messages": [...]}). The orchestrator automatically stores all non-underscore-prefixed keys in node_outputs[node_id], making them available to downstream nodes via Jinja2 expressions like {{ agent_abc123.output }}.

Reserved underscore-prefixed keys control side effects:

What's next?¶

• Learn how workflows start: Triggers
• Understand LLM-powered nodes: Agents
• Reference upstream data: Expressions