Sequential Agent

Purpose

The Sequential Agent addresses the need within the broader Agent Workflow Management topic to execute multiple sub-agents in a strict, predefined order exactly once. This pattern is essential for pipeline-style workflows where each agent performs a step that depends on the previous step's output. Unlike the other workflow agents—such as the Parallel Agent which runs sub-agents concurrently, or the Loop Agent which repeats execution—the Sequential Agent guarantees a linear, predictable progression through its sub-agent sequence.

This deterministic ordering simplifies error handling, debugging, and reasoning about the workflow, making it ideal for scenarios where each step must complete successfully before the next begins.

Functionality

The Sequential Agent is implemented as a specialized wrapper around the more generic Loop Agent configured to run exactly one iteration (MaxIterations=1). This reuse leverages the Loop Agent’s iteration and sub-agent orchestration logic while constraining execution to a single pass through the sub-agent list.

Key Behaviors:

• Fixed ordering: Sub-agents are executed one after another in the order they are provided in the configuration.

• Single iteration: Each sub-agent runs once per invocation of the Sequential Agent.

• Sub-agent uniqueness enforcement: The agent validates that sub-agent names are unique within its entire agent tree, preventing ambiguous execution or conflicts.

• State and type tagging: Internally, the agent sets its type to TypeSequentialAgent for diagnostics and runtime identification.

Workflow Overview:

1. The Sequential Agent receives an invocation request.

2. It triggers execution of the first sub-agent.

3. Once the first sub-agent completes, the second sub-agent is invoked.

4. This process continues until all sub-agents have run once.

5. The collected events from all sub-agents are aggregated and returned in sequence.

This behavior ensures a linear pipeline effect where the output or side effects of one sub-agent can influence the next.

Code Interaction Example

The core creation function New demonstrates how the Sequential Agent is constructed by wrapping a Loop Agent configured for one iteration:

func New(cfg Config) (agent.Agent, error) {
	sequentialAgent, err := loopagent.New(loopagent.Config{
		AgentConfig:   cfg.AgentConfig,
		MaxIterations: 1, // Ensures a single pass over sub-agents
	})
	// type assertion and internal state tagging omitted for brevity
	return sequentialAgent, nil
}

This design choice simplifies the implementation by reusing the Loop Agent's machinery while restricting execution to a one-time sequence.

Error Handling and Validation

Tests enforce strict constraints on sub-agent composition, including:

• No duplicate sub-agent names anywhere in the hierarchy.

• No sharing of sub-agents between multiple parents.

• Nested Sequential Agents must have unique names distinct from their parents and siblings.

These validations prevent runtime ambiguity and ensure the pipeline integrity.

Integration

The Sequential Agent integrates tightly with the other workflow agents under the Agent Workflow Management umbrella. It complements the Parallel Agent and Loop Agent by providing the simplest linear execution pattern:

• Use Sequential Agent when order matters and concurrency or repetition is not needed.

• Use Parallel Agent to run multiple sub-agents simultaneously for speed or diverse perspectives.

• Use Loop Agent to repeat workflows until a condition is met or a fixed iteration count is reached.

The Sequential Agent also interoperates with:

• LLM Agents: Sub-agents can be LLM-driven, enabling complex prompt chains.

• Session Management: It uses session services to persist state and events across the sequential steps.

• Runner: Execution is coordinated by the Agent Execution Runner, which manages invoking the Sequential Agent and handling its emitted events.

Diagram

flowchart TD
Start[Start Sequential Agent]
SubAgent1[Run Sub-Agent 1]
SubAgent2[Run Sub-Agent 2]
SubAgent3[Run Sub-Agent N]
End[End Sequential Agent]
Start --> SubAgent1 --> SubAgent2 --> SubAgent3 --> End

This flowchart visualizes the core process: each sub-agent executes strictly after the previous completes, forming a linear pipeline. The number of sub-agents (N) is configurable as part of the agent setup, but the sequence is always fixed and runs once.

This linear, single-pass execution approach makes the Sequential Agent an essential building block for orchestrating complex AI workflows where ordered processing is required.