Agent Workflow Management

Overview

The Agent Workflow Management module implements a set of specialized agents designed to orchestrate complex AI workflows by composing and managing multiple sub-agents with different execution patterns. This module provides workflow agents that support:

Sequential execution of sub-agents, running one after another in a strict order.
Parallel execution of sub-agents, running concurrently and independently.
Looping execution of sub-agents for iterative or repetitive tasks.

These workflow agents enable the construction of sophisticated AI workflows by coordinating multiple sub-agents, each potentially with distinct behaviors or goals, and managing their execution lifecycle within a unified framework. This orchestration capability is essential for building multi-step, multi-agent AI processes, such as pipelines, ensemble models, or iterative refinement loops.

The module is implemented primarily under the agent/workflowagents/ directory with sub-packages for sequentialagent, parallelagent, and loopagent.

Core Concepts and Purpose

Why Workflow Agents?

While individual AI agents can handle simple tasks, complex applications often require:

Running multiple agents in a defined order.
Running several agents simultaneously to gather diverse outputs.
Iteratively repeating agent execution until convergence or a termination condition.

This module addresses these needs by providing workflow agents that control sub-agent invocation patterns:

SequentialAgent: Executes sub-agents one after another in a fixed, strict sequence.
ParallelAgent: Executes sub-agents concurrently, collecting their outputs asynchronously.
LoopAgent: Executes sub-agents repeatedly, either a fixed number of iterations or indefinitely until a condition triggers termination.

These patterns enhance modularity and reuse, allowing developers to compose complex behaviors from simpler agents.

Interaction with Other System Components

Workflow agents are fully integrated with the broader agent framework:

They use the core agent.Agent interface and lifecycle defined in the agent package.
Sub-agents can be any implementation of agent.Agent, including LLM-based agents (LLM Integration and Agents), tool-based agents, or even other workflow agents, enabling nested workflows.
They run within an invocation context (agent.InvocationContext) that carries session, memory, artifact, and user input state.
Workflow agents produce session events (session.Event) streamed back to the caller, enabling incremental results and interaction.
The module supports integration with the agent execution runner (Agent Execution Runner) which orchestrates execution inside user sessions.
Workflow agents do not directly implement LLM calls or tools but delegate to their sub-agents, which may use those capabilities.

Detailed Functionality and Architecture

SequentialAgent

The SequentialAgent runs its list of sub-agents strictly one after another, waiting for each to complete before starting the next. This ensures deterministic ordering of execution, useful when later steps depend on outputs from earlier steps.

It is implemented as a thin wrapper around the LoopAgent configured to run exactly one iteration (MaxIterations: 1).
The agent's configuration (sequentialagent.Config) includes an agent.Config with the list of sub-agents.
SequentialAgent validates that sub-agent names are unique and that the agent tree does not contain duplicate references to the same sub-agent instance, preventing ambiguous or cyclic workflows.

// SequentialAgent is implemented by wrapping LoopAgent with MaxIterations=1.
func New(cfg Config) (agent.Agent, error) {
	sequentialAgent, err := loopagent.New(loopagent.Config{
		AgentConfig:   cfg.AgentConfig,
		MaxIterations: 1,
	})
	// Further internal state initialization omitted for brevity...
	return sequentialAgent, nil
}

ParallelAgent

The ParallelAgent runs all its sub-agents concurrently in isolated invocation contexts and merges their outputs.

Each sub-agent is invoked in its own goroutine with a child context derived from the parent.
Events produced by sub-agents are sent over a shared channel to the parent agent's event stream.
Errors from any sub-agent are propagated, and cancellation is handled gracefully.
Useful for scenarios like running multiple algorithms simultaneously, generating multiple candidate responses, or running ensemble evaluations.

func run(ctx agent.InvocationContext) iter.Seq2[*session.Event, error] {
	// For each sub-agent, run concurrently in separate goroutine
	// Collect results in resultsChan and yield to caller in order received.
}

LoopAgent

The LoopAgent repeatedly executes its sub-agents in sequence for a configured number of iterations (MaxIterations), or indefinitely if zero.

Each iteration runs all sub-agents in the order defined.
Execution stops early if any sub-agent signals an escalation via the event actions (event.Actions.Escalate).
Suitable for iterative refinement workflows, such as revising outputs until satisfactory or repeatedly polling external data.
Supports nested looping by allowing sub-agents themselves to be workflow agents.

func (a *loopAgent) Run(ctx agent.InvocationContext) iter.Seq2[*session.Event, error] {
	count := a.maxIterations
	return func(yield func(*session.Event, error) bool) {
		for {
			// Run all sub-agents sequentially
			// Exit if escalate action detected or iteration count exhausted
		}
	}
}

Design Patterns and Important Concepts

Composability and Agent Trees

Workflow agents rely on the core agent composition model where agents can have sub-agents forming a tree. This design enables:

Nested workflows: e.g., a SequentialAgent containing ParallelAgents and vice versa.
Reuse of sub-agents across workflows.
Enforced uniqueness of agent names and parent relationships to avoid ambiguous workflows.

The tests in sequentialagent/agent_test.go emphasize strict validation of agent trees to prevent duplicate sub-agent instances or conflicting names.

Invocation Context Branching

ParallelAgent maintains distinct "branches" in the invocation context for each sub-agent execution. This supports tracing and isolation of execution state, facilitating debugging and telemetry.

Yield-Based Event Streaming

All workflow agents expose their execution as an iterator (iter.Seq2) streaming session.Events asynchronously. This design supports:

Incremental consumption of results.
Early termination by the caller.
Integration with session and runner layers that manage event persistence and delivery.

Interactions Between Workflow Agents

The workflow agents can be combined to create complex execution patterns. For example:

A SequentialAgent can include a LoopAgent as a sub-agent to perform an iterative task as one step of a sequence.
A LoopAgent can include ParallelAgent sub-agents to run multiple agents concurrently on each iteration.
These nested compositions enable expressing sophisticated orchestration logic with minimal custom code.

Visual Representation of Agent Workflow Management

flowchart TD
UserInput[User Input]
SequentialAgent[Sequential Agent]
ParallelAgent[Parallel Agent]
LoopAgent[Loop Agent]
SubAgent1[Sub-Agent 1]
SubAgent2[Sub-Agent 2]
SubAgent3[Sub-Agent 3]
EventStream[Session Event Stream]
UserInput --> SequentialAgent
UserInput --> ParallelAgent
UserInput --> LoopAgent
SequentialAgent --> SubAgent1
SequentialAgent --> SubAgent2
SequentialAgent --> SubAgent3
ParallelAgent --> SubAgent1
ParallelAgent --> SubAgent2
ParallelAgent --> SubAgent3
LoopAgent --> SubAgent1
LoopAgent --> SubAgent2
LoopAgent --> SubAgent3
SubAgent1 --> EventStream
SubAgent2 --> EventStream
SubAgent3 --> EventStream

This flowchart illustrates how each workflow agent receives user input and orchestrates the execution of its sub-agents, whose events are streamed back to the session for consumption.

References to Related Topics

The sub-agents run inside an agent.InvocationContext and produce session.Events managed by Session Management.
Sub-agents often include LLM Integration and Agents that wrap language model calls.
Workflow agents' execution is coordinated by the Agent Execution Runner, which handles session state and event persistence.
For composing agents as callable tools, see the Tooling System topic.
Nested workflows may include looping and escalation logic implemented in the Loop Agent subtopic.

This detailed explanation of Agent Workflow Management provides insight into the purpose, design, and internals of the workflow agents enabling complex AI orchestrations within the agent framework.