Fundamental Concepts

Core Concepts

Master the building blocks of workflows and nodes

Table of Contents

Agents vs Workflows
What Are Workflows?
Understanding Nodes
Connections and Data Flow
Variables and Data Passing
Conditional Logic
Loops and Iterations
Error Handling
Execution Flow
Best Practices
Next Steps

Agents vs Workflows

Two Concepts, One System

Agent Builder distinguishes between an Agent (the persona that runs) and a Workflow (the visual logic the persona executes). One Agent runs exactly one Workflow.

Agent

The configurable persona

Name and description

System prompt

Default model and temperature

Agent-level variables

Workflow

The visual logic the agent runs

Directed graph of nodes

Up to 50 nodes per workflow

Edited on the canvas

Exported as JSON

  Quick mental model: Think of the Agent as who is running and the Workflow as what it does. The editor's Agent tab configures the persona; the canvas and Palette tab define the workflow. 

What Are Workflows?

Understanding Workflows

A workflow is a visual representation of your agent's logic - a sequence of connected nodes that define how data flows and transforms through your agent.

Key Characteristics

Visual Design: Workflows are created using a drag-and-drop canvas
Node-Based: Composed of individual nodes, each performing a specific function
Data Flow: Information flows from node to node through connections
Reusable: Workflows can be saved, shared, and reused

Sharing Workflows

While in-platform sharing is currently in development, you can share your workflow builds with others using the Import/Export functionality:

Export: Use the Import/Export button to download your workflow as a JSON file
Share: Send the exported JSON file to other users
Import: Recipients can use the Import/Export button to load your workflow into their Agent Builder

Import/Export interface for sharing workflows

Coming Soon: Native in-platform workflow sharing is under development, which will make it even easier to collaborate and share your builds with the community.

Workflow Components

Nodes

Individual processing units

Perform specific tasks

Have inputs and outputs

Configurable parameters

Connections

Links between nodes

Define data flow direction

Pass data between nodes

Create execution order

  Think of it this way: A workflow is like a recipe - nodes are the steps, connections show the order, and data is the ingredients flowing through each step. 

Understanding Nodes

Node Fundamentals

Nodes are the building blocks of workflows. Each node performs a specific operation and can be configured to meet your needs.

Nodes palette with available node types

Node Types

Nodes are organized into categories based on their function:

AI Operations: LLM, Decision Tree, Train File, Train Array, and Text to Speech nodes — call a model, classify and route, ingest into a dataset, or generate audio
Control Flow: If/Else, Loop, and Return Response nodes — branch on a condition, iterate over a collection, and end the workflow with a response
Data: Save Variable, Transform Variables, and Read File nodes — store, reshape, and load data for downstream nodes
Integration: the API Call node — make an outbound HTTPS request to an external service and use its status code and body downstream

That is the complete set of twelve node types. To call a finished agent from an external system, use the Ask Sage API — see API & Integration.

Node Structure

Every node has:

Input Ports: Where data enters the node
Output Ports: Where processed data exits
Configuration Panel: Settings and parameters
Status Indicator: Shows execution state (available when running the workflow in agent mode)

Node Properties

Name: Identify the node in your workflow
Type: Determines what the node does
Parameters: Configure the node's behavior
Connections: Links to other nodes

Node Reference: For the configuration options of every node type, see Workflows & Nodes.

Connections and Data Flow

How Data Flows

Connections define how data moves through your workflow. Understanding data flow is crucial for building effective agents.

Example of a workflow showing connections and data flow between nodes

Connection Basics

Source Node

Data originates from output port

→

Connection

Data travels along the connection

→

Target Node

Data arrives at input port

Data Types

Connections can carry different types of data:

Text/String: Textual information
Number: Numeric values
Boolean: True/false values
Object: Complex structured data
Array: Lists of items
Any: Flexible data type

Connection Rules

Execution starts at the entry node — the node with no incoming connection. Keep a single entry point
Workflows execute in a single direction from start to finish
Output types must match input types
Circular connections are not allowed (unless using loop nodes)
Disconnected nodes won't execute
No parallel processing - nodes execute sequentially in order

  Type Matching: Always ensure the output data type matches the expected input type. Use a Transform Variables node to reshape data when it does not. 

Variables and Data Passing

Working with Variables

Variables allow you to store and reuse data throughout your workflow, making your agents more flexible and powerful.

Saving output data to variables in the workflow

Variable Basics

