agent.go

Overview

This file implements the SequentialAgent, a specialized workflow agent designed to execute multiple sub-agents strictly in a fixed, sequential order exactly once. It belongs to the sequentialagent package and provides a mechanism to compose AI workflows where steps must run one after another in a deterministic pipeline fashion.

The SequentialAgent is constructed as a thin wrapper around the more generic LoopAgent configured to run a single iteration (MaxIterations: 1). This design enables reuse of the LoopAgent’s orchestration and sub-agent management logic while enforcing a single-pass execution.

The primary use case for this agent is when the execution order matters and you want each sub-agent to run once in strict sequence, ensuring that the output or side effects of earlier sub-agents can influence subsequent ones.

Package and Imports

• Package: sequentialagent — provides the SequentialAgent implementation.

• Imports:

  • fmt — for error formatting.

  • agent — core agent interfaces and types.

  • loopagent — used to create the underlying LoopAgent configured for single iteration.

  • agentinternal — internal agent representation for setting agent type and configuration.

Classes and Types

Config

type Config struct {
	AgentConfig agent.Config
}

• Purpose: Defines the configuration for the SequentialAgent.

• Fields:

  • AgentConfig (agent.Config): Basic agent setup configuration including sub-agents, metadata, and runtime parameters.

• Usage: Passed to the New function to create a SequentialAgent instance.

Functions and Methods

New(cfg Config) (agent.Agent, error)

func New(cfg Config) (agent.Agent, error)

• Purpose: Constructs a new SequentialAgent instance.

• Parameters:

  • cfg (Config): Configuration containing the AgentConfig with sub-agents and settings.

• Returns:

  • An agent.Agent representing the SequentialAgent.

  • An error if creation or type assertion fails.

• Description:

  • Internally calls loopagent.New with MaxIterations set to 1 to create a LoopAgent that runs sub-agents exactly once.

  • Performs a type assertion to the internal agent interface (agentinternal.Agent) to access and modify internal state.

  • Sets the agent type to TypeSequentialAgent for diagnostics and runtime identification.

  • Copies the configuration into the internal state for reference.

• Usage Example:

  cfg := sequentialagent.Config{
      AgentConfig: agent.Config{
          // Set sub-agents and other configuration here
      },
  }
  seqAgent, err := sequentialagent.New(cfg)
  if err != nil {
      // handle error
  }
  // seqAgent can now be run within an invocation context
  

• Error Handling:

  • Returns an error if loopagent.New fails.

  • Returns an error if the created agent cannot be converted to the internal agent type, indicating an internal implementation issue.

Implementation Details

• The SequentialAgent does not implement its own execution logic but reuses the LoopAgent’s framework by constraining it to run a single iteration, thereby executing all sub-agents once in order.

• Internal state manipulation through agentinternal.Reveal allows tagging the agent type and storing the configuration for introspection and debugging.

• The agent’s strict execution order and single pass make it suitable for pipeline workflows where each step must complete before the next starts.

• Validation of sub-agent uniqueness and tree structure is enforced by LoopAgent and higher-level tests to prevent ambiguous or conflicting workflows.

Interaction with Other System Components

• LoopAgent: SequentialAgent is a specialized instance of LoopAgent with a fixed iteration count (MaxIterations=1), leveraging its sub-agent orchestration.

• Agent Framework: Implements the standard agent.Agent interface, allowing it to be used interchangeably with other agents.

• Sub-Agents: The SequentialAgent executes a list of sub-agents defined in its configuration, which can be any type of agent, including LLM-driven agents or other workflow agents.

• Invocation Context: The agent executes within an agent.InvocationContext which manages session state, memory, and artifacts.

• Session Management & Runner: Execution results in a stream of session.Events that are managed and persisted by the session service and executed by the agent runner (Agent Execution Runner).

• Agent Type Identification: Internal tagging facilitates telemetry, diagnostics, and skill building by identifying this agent as a SequentialAgent (Sequential Agent).

Visual Diagram

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

This flowchart illustrates the core workflow of the SequentialAgent: it runs each sub-agent one after another in a strict order and only once, forming a linear pipeline.

References to Related Topics

• Agent Workflow Management: Provides broader context on workflow agents including sequential, parallel, and loop patterns.

• Loop Agent: The underlying agent used by SequentialAgent to perform iteration control.

• Agent Execution Runner: Coordinates lifecycle and execution of agents including SequentialAgent.

• LLM Integration and Agents: Sub-agents may include LLM-based agents invoked sequentially.

• Session Management: Manages session state and event persistence during agent execution.