Design and Run Flows

Overview of Flows

A Flow is a standalone executable workflow represented as an explicit graph of typed inputs, outputs, nodes, control-flow connections, and optional data-flow connections. Execution begins at one StartNode, follows declared paths, transfers values through explicit edges, and completes at an EndNode; control flow determines which nodes may execute, while data flow determines which values they receive. Flows support branching, mapping, parallelism, nested subflows, reusable agents, tools, and model invocations, providing validated, inspectable, and repeatable workflow structure.

StartNode

A StartNode is the entry point of a Flow, identified by the Flow’s start_node field. It exposes caller-supplied Flow inputs as named outputs, which downstream nodes can receive only through declared data-flow connections. Its contract defines component identity, optional inputs and outputs, and branch names for outgoing control-flow edges; it does not itself determine downstream data or execution beyond the graph connections.

EndNode

An EndNode marks completion of a Flow path and maps values received through data-flow edges to the enclosing Flow’s output contract. A Flow may contain multiple EndNodes for different valid outcomes, with each reachable EndNode returning compatible output values and optionally identifying a branch_name. For top-level Flows, these mapped values are returned to the caller; for nested Flows, they become outputs of the enclosing component.

ToolNode

A ToolNode invokes one predefined Tool at a declared point in a Flow, using typed inputs and producing typed outputs without model-selected operation choice. The node defines the graph-facing contract, branches, and reference to the Tool, while the referenced Tool defines operation-specific details such as PL/SQL configuration. Control-flow edges determine when the node executes, data-flow edges supply arguments and transfer results, and compatible Tool and ToolNode contracts are required.

LLMNode

An LlmNode performs one predetermined model invocation, such as summarization, classification, or generation, without iterative reasoning or tool calling. It receives typed inputs, renders them into a required prompt_template using case-sensitive variable names, invokes the referenced LLM configuration, and maps the model response to declared outputs. Provider, endpoint, model, credentials, generation parameters, and expected response format must be compatible, while explicit data-flow edges connect the node’s inputs and outputs to other components.

AgentNode

An AgentNode executes a referenced Agent as one component within a Flow, exposing its own typed input, output, branch, and graph identity contracts. The referenced Agent performs iterative model reasoning and tool-calling using its instructions, LLM configuration, and available Tools, then returns a result through the AgentNode outputs. Flow edges connect to the AgentNode rather than the Agent internals, and the AgentNode and Agent contracts must remain compatible.

BranchingNode

A BranchingNode selects one declared branch by evaluating exactly one typed input against its mapping. The selected branch must be declared in branches and correspond to an outgoing control-flow edge with the matching from_branch; edges for other branches are not followed. Branch selection controls execution only and does not transfer values, so separate data-flow edges must provide the decision or other required inputs to downstream handlers.

FlowNode

A FlowNode embeds a reusable subflow within an enclosing Flow while presenting the subflow as a single graph component. It maps compatible inputs into the referenced Flow, starts that subflow at its StartNode, maps the reached EndNode’s outputs back to its own outputs, and exposes the resulting branch for continuation. The enclosing and nested graphs remain separate, and their input and output counts, names, and types must satisfy the required compatibility rules.

MapNode

A MapNode executes the same subflow once for each item in an input collection, maps each item to the subflow’s compatible scalar input, and combines selected outputs through reducers. Its contract defines collection-boundary names, while the subflow handles one item per execution and runs from StartNode to EndNode. Supported reducers include append, sum, average, min, and max; omitted reducers default to append. The example maps order IDs to an order-lookup subflow, appends returned statuses, and exposes the combined array through the enclosing Flow. A complete runnable specification demonstrates execution with three order IDs and returns their corresponding statuses.

Parallelism

Parallel execution runs independent work concurrently without changing component contracts, reference resolution, type compatibility, or reducer behavior. ParallelFlowNode executes multiple different, independent subflows and exposes each subflow’s uniquely provided outputs, while ParallelMapNode executes the same subflow concurrently for every item in a collection and reduces the results according to configured reducers. Completion order is nondeterministic, and dependencies between operations require sequential control and data flow instead. Examples show concurrent shipment, payment, and return checks for one order, plus concurrent status lookups for multiple orders using an append reducer.

End-to-End Workflow Example

This order-support workflow demonstrates coordinated control flow, data flow, and processing nodes for three request types: order-status inquiries use a reusable FlowNode, return requests invoke a predetermined ToolNode, and general questions use an AgentNode. The StartNode publishes request data, a BranchingNode maps request_type to one declared branch, and only the selected path executes before transferring its result to the corresponding EndNode and common response output. Data-flow edges explicitly supply each node’s required inputs, while control-flow edges determine execution. The runnable specification includes database operations, nested flow and tool references, agent configuration, and an example return-request execution that produces a customer-facing eligibility response.
Read More: End-to-End Workflow Example