Skip to main content

Overview

The SequentialWorkflow class orchestrates the execution of a sequence of agents in a defined workflow. This class enables the construction and execution of a workflow where multiple agents (or callables) are executed in a specified order, passing tasks and optional data through the chain.

Key Features

  • Sequential Execution: Agents execute one after another in a defined order
  • Synchronous and Asynchronous Support: Both blocking and non-blocking execution modes
  • Batched Processing: Execute multiple tasks through the same workflow
  • Concurrent Task Processing: Run multiple tasks concurrently using thread pools
  • Team Awareness: Agents can be aware of their position in the team structure
  • Auto-save Support: Automatically save conversation history to workspace
  • Flexible Output Types: Support for various output formats (dict, list, string)

Installation

Class Definition

Parameters

id
str
default:"sequential_workflow"
Unique identifier for the workflow instance
name
str
default:"SequentialWorkflow"
Human-readable name for the workflow
description
str
Description of the workflow’s purpose
agents
List[Union[Agent, Callable]]
required
List of agents or callables to execute in sequence. Cannot be None or empty.
max_loops
int
default:"1"
Maximum number of times to execute the workflow. Must be greater than 0.
output_type
OutputType
default:"dict"
Format of the output from the workflow. Options include “dict”, “list”, “str”, etc.
shared_memory_system
callable
default:"None"
Optional callable for managing shared memory between agents
multi_agent_collab_prompt
bool
default:"False"
If True, appends a collaborative prompt to each agent’s system prompt
team_awareness
bool
default:"False"
Whether agents are aware of the team structure and their position
autosave
bool
default:"True"
Whether to enable autosaving of conversation history to workspace
verbose
bool
default:"False"
Whether to enable verbose logging
drift_detection
bool
default:"False"
If True, a judge agent scores the final output’s semantic alignment with the original task after the pipeline completes. If the score falls below drift_threshold, the pipeline reruns and the cycle repeats until the score meets the threshold. If the judge output cannot be parsed, drift checking is skipped and the last result is returned as-is.
drift_threshold
float
default:"0.75"
Minimum alignment score (0.0–1.0) to consider the output acceptable. A warning is logged when the score falls below this value, and the pipeline reruns. Used only when drift_detection=True.
drift_model
str
default:"claude-sonnet-4-5"
Model used by the drift detection judge agent. Used only when drift_detection=True.

Methods

run(task, img=None, imgs=None, *args, **kwargs)

Executes a specified task through the agents in the dynamically constructed flow. If drift_detection is configured, a judge agent scores the final output’s semantic alignment with the original task after the pipeline completes. If the score falls below drift_threshold, the pipeline reruns and the cycle repeats until the score meets the threshold.
task
str
required
The task for the agents to execute
img
Optional[str]
default:"None"
An optional image input forwarded to every agent that supports it
imgs
Optional[List[str]]
default:"None"
Optional list of images. Accepted for API compatibility; only img is currently forwarded to the underlying flow.
result
str | dict | list
The final result, formatted per output_type

run_batched(tasks)

Executes a batch of tasks through the agents sequentially.
tasks
List[str]
required
A list of tasks for the agents to execute. Must be a non-empty list of strings.
results
List[str]
A list of final results after processing through all agents

run_async(task)

Executes the specified task through the agents asynchronously.
task
str
required
The task for the agents to execute. Must be a non-empty string.
result
str
The final result after processing through all agents

run_concurrent(tasks)

Executes a batch of tasks through the agents concurrently using ThreadPoolExecutor.
tasks
List[str]
required
A list of tasks for the agents to execute. Must be a non-empty list of strings.
results
List[str]
A list of final results after processing through all agents

run_stream(task, img=None, with_events=False, **kwargs)

Stream tokens from each agent in pipeline order, in real time. Each agent’s tokens are yielded the moment the LLM produces them; once an agent finishes, its full output is handed off to the next agent — the same hand-off as run(), just streamed. Delegates to AgentRearrange.run_stream internally.
task
str
required
Initial task passed to the first agent in the pipeline.
img
Optional[str]
default:"None"
Optional image input forwarded to every agent.
with_events
bool
default:"False"
When False, yield plain token strings. When True, yield structured event dicts (agent_start, token, agent_end) — useful for per-agent UI panels or attributing each token to its emitting agent.
generator
Iterator[str | dict]
Sync generator. Yields plain token strings by default, or event dicts when with_events=True.

arun_stream(task, img=None, with_events=False, **kwargs)

Async generator version of run_stream. Drop-in for any async caller (FastAPI’s StreamingResponse, async background workers, etc.). Same parameter and yield semantics as the sync version.
async_generator
AsyncIterator[str | dict]
Async generator. Yields plain token strings by default, or event dicts when with_events=True.

Structured events

When called with with_events=True, both methods yield three event types:
max_loops > 1 and drift_detection are not applied in streaming mode. Use run() if you need those.

sequential_flow()

Constructs a string representation of the agent execution order.
flow
str
A string showing the order of agent execution (e.g., “AgentA -> AgentB -> AgentC”)

reliability_check()

Validates the workflow configuration and prepares agents for execution. Raises:
  • ValueError: If the agents list is None or empty, or if max_loops is set to 0

Attributes

Usage Examples

Basic Sequential Workflow

Batched Task Processing

Concurrent Task Execution

Async Execution

With Team Awareness

Custom Output Types

With Autosave

Error Handling

Best Practices

  1. Agent Design: Ensure each agent has a clear, specific role in the sequence
  2. Error Handling: Use try-except blocks around workflow execution
  3. Verbose Mode: Enable verbose logging during development for debugging
  4. Autosave: Enable autosave for important workflows to preserve conversation history
  5. Task Clarity: Provide clear, specific tasks to get the best results
  6. Resource Management: Use run_concurrent for I/O-bound tasks to improve performance
  7. Team Awareness: Enable team awareness for complex workflows where context matters

Common Use Cases

  • Content Creation Pipelines: Research -> Write -> Edit workflows
  • Data Processing: Extract -> Transform -> Load (ETL) pipelines
  • Analysis Workflows: Collect -> Analyze -> Report sequences
  • Quality Assurance: Create -> Review -> Approve chains
  • Multi-Stage Reasoning: Break complex problems into sequential steps