Definition: Named storage for data values
Scope: Can be workflow-wide or node-specific
Types: Support all data types (text, number, object, etc.)
Reference: Access variables from any node

Using Variables

Set Variables: Store data for later use
Get Variables: Retrieve stored data
Update Variables: Modify existing values
Delete Variables: Remove when no longer needed

Best Practices

Use descriptive variable names
Initialize variables before use
Clean up unused variables
Document complex variable usage

Naming Convention: Use camelCase or snake_case for variable names (e.g., userInput, response_data).

Conditional Logic

Making Decisions

Conditional logic allows your workflow to make decisions and take different paths based on conditions.

Example of conditional logic in a workflow

Types of Conditional Nodes

If/Else Node

Boolean conditional branching (type: if_else)

Test a condition on a variable

Two execution paths: true and false

Deterministic, no model call

Decision Tree Node

AI-powered multi-path routing (type: decision_tree)

Model classifies the input

Routes to one of many branches

Define a default branch for unmatched cases

Common Conditions

Comparison: Equal, not equal, greater than, less than
Logical: AND, OR, NOT
Existence: Is null, is empty, exists
Pattern: Matches regex, contains text

  Complex Logic: Combine multiple conditional nodes to create sophisticated decision trees for your workflows. 

Loops and Iterations

Repeating Operations

Loops allow you to repeat operations multiple times or process collections of data efficiently.

Example of a loop in a workflow

Loop Types

The Loop Node (type: loop) iterates over the items of an array variable — for example the rows of a CSV loaded by a Read File node. To repeat a fixed number of times, loop over an array with that many items.

Loop Components

Iteration Variable: Current item being processed
Loop Body: Nodes executed on each iteration

Best Practices

Avoid infinite loops
Process data in batches for large collections
Monitor performance with loops

Performance Tip: Be cautious with loops in workflows - processing large collections can consume significant tokens and time.

Error Handling

Handling Errors Gracefully

Proper error handling ensures your workflows handle unexpected situations gracefully and provide useful feedback.

Agents in the UI display execution logs showing how the workflow is operating, including error details and execution status for each node

Exporting Logs: Logs can be exported in full or one section at a time as a Word document - see Exporting Logs and Results in the First Workflow tutorial.

Error Handling Strategies

Agent Builder has no dedicated try/catch construct. A node that fails stops the run and reports the error in the execution logs. Design for that:

Validate early

Use an If/Else node to check inputs before expensive LLM calls

→

Route the unexpected

Give Decision Tree nodes a default branch that ends in a clear Return Response

→

Read the logs

Fix the failing node's configuration and re-run

Error Types

Validation Errors: Invalid input data
Connection Errors: Network or API failures
Processing Errors: Node execution failures
Timeout Errors: Operations taking too long

Recovery Options

Re-run: Correct the node configuration or input and run the agent again
Fallback branch: Route unmatched or invalid cases to an alternative path with an If/Else or Decision Tree node
Informative terminal response: End fallback branches with a Return Response node that explains what was missing

  Best Practice: Always include error handling for external API calls and user input validation. 

Execution Flow

How Workflows Execute

Understanding how workflows execute helps you design more efficient and predictable agents.

Execution Order

Workflows execute in a specific order:

Entry Node: The node with no incoming connection executes first
Sequential Execution: Nodes execute when all inputs are ready
Completion: Workflow finishes when all paths complete

Execution States

Pending: Waiting to execute
Running: Currently executing
Success: Completed successfully
Failed: Encountered an error
Skipped: Bypassed due to conditions

Performance Considerations

Token Usage: AI operations consume tokens
Execution Time: Complex workflows take longer
Resource Limits: Stay within platform limits

Optimization: For performance optimization techniques, see Advanced Techniques.

Best Practices

Workflow Design Best Practices

Design Principles

Keep It Simple: Start with simple workflows and add complexity gradually
Modular Design: Break complex workflows into reusable components
Clear Naming: Use descriptive names for nodes and variables
Test Incrementally: Test as you build, not just at the end

Avoid Common Pitfalls

Don't create overly complex workflows
Don't skip error handling
Don't ignore data type mismatches
Don't forget to test edge cases
Don't create circular dependencies

Organization Tips

Group related nodes together
Use consistent naming conventions
Keep workflows focused on single tasks
Create reusable sub-workflows

  Learn More: Check out the Building Workflows section for practical application of these concepts. 

Next Steps

Continue Learning

Now that you understand the core concepts, explore these topics: