Node Types

Complete reference for all node types in the TARX workflow canvas. Each node type has a defined set of inputs, outputs, configuration options, and expression variables.

---

triggerNode — Trigger

The starting point of every workflow. A workflow must have exactly one Trigger node. It receives initial input and passes it downstream.

Trigger Types

Manual

Executes when someone clicks the Run button in the canvas or calls the execute API.

Config Field	Type	Description
default_input	string	Pre-filled value in the run modal
input_label	string	Label shown in the run modal (e.g., "Topic", "Search query")

Expression output: {{trigger.output}} → The string entered in the run modal

Webhook

Executes when an HTTP POST request hits the workflow's webhook URL.

Config Field	Type	Description
webhook_secret	string	HMAC-SHA256 signing secret (auto-generated, click "Generate")
payload_path	string	Optional JSONPath to extract a field (e.g., $.body.text)

Webhook URL format: https://api.tarx.io/webhooks/{workflow_id}

Request format:

POST /webhooks/{workflow_id}
Content-Type: application/json
X-TARX-Signature: sha256={hmac_hex}

{"body": "Your payload here"}

The HMAC signature is computed as HMAC-SHA256(secret, raw_body_bytes).

Expression output: {{trigger.output}} → The webhook payload (or extracted field if payload_path set)

Schedule

Executes on a cron schedule.

Config Field	Type	Description
cron_expression	string	Standard cron expression (5 fields)
timezone	string	IANA timezone name (e.g., America/New_York)
default_input	string	Value injected as trigger output on each run

Common cron examples:

Cron	Schedule
0 9 * * *	Every day at 9:00 AM
0 9 * * 1-5	Weekdays at 9:00 AM
0 */4 * * *	Every 4 hours
*/15 * * * *	Every 15 minutes
0 8 1 * *	First day of each month at 8:00 AM

Expression output: {{trigger.output}} → The default_input value

HTTP

Executes when the workflow's HTTP endpoint receives a request (any method).

Config Field	Type	Description
allowed_methods	list	["GET", "POST"] etc.
response_mode	string	sync (wait for result) or async (return execution_id)

Expression output: {{trigger.output}} → Full request context as JSON {"method": "POST", "headers": {...}, "body": {...}}

---

agentNode — Agent

Runs an LLM agent. This is the core execution unit — everything else orchestrates around agent nodes.

Configuration

Config Field	Type	Description
agent_id	string	Reference to a configured agent in the project
input	string	The input passed to the agent (supports expressions)
label	string	Display name on the canvas
timeout	int	Max seconds to wait for completion (default: 120)

Inputs

• One input edge from any upstream node
• input field evaluated at runtime — all {{...}} expressions resolved

Outputs

• One output edge to any downstream node
• Expression: {{node_label.output}} where node_label is the agent's name from the agent config

Expression variable is the AGENT name, not the node label

The expression variable {{agent_name.output}} uses the agent's name (as configured in the Agent Editor), not the node's display label. If your agent is named researcher, the expression is {{researcher.output}} regardless of what you label the node on the canvas.

Agent Node States

State	Canvas Color	Meaning
Idle	Gray	Not yet executed
Running	Pulsing orange	LLM call in progress
Complete	Green	Successfully completed
Failed	Red	Error occurred
Skipped	Light gray	Branch condition routed around this node

---

branchNode — Condition / Branch

Evaluates a Python expression and routes execution to the True or False path.

Configuration

Config Field	Type	Description
condition	string	Python expression that evaluates to True or False
label	string	Display label on canvas

Condition Expression

The condition is a Python expression evaluated at runtime. Available variables in the expression:

Variable	Value
output	The output string from the immediately upstream node
trigger_output	The trigger's original output
node_outputs	Dict of all completed node outputs: {"agent_name": "output text"}

Example conditions:

# Check length
len(output) > 500

# Check for keyword
"error" in output.lower()

# Check JSON field
import json; json.loads(output)["severity"] == "high"

# Check numeric value
float(output.split()[0]) > 0.8

# Always true (force one path)
True

# Complex condition
len(output) > 100 and "success" in output.lower()

Outputs

• True output handle (right top) → Runs when condition evaluates to True
• False output handle (right bottom) → Runs when condition evaluates to False

Expression output: {{branch_label.output}} → The condition result as a string ("True" or "False")

---

loopNode — Loop / Iterator

Iterates over a list, running all downstream nodes once per item in the list.

Configuration

Config Field	Type	Description
items_expression	string	Expression that evaluates to the list to iterate over
label	string	Canvas display label
max_iterations	int	Safety limit (default: 1000)

Items Expression

Must evaluate to a Python list. Examples:

# From a JSON array produced upstream (agent or Transform node)
{{trigger.output}}

