Node anatomyCopy Anchor Link

A node is one configured unit of work in a saved ActionFlow. It has an instance ID, a catalog type and function, saved configuration, declared inputs and outputs, and—when the node executes—an input object and result from its runtime function.

A node is not a pure function. AI calls, HTTP requests, database operations, messages, file generation, and control decisions can be non-deterministic or have external side effects. The canvas describes intended work; the node function and its providers decide the actual result.

What a node containsCopy Anchor Link

A catalog node, a node instance, and a runtime result are different things. The catalog describes available configuration; the instance stores your choices; the result records one execution.

Node categoriesCopy Anchor Link

The current node model includes these operational categories:

• Start: begins an ActionFlow run.
• AI: calls a model through the selected service and model.
• Communication: sends or receives messages through a provider.
• Control: selects paths, repeats a body, transforms branch values, or waits.
• Data: parses, queries, validates, sorts, or transforms data.
• HITL: pauses for a human decision.
• Integration: calls a third-party service.
• Storage: stores or retrieves files.
• Utility: performs HTTP, math, string, date, crypto, scraping, or Action Agent work.
• Sticky: annotates the canvas and is not part of node execution.

The node's function selects the implementation under packages/nodes/functions. Start nodes and a few special shapes can return their assembled inputs directly; other nodes call the mapped function. A missing implementation can therefore produce an input pass-through or a runtime function error rather than a successful declared output.

Handles and edgesCopy Anchor Link

A handle is a canvas connection point. Handles do not form a static type system. The current graph uses them for different runtime jobs:

• Node-level execution handles sequence one node after another.
• Named data mappings assign a selected output path to a named input in the saved graph.
• Output chips store {{nodeId.outputPath}} references in inspector fields.
• If and Switch lane handles select a branch.
• Loop body handles mark the nodes that run once per item.

The normal node-source and node-target handles, and saved edges with missing handles, are treated as the default execution connection. An untargeted default edge also exposes the source result under the source-node ID in the target's input object; it does not select a named target input.

See Handles for the saved handle contract and Inputs for value resolution.

Sequential executionCopy Anchor Link

The current runner processes node work sequentially and depth-first:

1. Find the first start node in the saved graph.
2. Build that node's inputs.
3. Execute its node function.
4. Store the result.
5. Visit eligible outgoing edges in order. A target and its descendants finish before the next eligible edge is visited.
6. If or Switch follows only the selected lane. Loop repeats its body sequentially for each item.
7. Stop the normal path when a node throws or reports an unhandled failure.

There is no parallel branch scheduler. A node that has already executed is normally not executed again merely because another edge points to it. Loop body descendants are explicitly cleared from the executed set before each iteration so that the body can run again.

The detailed behavior, including Loop context, Merge, Wait, HITL, and failure state, is in Flow execution model.

Design-time feedback is not runtime proofCopy Anchor Link

Actionflow Studio provides several useful checks before execution:

• a node cannot connect to itself;
• a start node cannot be the target of a connection;
• occupied equivalent handles normally cannot be reused; shared loop-body-out joins into If/Switch are the target-side exception, and loop-target is equivalent to the other default target handles;
• Loop and control-body connections must stay in a compatible scope;
• an output chip drop can check the declared data type, cardinality, and allowed upstream node; and
• required indicators and inspector warnings can show missing inputs; Flow Requirements can show missing credentials.

These checks describe the current editor and catalog. They do not compile the saved JSON, prove every nested object shape, validate every external payload, or guarantee that a node function will succeed.

validateFlow adds server-side graph and requirement checks for nodes reachable from a start node. It primarily checks presence and configuration: graph structure, start nodes, enabled catalog rows, present/resolvable credential records, AI model selection, required input presence, and Loop configuration. It is not a full value or output-type validator and does not verify secret validity.

At runtime, the node function, model provider, database, or external API validates the values it actually receives. A function can return success: false; an exception stops execution immediately. continueOnError can let traversal continue after a reported success: false result, but it does not turn a thrown exception into a successful node.

Outputs and run historyCopy Anchor Link

Catalog output definitions are discovery metadata. The runtime result is whatever the executed function returns, so a downstream reference can be empty or missing even when the catalog lists an output.

Actionflow Studio's active Run Output surface can show current node progress and results. Terminal run history is a persisted and sanitized audit view, not an unlimited copy of every raw request, provider response, or secret:

• repeated Loop-body results stored between iterations are capped at 100,000 serialized characters and marked when truncated;
• the public history read path keeps selected metadata and redacts recognized sensitive-looking result keys; and
• custom result fields can still contain business or personal data, so handle history according to your data-retention needs.

See Run history and Flow troubleshooting.

Debugging a nodeCopy Anchor Link

1. Confirm that the node is reachable from the start node.
2. Inspect the saved input values and any {{nodeId.outputPath}} reference.
3. Confirm the selected model or named organization connection.
4. Run the full graph and inspect the node's resolved input.
5. Check whether the function threw or returned success: false.
6. Inspect the actual result path used by the downstream node.

RelatedCopy Anchor Link

• Handles
• Node inputs
• Node requirements
• ActionFlow requirements
• Flow execution model
• Node settings