Node Types Reference

Technical specification for every node type in TARX. Use this as a reference when building workflows programmatically or debugging unexpected behavior.

---

triggerNode

Type string: triggerNode

Config Schema

interface TriggerNodeData {
  trigger_type: "manual" | "webhook" | "schedule" | "http";
  label?: string;
  
  // Manual trigger
  default_input?: string;
  input_label?: string;
  
  // Webhook trigger
  webhook_secret?: string;
  payload_path?: string;  // JSONPath, e.g., "$.body.message"
  
  // Schedule trigger
  cron_expression?: string;  // 5-field cron
  timezone?: string;         // IANA timezone
  
  // HTTP trigger
  allowed_methods?: ("GET" | "POST" | "PUT" | "DELETE" | "PATCH")[];
  response_mode?: "sync" | "async";
}

Inputs

None (start node)

Outputs

• 1 output handle — connects to any downstream node

Expression Variables

Variable	Available When	Value
{{trigger.output}}	Always	Trigger output (varies by type)

Execution Behavior

• Executes first, always
• Cannot fail (trigger processing errors result in 400 response, not execution failure)
• Webhook: validates HMAC signature before queueing execution

---

agentNode

Type string: agentNode

Config Schema

interface AgentNodeData {
  agent_id: string;       // References an agent by its ID
  input: string;          // Input text, supports {{expressions}}
  label?: string;         // Canvas display label
  timeout?: number;       // Seconds before timeout (default: 120)
}

Inputs

• 1 input handle — from any upstream node

Outputs

• 1 output handle — connects to downstream nodes

Expression Variables

Variable	Available When	Value
{{agent_name.output}}	After node completes	Full LLM response text

Note: agent_name is the agent's configured name, not the node's canvas label.

Execution Behavior

1. Resolves all {{...}} expressions in the input field
2. Loads agent config (model, system_prompt, capabilities, etc.)
3. If RAG sources configured: embeds input, queries all RAGs, prepends results to system prompt
4. If MCP servers configured: connects to each, discovers tools
5. Calls LiteLLM with full context (system prompt + RAG context + user input + tools)
6. Model may make tool calls (capabilities or MCP): each call is executed and result returned to model
7. Maximum 10 tool call rounds
8. Final text response stored as node output

Failure Modes

Error	Cause
AgentNotFound	agent_id references deleted agent
APIKeyNotFound	Agent's user_api_key_id references deleted key
ProviderAuthError	API key is invalid or expired
ProviderRateLimitError	Provider rate limit exceeded
TimeoutError	Execution exceeded timeout seconds
ToolCallMaxRoundsError	Model attempted more than 10 tool rounds
MCPConnectionError	MCP server unreachable or auth failed

---

branchNode

Type string: branchNode

Config Schema

interface BranchNodeData {
  condition: string;   // Python expression
  label?: string;
}

Inputs

• 1 input handle

Outputs

• 2 output handles:
  • Top handle: True path
  • Bottom handle: False path

Python Condition Context

# Variables available in condition:
output: str          # Output of immediately upstream node
trigger_output: str  # {{trigger.output}} value
node_outputs: dict   # {"agent_name": "output_text", ...}

Expression Variables

Variable	Value
{{branch_name.output}}	"True" or "False"

Execution Behavior

1. Evaluates condition as a Python expression in the above context
2. Routes to True or False handle based on result
3. Only one path executes — the other path's nodes are skipped

Failure Modes

Error	Cause
ConditionEvaluationError	Python expression raised an exception
ConditionTypeError	Expression didn't return a boolean-compatible value

---

loopNode

Type string: loopNode

Config Schema

interface LoopNodeData {
  items_expression: string;  // Expression evaluating to a list
  label?: string;
  max_iterations?: number;   // Safety cap, default: 1000
}

Inputs

• 1 input handle — from upstream node

Outputs

• 1 output handle — connects to loop body nodes

Expression Variables

Variable	Available When	Value
{{loop_name.current_item}}	Inside loop body	Current item (stringified)
{{loop_name.index}}	Inside loop body	0-based integer index
{{loop_name.output}}	After loop completes	JSON array of all results

Items Expression Parsing

The items_expression is evaluated and parsed:

1. {{...}} expressions are resolved
2. Result is parsed as JSON if it starts with [
3. If not JSON, treated as a newline-delimited list
4. Each element becomes one iteration's current_item

Execution Behavior

1. Resolves items_expression to a list
2. For each item, in order: a. Sets current_item and index context variables b. Executes all nodes in the loop body (connected downstream nodes) c. Collects the last node's output as this iteration's result
3. After all iterations: emits JSON array of all iteration results as output
4. Stops at max_iterations if list is longer

Failure Modes

Error	Cause
ItemsExpressionError	Expression evaluation failed
ItemsParseError	Result couldn't be parsed as a list
MaxIterationsExceeded	List longer than max_iterations

---

outputNode

Type string: outputNode

Config Schema

interface OutputNodeData {
  value?: string;         // Expression resolving to output value (defaults to upstream output)
  label?: string;         // Optional alias — names this output for Canvas
  format?: "passthrough" | "json" | "markdown";  // default: "passthrough"
}

Inputs

• 1 input handle

Outputs

• 1 output handle — non-terminal. The Output node passes its value through, so you can wire additional nodes downstream of it. It is not an "end" marker; use a Terminate node to halt a run early.

Canvas data source

The Output node is the canonical data source for Canvas visualizations. Each run's value is captured and aggregated by any Canvas linked to this workflow.

• label — an optional alias (e.g. sales_data, error_report). In branching workflows with multiple Output nodes, the label identifies which output a Canvas chart should read from via the "Aggregate from output" picker. Single-Output workflows need no label.

Execution Behavior

1. Resolves value (or passes the upstream output through when empty), applying the chosen format.
2. Updates the execution's top-level output and stores its own node result.
3. Multiple Output nodes are allowed; each stores its result. Canvas reads the top-level output by default, or a specific node when one is selected in the source picker.

---

humanLoopNode

Type string: humanLoopNode

Config Schema

interface HumanLoopNodeData {
  title: string;
  description?: string;
  display_value: string;        // Supports {{expressions}}
  timeout_hours?: number;       // 0 = no timeout
  notification_email?: string;
  label?: string;
}

Inputs

• 1 input handle

Outputs

• 2 output handles:
  • Approved handle (top)
  • Rejected handle (bottom)

Expression Variables

Variable	Value
{{hil_name.output}}	"approved", "approved: comment", or "rejected: comment"

Execution Behavior

1. Resolves display_value expressions
2. Updates execution status to "paused"
3. Sends notification email (if configured)
4. Queues timeout job (if timeout_hours > 0)
5. Suspends execution — no further nodes run

On approval API call (POST /executions/{id}/approve with decision: "approved"):

1. Updates HiL output: "approved" or "approved: {comment}"
2. Resumes execution on Approved handle path

On rejection (same API with decision: "rejected"):

1. Updates HiL output: "rejected: {comment}"
2. Resumes execution on Rejected handle path

On timeout:

1. Sets output: "rejected: timeout — approval expired after {N} hours"
2. Continues on Rejected handle path

---

noteNode

Type string: noteNode

Config Schema

interface NoteNodeData {
  content: string;    // Markdown text
  color?: string;     // CSS color value
  label?: string;
}

Inputs / Outputs

None — cannot be connected to other nodes

Execution Behavior

None — completely ignored during execution

---

Canvas Position

All node types include a position in the canvas (stored in the workflow document):

interface NodePosition {
  x: number;  // Pixels from canvas left edge
  y: number;  // Pixels from canvas top edge
}

Position is managed by the canvas UI and doesn't affect execution.

---

Edge Schema

Edges connect nodes. The edge source and target use node IDs:

interface WorkflowEdge {
  id: string;
  source: string;         // Source node ID
  target: string;         // Target node ID
  sourceHandle?: string;  // For branchNode: "true" or "false"
                          // For humanLoopNode: "approved" or "rejected"
}