# Reference an upstream node that emits a JSON array
{{topic_generator.output}}

# Hard-coded list for testing
["topic 1", "topic 2", "topic 3"]

The items expression is evaluated using the same expression resolver as other fields.

Loop Variables

Inside the loop body (downstream nodes), two special variables are available:

Variable	Type	Description
{{loop_label.current_item}}	string	The current item being processed
{{loop_label.index}}	int	Current iteration index, 0-based

Example in a downstream agent's input field:

Process item {{loop_1.index + 1}} of {{total_count}}:
{{loop_1.current_item}}

Loop Outputs

After all iterations complete, the loop outputs a JSON array of all results:

Expression: {{loop_label.output}} → JSON array ["result_1", "result_2", ...]

---

outputNode — Output

Captures the result at a point in the workflow and exposes it to Canvas for visualization. The Output node is not a workflow terminator — it passes its value through, so you can keep wiring nodes after it. To stop a run early, use a Terminate node instead.

Configuration

Config Field	Type	Description
value	string	Expression that resolves to the output value (leave empty to pass the upstream output through)
label	string	Optional alias for this output. Names it in the Canvas "Aggregate from output" picker when a workflow has several Output nodes
format	string	"passthrough" (default), "json", or "markdown"

Canvas data source

The Output node is how a workflow's data reaches Canvas. When a Canvas links this workflow, each run's output is aggregated into chart data. In a branching workflow with multiple Output nodes, give each a label and pick which one a Canvas reads from using the Aggregate from output picker. See Canvas → Creating Canvases.

Example Values

{{agent_name.output}}
{{loop_1.output}}
Summary: {{writer.output}}
{"research": "{{researcher.output}}", "draft": "{{writer.output}}"}

Multiple Output Nodes

A workflow can have multiple Output nodes — for example, one per branch of a Condition. All Output nodes reached during execution are captured in the execution result, and each can be targeted individually by Canvas via its label.

Expression output: {{output_slug.output}} → the captured value (Output nodes are non-terminal, so downstream nodes can reference them).

---

humanLoopNode — Human-in-Loop

Pauses workflow execution and waits for a human to approve or reject before continuing.

Configuration

Config Field	Type	Description
title	string	Title of the approval request (shown to reviewer)
description	string	Context/instructions for the reviewer
timeout_hours	int	Hours to wait before auto-rejecting (0 = no timeout)
notification_email	string	Email to notify when pause occurs (optional)
display_value	string	The content to show for review (supports expressions)

Approval Flow

1. Execution reaches the Human-in-Loop node → pauses
2. Reviewer is notified (email + in-app notification)
3. Reviewer goes to: Executions → the paused execution → click "Review"
4. A review panel shows the display_value content
5. Reviewer clicks Approve or Reject (comment is optional)

On Approve: the paused node is marked completed, the Rejected branch is skipped, and execution continues down the Approved branch.

On Reject: execution continues down the Rejected branch (if one is connected — e.g. a cleanup or notification path). If nothing is connected to the Rejected handle, the run finishes there.

The approver (and their role) is recorded on the execution and shown in the UI and the execution log.

Outputs

• Approved output handle → route for approved continuations
• Rejected output handle → route for rejected continuations (optional cleanup path)

Expression output: {{hil_label.output}} → "approved" or "rejected" plus any reviewer comment

In Bridge

Reviewers can also approve/reject Human-in-Loop steps directly in Bridge. See Human-in-Loop for the full approval flow.

---

noteNode — Note

A visual annotation on the canvas. Has no effect on execution — it's for documenting complex workflows.

Configuration

Config Field	Type	Description
content	string	The note text (markdown supported)
color	string	Note background color (hex or named)

Usage

• Document complex branch logic
• Add TODO reminders
• Explain why certain agents were configured a specific way
• Mark sections of large workflows

Notes cannot be connected to other nodes and are completely ignored during execution.

---

Node Connection Rules

Not all connections are valid. Here are the connection rules:

From	Can Connect To
Trigger	Agent, Branch, Loop, Output, Human-in-Loop
Agent	Agent, Branch, Loop, Output, Human-in-Loop
Branch (True)	Agent, Loop, Output, Human-in-Loop
Branch (False)	Agent, Loop, Output, Human-in-Loop
Loop	Agent, Branch, Loop (nested), Output, Human-in-Loop
Human-in-Loop (Approved)	Agent, Branch, Output
Human-in-Loop (Rejected)	Agent, Output
Output	— (leaf node, no outputs)
Note	— (no connections)

Cycles are not supported

Workflows are Directed Acyclic Graphs. You cannot create loops by connecting a node back to an upstream node. Use the Loop/Iterator node for iteration instead.