Node types reference

A node is one step in a workflow graph. When a run executes, each node receives the current run state, does its work, and writes its result back into state. ModuleX supports exactly nine node types. This page covers all nine, the single convention that ties them together — every node writes its result to state under its own id — and how later nodes read earlier results with {{node_id.field}} references. For the engine that compiles and runs these nodes (the state graph, the run state, edges, and loops), see Workflow engine & nodes. For the cross-node data flow in depth, see Variables & references.

The nine node types

These are the canonical NodeType values. The string in the first column is the exact type you set on a node — there is no other set, and an unknown value raises Unsupported node type.

`type`	Node	What it does	Category
`llm`	LLM node	Call a language model with a system/user prompt; optionally enforce a structured-output JSON schema.	Model
`agent`	Agent node	Run an autonomous model-plus-tools loop that decides which tools to call, up to `max_iterations`.	Model
`tool`	Tool node	Call one integration tool deterministically with a mapped input.	Action
`knowledge`	Knowledge node	Retrieve relevant chunks from a knowledge base (managed `modulexdb` or BYOK vector store) for RAG.	Data
`function`	Function node	Run one of the built-in functions: HTTP request, webhook, or schema validation.	Action
`transformer`	Transformer node	Reshape, map, filter, and convert data between steps with a pipeline of operations.	Data
`conditional`	Conditional node	Branch on an expression or an LLM decision, or drive a `for` / `foreach` / `while` loop.	Control
`guardrails`	Guardrails node	Validate content with JSON-schema, regex, and PII checks, then block, warn, transform, or route.	Control
`interrupt`	Interrupt node	Pause the run to ask a human a structured question, then resume with their answer.	Control

Pick a node by intent

Use the decision guide below if you are not sure which type fits a step. Each node’s own page documents every parameter, input, output, error, and credit impact in full.

The output-to-state convention

Every node writes its result into the run state under a key equal to its own node id. There is no separate “output name” to wire up — the node id is the output key. If a node with id: "node_summary" produces the string "Quarterly revenue rose 12%.", then after that node runs the state contains:

{
  "node_summary": "Quarterly revenue rose 12%."
}

This is enforced by the engine in two ways:

When the graph is compiled, one state field is added per node id (typed Any) so each node’s output streams back into state correctly.
Each node’s executor returns a single-key dict of the form {node_id: result}. The node id is the only output key.

Some node configs still expose an output_key field (and a few expose input_keys). Both are deprecated and ignored — output is always stored under the node id. Do not set them. Use {{node_id.field}} references (below) instead of input_keys.

The shape of result depends on the node type — a string for a simple LLM node, an object for a Tool node, a list of chunks plus context for a Knowledge node, and so on. Each node page documents its exact result shape under “Output”. A few nodes write a structured envelope rather than a bare value, which you reference by sub-path:

Node type	Result written under the node id
`llm`	The model’s content (a string, or your structured-output object).
`tool`	The tool’s unwrapped result object (a `{success, action, result}` wrapper is flattened to the root, with `result` kept for backward-compatible `.result.field` paths).
`agent`	The agent’s final content after its tool loop.
`function`	The function’s `data` on success; on failure an object like `{error, success: false}`.
`knowledge`	An object `{total_results, chunks, context}` (shape depends on `output_format`).
`conditional`	For expression branching, `{matched_target}`; for LLM routing, `{llm_routing_decision}`.
`guardrails`	A validation envelope `{valid, validations, original_data, transformed_data, ...}`.
`interrupt`	The human’s resume value, once the run resumes.
`transformer`	The transformed value after all operations run.

Referencing earlier results: `{{node_id.field}}`

Later nodes read earlier results with the template syntax {{node_id.path}}. This is the single mechanism for passing data between nodes — there are no explicit input wires beyond the graph edges. How resolution behaves:

A value that is exactly one reference (for example {{node_search.results}}) resolves to the native typed value — a list stays a list, a number stays a number.
A reference inside a larger string (for example Summarize: {{node_search.title}}) is substituted into the string; non-string values are JSON-encoded into the text.
The path supports dot and bracket access: {{node_abc.results[0].title}} reads the title of the first item of node_abc’s results.
An unresolved or out-of-range path resolves to null (and an unresolved reference left in a template string is kept intact, not blanked).
In a list, an item written as {{...node_id.path}} (note the leading ...) is a spread: if it resolves to a list, its items are spliced into the surrounding list; a scalar or object is appended; null contributes nothing.

You can use references anywhere a config field accepts a template: prompts, tool input mappings, conditional expressions, knowledge queries, transformer sources, and interrupt messages. Each node page marks which of its fields accept {{...}}.

Reference patterns

{{node_llm_1}}                       Whole output of node_llm_1
{{node_search.results[0].url}}       Nested path with array index
Subject: {{node_meta.title}}         Reference embedded in a string
{{input}}                            The run's top-level input value
{{...node_split.items}}             Spread a list into a surrounding list

