Skip to content

Latest commit

 

History

History
175 lines (130 loc) · 8.67 KB

README.md

File metadata and controls

175 lines (130 loc) · 8.67 KB

Sequential Executor

Complexity: 🟢 Beginner

This example demonstrates how to use the sequential executor functionality with the NVIDIA NeMo Agent Toolkit. The sequential executor is a control flow component that chains multiple functions together, where each function's output becomes the input for the next function. This creates a linear tool execution pipeline that executes functions in a predetermined sequence.

The NeMo Agent Toolkit provides a sequential_executor tool to implement this functionality.

Table of Contents

Key Features

The sequential executor provides the following capabilities:

  • Sequential function chaining: Chain multiple functions together where each function's output becomes the input for the next function
  • Type compatibility checking: Optionally validate that the output type of one function is compatible with the input type of the next function in the chain
  • Error handling: Handle errors gracefully throughout the sequential execution process

Graph Structure

The sequential executor uses a linear graph structure where functions execute in a predetermined order. The following diagram illustrates the sequential executor's workflow:

Sequential Executor Graph Structure

During execution, each function receives the output from the previous function as its input. The sequential executor supports type compatibility checking between adjacent functions, which you can configure as described in the Configuration section.

Note: The sequential executor does not use agents or LLMs during execution.

Configuration

Configure the sequential executor through the config.yml file. The configuration defines individual functions and chains them together using the sequential_executor tool.

Required Configuration Options

The following options are required for the sequential executor:

  • _type: Set to sequential_executor to use the sequential executor tool
  • tool_list: List of functions to execute in order (such as [text_processor, data_analyzer, report_generator])
  • raise_type_incompatibility: Whether to raise an exception if the type compatibility check fails (default: false). The type compatibility check runs before executing the tool list, based on the type annotations of the functions. When set to true, any incompatibility immediately raises an exception. When set to false, incompatibilities generate warning messages and the sequential executor continues execution. Set this to false when functions in the tool list include custom type converters, as the type compatibility check may fail even though the sequential executor can still execute the tool list.
  • return_error_on_exception: Whether to return an error message instead of raising an exception when a tool fails during execution (default: false). When set to true, the sequential executor exits early and returns an error message as the workflow output instead of raising the exception. When set to false, exceptions are re-raised. Set this to true when you want the workflow to gracefully handle uncaught tool failures and immediately return error information to the user.

Optional Configuration Options

  • description: Description of the workflow (default: "Sequential Executor Workflow")
  • tool_execution_config: Configuration for each tool in the sequential execution tool list. Keys must match the tool names from the tool_list
    • use_streaming: Whether to use streaming output for the tool (default: false)

Exceptions

  • SequentialExecutorExit: Raised by a tool to exit the chain early and return a custom message as the workflow output. Unlike return_error_on_exception which handles unexpected errors, this exception is for intentional early termination. Import from nat.plugins.langchain.control_flow.sequential_executor.

Example Configuration

The following examples show different configuration approaches:

Basic Configuration

functions:
  text_processor:
    _type: text_processor
  data_analyzer:
    _type: data_analyzer
  report_generator:
    _type: report_generator

workflow:
  _type: sequential_executor
  tool_list: [text_processor, data_analyzer, report_generator]
  raise_type_incompatibility: false
  return_error_on_exception: false

Configuration with Tool Execution Settings

functions:
  text_processor:
    _type: text_processor
  data_analyzer:
    _type: data_analyzer
  report_generator:
    _type: report_generator

workflow:
  _type: sequential_executor
  tool_list: [text_processor, data_analyzer, report_generator]
  tool_execution_config:
    text_processor:
      use_streaming: false
    data_analyzer:
      use_streaming: false
    report_generator:
      use_streaming: false
  raise_type_incompatibility: false
  return_error_on_exception: false

Installation and Setup

Before running this example, follow the instructions in the Install Guide to create the development environment and install the NeMo Agent Toolkit.

Install this Workflow

From the root directory of the NeMo Agent Toolkit repository, run the following command:

uv pip install -e examples/control_flow/sequential_executor

Run the Workflow

This workflow demonstrates sequential executor functionality by processing raw text through a three-stage pipeline. Each function's output becomes the input for the next function in the chain.

Run the following command from the root of the NeMo Agent Toolkit repository to execute this workflow:

nat run --config_file=examples/control_flow/sequential_executor/configs/config.yml --input "The quick brown fox jumps over the lazy dog. This is a simple test sentence to demonstrate text processing capabilities."

Expected Output

nemo-agent-toolkit % nat run --config_file=examples/control_flow/sequential_executor/configs/config.yml --input "The quick brown fox jumps over the lazy dog. This is a simple test sentence to demonstrate text processing capabilities."
None of PyTorch, TensorFlow >= 2.0, or Flax have been found. Models won't be available and only tokenizers, configuration and file / data utilities can be used.
2025-09-17 15:34:57,004 - nat.cli.commands.start - INFO - Starting NAT from config file: 'examples/control_flow/sequential_executor/configs/config.yml'

Configuration Summary:
--------------------
Workflow Type: sequential_executor
Number of Functions: 3
Number of LLMs: 0
Number of Embedders: 0
Number of Memory: 0
Number of Object Stores: 0
Number of Retrievers: 0
Number of TTC Strategies: 0
Number of Authentication Providers: 0

2025-09-17 15:34:57,571 - nat.front_ends.console.console_front_end_plugin - INFO -
--------------------------------------------------
Workflow Result:
['=== TEXT ANALYSIS REPORT ===\n\nText Statistics:\n  - Word Count: 20\n  - Sentence Count: 2\n  - Average Words per Sentence: 10.0\n  - Text Complexity: Moderate\n\nTop Words:\n  1. quick\n  2. brown\n  3. jumps\n  4. over\n  5. lazy\n\nReport generated successfully.\n==========================']
--------------------------------------------------

This output demonstrates how the sequential executor processes raw text input through multiple functions, creating a complete data processing pipeline that generates a formatted analysis report.