Fundamental Concepts

Core Concepts

Master the building blocks of workflows and nodes

Table of Contents
  1. What Are Workflows?
  2. Understanding Nodes
  3. Connections and Data Flow
  4. Variables and Data Passing
  5. Conditional Logic
  6. Loops and Iterations
  7. Error Handling
  8. Execution Flow
  9. Best Practices
  10. Next Steps

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 Workflow Interface

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.

Agent Builder Nodes Palette

Nodes palette with available node types

Node Types

Nodes are organized into categories based on their function:

  • Input/Output: Handle data entering and leaving the workflow
  • Logic & Control: Make decisions and control execution flow
  • Data Processing: Transform and manipulate data
  • AI Operations: Leverage AI models for intelligent processing
  • Integration: (Coming Soon) Connect to external systems and APIs. Currently, you can deploy agents and workflows outside of Ask Sage and integrate Ask Sage agents into other systems

Node Structure

Every node has:

  1. Input Ports: Where data enters the node
  2. Output Ports: Where processed data exits
  3. Configuration Panel: Settings and parameters
  4. 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 a complete catalog of all available node types, see the Node Reference section.

Connections and Data Flow

How Data Flows

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

Agent Builder Workflows

Example of a workflow showing connections and data flow between nodes

Connection Basics

1

Source Node

Data originates from output port

→
2

Connection

Data travels along the connection

→
3

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

  • Every workflow must have exactly one starter node
  • 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 conversion nodes when needed.

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.

Agent Builder Output Save

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

  1. Set Variables: Store data for later use
  2. Get Variables: Retrieve stored data
  3. Update Variables: Modify existing values
  4. 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.

Agent Builder Conditional Logic

Example of conditional logic in a workflow

Types of Conditional Nodes

IF/THEN/ELSE

Basic conditional branching

Test a condition
Two execution paths
Simple decision logic

Switch

Multiple path branching

Match multiple cases
Many execution paths
Default fallback option

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.

Agent Builder Loop Example

Example of a loop in a workflow

Loop Types

  1. For Each Loop: Iterate over items in a collection
  2. Count Loop: Repeat a specific number of times

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.

Agent Builder Execution Logs

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

Error Handling Strategies

1

Try

Attempt operation

→
2

Catch

Handle errors

→
3

Finally

Cleanup actions

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

  • Retry: Attempt the operation again
  • Fallback: Use alternative path or default value
  • Log and Continue: Record error and proceed
  • Fail Gracefully: Stop execution with informative message
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:

  1. Start Nodes: Nodes with no inputs execute first
  2. Sequential Execution: Nodes execute when all inputs are ready
  3. 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 the Advanced Techniques section.

Best Practices

Workflow Design Best Practices

Design Principles

  1. Keep It Simple: Start with simple workflows and add complexity gradually
  2. Modular Design: Break complex workflows into reusable components
  3. Clear Naming: Use descriptive names for nodes and variables
  4. 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:

Workflows & Nodes
Explore all available node types and their capabilities
→
First Workflow Tutorial
Apply these concepts to build real workflows
→
Use Cases & Examples Under Construction
See these concepts in action with real examples
→

Back to top

Copyright © 2025 Ask Sage Inc. All Rights Reserved.