The same {{node_id.field}} syntax is what the AI Composer writes when it wires nodes together for you, and what the canvas shows in field pickers. See Variables & references for the full resolution rules, reducers, and the run state model.

What every node shares

These fields exist on every node regardless of type. They are set on the node itself, not inside the type-specific config.

string

required

Unique node identifier. This is also the key its output is written under in run state (see the output-to-state convention above). Referenced elsewhere as {{id.field}}.

string

required

One of the nine node types: llm, tool, agent, function, conditional, interrupt, transformer, guardrails, knowledge. Any other value raises Unsupported node type at compile time.

string

Human-readable label shown on the canvas. Optional.

string

What the node does. Optional, display only.

boolean

default:"true"

Whether the node runs. A disabled node is skipped at execution time and its edges are rewired to the next enabled target, but it remains visible in the workflow definition. null is treated as true.

object

Per-node retry policy. Applies to every node type except interrupt, which is never retry-wrapped (pausing for a human is not a retriable failure). See the fields below.

Show retry_config fields

integer

default:"3"

Total attempts including the first (1 = no retry). Range 1–10.

number

default:"1.0"

Seconds to wait before the first retry. Range 0.1–60.

number

default:"2.0"

Exponential backoff multiplier applied between retries. Range 1.0–5.0.

string[]

Error class names that trigger a retry. Errors not in this list fail the node immediately.

Each type then carries one type-specific config object — llm_config, tool_config, agent_config, function_config, conditional_config, interrupt_config, transformer_config, guardrails_config, or knowledge_config — documented in full on that node’s page. (The builder also accepts a wrapped {config: {...}} form and normalizes it to the type-specific key.)

How a node fails

When a node raises after exhausting its retries, the run emits a node_error event and the run stops. The error carries a machine-readable reason — for example credit_exhausted when the billing gate stops a managed call mid-run — so a client can match it deterministically. See Error handling & retries for retry behavior and debugging, and Errors & status codes for the envelope shapes returned by the run surface.

Credit impact

There is no flat per-node credit charge. Credits are metered inline based on what a node actually does:

llm and agent nodes, and the LLM call inside a conditional node’s LLM routing, record credit usage per call from the model’s input and output tokens. The agent node records usage on every iteration of its loop.
knowledge nodes consume credits only when retrieving from the managed modulexdb store — a retrieval base plus the query-embedding cost. Bring-your-own-vector-store providers (Qdrant, Pinecone, Weaviate, MongoDB Atlas) are not metered by ModuleX.
tool, function, transformer, conditional (expression), guardrails, and interrupt nodes do not themselves consume credits. A tool node may incur cost at the connected provider, but ModuleX does not meter it.

For when the billing gate can stop a run and what surfaces it applies to, see Credits & the billing model.

How to pick a node

I need to call a language model

Use an LLM node for a single, deterministic model call — one prompt in, one answer out, optionally constrained to a JSON schema. Reach for an Agent node only when the model must decide which tools to call and loop until it is done; an agent costs more credits because it records usage on every iteration.

I need to call an external service

Use a Tool node to call one integration tool with values you control (it honors both parameter_defaults and parameter_overrides). Use a Function node for a raw HTTP request, an outbound webhook, or schema validation without an integration. Let an Agent node call tools only when the model should choose them.

I need company knowledge or RAG context

Use a Knowledge node to retrieve chunks from a knowledge base, then feed {{node_id.context}} into a downstream LLM node prompt.

I need to reshape or combine data

Use a Transformer node for string, object, array, type, date, and math operations — picking fields, mapping a list, parsing JSON, formatting a date, and so on — without writing code.

I need to branch or loop

Use a Conditional node: an expression branch for deterministic routing, an LLM decision for fuzzy routing, or a loop (for / foreach / while) to iterate over data.

I need to validate or sanitize content

Use a Guardrails node to check content against a JSON schema or regex, detect and mask PII, then block, warn, transform, or route on failure.

I need a human to approve or supply input

Use an Interrupt node. It pauses the run and waits for a structured answer that you resume with — see Human-in-the-loop resume.

Worked example: a three-node retrieve-and-summarize flow

This example chains a Knowledge node, an LLM node, and a Guardrails node. It shows the output-to-state convention and {{node_id.field}} references end to end. Each node writes under its own id; the next node reads it by reference.

Retrieve context from a knowledge base

node_kb queries the managed store and writes {total_results, chunks, context} under node_kb. The query itself is a reference to the run input.

Summarize with an LLM

node_summary reads {{node_kb.context}} into its user prompt and writes the model’s answer under node_summary.

Validate the answer

node_guard checks {{node_summary}} for PII and writes its validation envelope under node_guard, blocking the run if a check fails.

Workflow nodes (excerpt)

{
  "nodes": [
    {
      "id": "node_kb",
      "type": "knowledge",
      "name": "Search handbook",
      "knowledge_config": {
        "credential_id": "cred_kb_handbook",
        "provider_type": "modulexdb",
        "query": "{{input}}",
        "top_k": 5,
        "min_score": 0.3,
        "max_tokens": 2000,
        "output_format": "context"
      }
    },
    {
      "id": "node_summary",
      "type": "llm",
      "name": "Summarize",
      "llm_config": {
        "llm": {
          "integration_name": "modulexai",
          "provider_id": "anthropic",
          "model_id": "claude-haiku-3.5",
          "temperature": 0.4
        },
        "system_prompt": "You answer strictly from the provided context.",
        "user_prompt": "Question: {{input}}\n\nContext:\n{{node_kb.context}}"
      }
    },
    {
      "id": "node_guard",
      "type": "guardrails",
      "name": "Check PII",
      "guardrails_config": {
        "source": "{{node_summary}}",
        "pii_detection": { "enabled": true, "action": "block" },
        "on_failure": "block"
      }
    }
  ],
  "edges": [
    { "source": "__start__", "target": "node_kb" },
    { "source": "node_kb", "target": "node_summary" },
    { "source": "node_summary", "target": "node_guard" }
  ]
}

After a successful run, the final state holds one key per node id:

object

The Knowledge node’s result.

Show properties

integer

Number of chunks retrieved.

array

The retrieved chunks (present when output_format is chunks or both).

string

The chunks formatted into a single context string (referenced by node_summary).

string

The LLM node’s answer — written directly under the node id as a string.

object

The Guardrails node’s validation envelope.

Show properties

boolean

Whether every enabled check passed.

object

Per-check results (json_validation, regex_validation, hallucination_check, pii_detection).

any

The input that was checked.

any

The output after any masking/transform.

boolean

Present and true when on_failure is block and a check failed.

Run it

Run the workflow over the API or an SDK. Streaming the run lets you watch each node_update arrive — one per node, keyed by node with the per-node output — followed by done. See Run via API and SSE run streaming for the full event taxonomy.

curl -X POST "https://api.modulex.dev/workflows/run" \
  -H "Authorization: Bearer mx_live_xxx" \
  -H "X-Organization-ID: org_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_xxx",
    "input": "What is our refund policy?"
  }'

from modulex import ModuleX

client = ModuleX(
    api_key="mx_live_xxx",
    organization_id="org_xxx",
)

run = client.workflows.run(
    workflow_id="wf_xxx",
    input="What is our refund policy?",
)
print(run)

import { ModuleX } from "modulex";

const client = new ModuleX({
  apiKey: "mx_live_xxx",
  organizationId: "org_xxx",
});

const run = await client.workflows.run("wf_xxx", {
  input: "What is our refund policy?",
});
console.log(run);

The run surface is behind the billing gate. When an organization is out of credits or over a limit, the run endpoint returns a flat denial envelope — {code, layer, key, current, limit, reason} — as 402 / 403 / 429, not the plain {detail} shape used by CRUD routes. See Errors & status codes for all three envelope shapes.

Per-node references

Each node’s page documents every config field with its type, default, and required/optional flag, every input it reads, the exact shape it writes, every error it can raise, and its credit impact.

LLM node

Call a model with prompts and optional structured output.

Agent node

A model-plus-tools loop that runs until done.

Tool node

Call one integration tool deterministically.

Knowledge node

Retrieve RAG context from a knowledge base.

Function node

HTTP request, webhook, or schema validation.

Transformer node

Reshape, map, filter, and convert data.

Conditional node

Branch on expressions or LLM decisions, or loop.

Guardrails node

Validate content and block, warn, transform, or route.

Interrupt node

Pause for a human answer, then resume.

Workflow engine & nodes

How nodes compile into a graph, the run state, edges, and loops.

Variables & references

The full {{node_id.field}} resolution rules, reducers, and run state.

Error handling & retries

How node failures surface and how retries behave.

Glossary

Canonical ModuleX terminology, including every node term.

App overview

Chat

Knowledge

Collaboration

Builder

Nodes

Execution

Co-editing

Assistant Chat

The nine node types

Pick a node by intent

The output-to-state convention

Referencing earlier results: `{{node_id.field}}`

What every node shares

How a node fails

Credit impact

How to pick a node

Worked example: a three-node retrieve-and-summarize flow

Run it

Per-node references

LLM node

Agent node

Tool node

Knowledge node

Function node

Transformer node

Conditional node

Guardrails node

Interrupt node

Workflow engine & nodes

Variables & references

Error handling & retries

Glossary

​The nine node types

Pick a node by intent

​The output-to-state convention

​Referencing earlier results: {{node_id.field}}

​What every node shares

​How a node fails

​Credit impact

​How to pick a node

​Worked example: a three-node retrieve-and-summarize flow

​Run it

​Per-node references

LLM node

Agent node

Tool node

Knowledge node

Function node

Transformer node

Conditional node

Guardrails node

Interrupt node

​Related

Workflow engine & nodes

Variables & references

Error handling & retries

Glossary

The nine node types

The output-to-state convention

Referencing earlier results: `{{node_id.field}}`

What every node shares

How a node fails

Credit impact

How to pick a node

Worked example: a three-node retrieve-and-summarize flow

Run it

Per-node references

Related