Sequential Worflow

Author: jeanlaurent

cagent-schema.json

@@ -28,6 +28,13 @@
     "metadata": {
       "$ref": "#/definitions/Metadata",
       "description": "Configuration metadata"
+    },
+    "workflow": {
+      "type": "array",
+      "description": "Sequential workflow steps",
+      "items": {
+        "$ref": "#/definitions/WorkflowStep"
+      }
     }
   },
   "additionalProperties": false,
@@ -413,6 +420,23 @@
       },
       "required": ["path", "cmd"],
       "additionalProperties": false
+    },
+    "WorkflowStep": {
+      "type": "object",
+      "description": "A single step in a workflow",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Type of workflow step",
+          "enum": ["agent"]
+        },
+        "name": {
+          "type": "string",
+          "description": "Name of the agent to run"
+        }
+      },
+      "required": ["type", "name"],
+      "additionalProperties": false
     }
   }
 }

cmd/root/run.go

@@ -23,6 +23,7 @@ import (
 	"github.com/docker/cagent/pkg/app"
 	"github.com/docker/cagent/pkg/chat"
 	"github.com/docker/cagent/pkg/config"
+	v2 "github.com/docker/cagent/pkg/config/v2"
 	"github.com/docker/cagent/pkg/content"
 	"github.com/docker/cagent/pkg/evaluation"
 	"github.com/docker/cagent/pkg/remote"
@@ -32,6 +33,7 @@ import (
 	"github.com/docker/cagent/pkg/teamloader"
 	"github.com/docker/cagent/pkg/telemetry"
 	"github.com/docker/cagent/pkg/tui"
+	"github.com/docker/cagent/pkg/workflow"
 )
 
 var (
@@ -205,6 +207,26 @@ func doRunCommand(ctx context.Context, args []string, exec bool) error {
 				slog.Error("Failed to stop tool sets", "error", err)
 			}
 		}()
+
+		// Check if this is a workflow by loading the config
+		dir := filepath.Dir(agentFilename)
+		fs, err := os.OpenRoot(dir)
+		if err == nil {
+			defer fs.Close()
+			cfg, err := config.LoadConfig(filepath.Base(agentFilename), fs)
+			if err == nil && len(cfg.Workflow) > 0 {
+				// This is a workflow - check if TUI should be used
+				slog.Info("Detected workflow configuration", "steps", len(cfg.Workflow))
+
+				// For exec mode or --tui=false, run without TUI
+				if exec || !useTUI {
+					return runWorkflowCLI(ctx, cfg, agents)
+				}
+
+				// Default: use TUI for workflow
+				return runWorkflowTUI(ctx, agentFilename, cfg, agents)
+			}
+		}
 	} else {
 		// For remote runtime, just store the original agent filename
 		// The remote server will handle agent loading
@@ -882,3 +904,170 @@ func printAvailableCommands(agentName string, cmds map[string]string) {
 		fmt.Printf(" - %s: %s\n", n, cmds[n])
 	}
 }
+
+// runWorkflowCLI executes a sequential workflow in CLI mode (--tui=false)
+func runWorkflowCLI(ctx context.Context, cfg *v2.Config, agents *team.Team) error {
+	executor := workflow.New(cfg, agents)
+
+	// Create an events channel
+	events := make(chan runtime.Event, 128)
+
+	// Run the workflow in a goroutine
+	go func() {
+		defer close(events)
+		if err := executor.Execute(ctx, events); err != nil {
+			events <- runtime.Error(err.Error())
+		}
+	}()
+
+	var lastErr error
+	currentAgent := ""
+	llmIsTyping := false
+
+	for event := range events {
+		switch e := event.(type) {
+		case *runtime.WorkflowStepStartedEvent:
+			if llmIsTyping {
+				fmt.Println()
+				llmIsTyping = false
+			}
+			currentAgent = e.AgentName
+			fmt.Printf("\n%s\n", bold(fmt.Sprintf("⏳ Step %d: Running agent '%s'...", e.StepIndex+1, e.AgentName)))
+
+		case *runtime.WorkflowStepCompletedEvent:
+			if llmIsTyping {
+				fmt.Println()
+				llmIsTyping = false
+			}
+			fmt.Printf("%s\n", bold(fmt.Sprintf("✅ Step %d completed", e.StepIndex+1)))
+
+		case *runtime.WorkflowStepFailedEvent:
+			if llmIsTyping {
+				fmt.Println()
+				llmIsTyping = false
+			}
+			fmt.Printf("%s\n", red("❌ Step %d failed: %s", e.StepIndex+1, e.Error))
+			lastErr = fmt.Errorf("workflow step %d failed: %s", e.StepIndex+1, e.Error)
+
+		case *runtime.WorkflowCompletedEvent:
+			if llmIsTyping {
+				fmt.Println()
+				llmIsTyping = false
+			}
+			fmt.Printf("\n%s\n", bold("🎉 Workflow completed successfully!"))
+			fmt.Printf("\n%s\n", bold("Final Output:"))
+			fmt.Printf("%s\n", e.FinalOutput)
+
+		case *runtime.AgentChoiceEvent:
+			if e.AgentName != currentAgent {
+				if llmIsTyping {
+					fmt.Println()
+				}
+				currentAgent = e.AgentName
+				printAgentName(e.AgentName)
+				llmIsTyping = false
+			}
+			if !llmIsTyping {
+				fmt.Println()
+				llmIsTyping = true
+			}
+			fmt.Print(e.Content)
+
+		case *runtime.ToolCallEvent:
+			if llmIsTyping {
+				fmt.Println()
+				llmIsTyping = false
+			}
+			printToolCall(e.ToolCall)
+
+		case *runtime.ToolCallResponseEvent:
+			if llmIsTyping {
+				fmt.Println()
+				llmIsTyping = false
+			}
+			printToolCallResponse(e.ToolCall, e.Response)
+
+		case *runtime.ErrorEvent:
+			if llmIsTyping {
+				fmt.Println()
+				llmIsTyping = false
+			}
+			lastErr = fmt.Errorf("%s", e.Error)
+			printError(lastErr)
+		}
+	}
+
+	if llmIsTyping {
+		fmt.Println()
+	}
+
+	if lastErr != nil {
+		return lastErr
+	}
+
+	return nil
+}
+
+// runWorkflowTUI executes a sequential workflow in TUI mode (default)
+func runWorkflowTUI(ctx context.Context, agentFilename string, cfg *v2.Config, agents *team.Team) error {
+	// Create a dummy session for workflow tracking
+	sess := session.New()
+	sess.Title = "Workflow: " + filepath.Base(agentFilename)
+
+	// Get the first workflow step's agent for runtime (just for app compatibility)
+	var firstAgentName string
+	if len(cfg.Workflow) > 0 {
+		firstAgentName = cfg.Workflow[0].Name
+	} else {
+		return fmt.Errorf("no workflow steps defined")
+	}
+
+	// Create a minimal runtime (we won't actually use it for execution, just for app compatibility)
+	rt, err := runtime.New(agents,
+		runtime.WithCurrentAgent(firstAgentName),
+		runtime.WithSessionCompaction(false),
+	)
+	if err != nil {
+		return fmt.Errorf("failed to create runtime: %w", err)
+	}
+
+	// Create the app which will handle event forwarding to TUI
+	a := app.New("cagent", agentFilename, rt, agents, sess, nil)
+	m := tui.New(a)
+
+	progOpts := []tea.ProgramOption{
+		tea.WithAltScreen(),
+		tea.WithContext(ctx),
+		tea.WithFilter(tui.MouseEventFilter),
+		tea.WithMouseCellMotion(),
+		tea.WithMouseAllMotion(),
+	}
+
+	p := tea.NewProgram(m, progOpts...)
+
+	// Start the event subscription in the background
+	go a.Subscribe(ctx, p)
+
+	// Run the workflow executor and forward events to the app's event channel
+	go func() {
+		executor := workflow.New(cfg, agents)
+		events := make(chan runtime.Event, 128)
+
+		// Execute workflow
+		go func() {
+			defer close(events)
+			if err := executor.Execute(ctx, events); err != nil {
+				events <- runtime.Error(err.Error())
+			}
+		}()
+
+		// Forward all workflow events to the app's event channel (which TUI will receive)
+		for event := range events {
+			a.SendEvent(event)
+		}
+	}()
+
+	// Run the TUI
+	_, err = p.Run()
+	return err
+}

examples/README.md

@@ -44,6 +44,24 @@ These are more advanced examples, most of them involve some sort of MCP server t
 | [couchbase_agent.yaml](couchbase_agent.yaml)           | Run Database commands using MCP tools       |            |       |      |       |        | docker,[couchbase](https://hub.docker.com/mcp/server/couchbase/overview)                                          |            |
 | [notion-expert.yaml](notion-expert.yaml)               | Notion documentation expert using OAuth      |            |       |      |       |        | [notion](https://mcp.notion.com) (uses OAuth)                                                                     |            |
 
+## **Workflow Configurations**
+
+These examples demonstrate sequential workflow execution where multiple agents are chained together. Each agent processes the output from the previous agent, creating a pipeline of transformations. Workflows don't require a root agent - they execute agents in the order defined in the workflow section.
+
+See [WORKFLOW_README.md](WORKFLOW_README.md) for detailed documentation.
+
+| Name                                                             | Description/Purpose                       | Steps | Models Used |
+|------------------------------------------------------------------|-------------------------------------------|-------|-------------|
+| [story_workflow.yaml](story_workflow.yaml)                       | Creative writing workflow                 | 3     | OpenAI GPT-4o |
+| [product_description_workflow.yaml](product_description_workflow.yaml) | Marketing content generation        | 3     | OpenAI GPT-4o |
+| [joke_workflow.yaml](joke_workflow.yaml)                         | Joke creation, translation, and formatting | 3     | OpenAI GPT-4o |
+
+**How workflows work:**
+- Agents execute sequentially in the order defined
+- Output from each agent becomes input for the next
+- No root agent required
+- Run with: `./bin/cagent run examples/story_workflow.yaml`
+
 ## **Multi-Agent Configurations**
 
 These examples are groups of agents working together. Each of them is specialized for a given task, and usually has some tools assigned to fulfill these tasks.

examples/WORKFLOW_README.md

@@ -0,0 +1,118 @@
+# Sequential Workflow Execution
+
+This directory contains examples of sequential workflow execution in cagent. Workflows allow you to chain multiple agents together, where each agent processes the output from the previous agent.
+
+## Examples
+
+### Story Generation Workflow
+
+The `story_workflow.yaml` file demonstrates a creative writing workflow with three agents:
+
+1. **story_starter** - Writes the opening paragraph of a story about a robot learning to cook
+2. **add_dialogue** - Continues the story by adding dialogue between the robot and a chef
+3. **add_ending** - Completes the story with a satisfying conclusion
+
+```bash
+./bin/cagent run examples/story_workflow.yaml
+```
+
+### Product Description Workflow
+
+The `product_description_workflow.yaml` file shows a marketing content workflow:
+
+1. **draft_writer** - Creates an initial product description for a smart water bottle
+2. **make_exciting** - Rewrites the description with more engaging language
+3. **add_cta** - Adds a compelling call-to-action
+
+```bash
+./bin/cagent run examples/product_description_workflow.yaml
+```
+
+### Joke Workflow
+
+The `joke_workflow.yaml` demonstrates a simple two-step comedy workflow:
+
+1. **joke_writer** - Creates an original joke
+2. **joke_improver** - Enhances the joke with better timing or punchline
+
+```bash
+./bin/cagent run examples/joke_workflow.yaml
+```
+
+## How It Works
+
+The `run` command automatically detects workflows by checking if the configuration file contains a `workflow` section. No special command is needed!
+
+## Workflow Configuration
+
+### Basic Structure
+
+```yaml
+version: "2"
+
+agents:
+  agent_name:
+    model: openai/gpt-4o
+    instruction: |
+      Your agent instructions here
+
+workflow:
+  - type: agent
+    name: agent_name
+  - type: agent
+    name: next_agent
+```
+
+### Key Features
+
+1. **Sequential Execution**: Agents run in the order defined in the workflow
+2. **Data Piping**: The output of each agent becomes the input for the next agent
+3. **Automatic Context**: The first agent receives instructions to generate initial content, subsequent agents receive the previous output as input
+4. **No Root Agent Required**: Workflows don't need a "root" agent - just define the agents used in your workflow steps
+
+### Example Flow
+
+```
+Step 1: story_starter
+→ Output: "RoboChef-42 had never encountered a kitchen before..."
+
+Step 2: add_dialogue (receives previous output)
+→ Output: "...Chef Lucia approached with curiosity..."
+
+Step 3: add_ending (receives previous output)
+→ Output: "...a bright future in the culinary world."
+```
+
+## Command Options
+
+Workflows support the same runtime configuration flags as regular agent runs:
+
+### Running without TUI (CLI mode)
+
+```bash
+./bin/cagent run examples/story_workflow.yaml --tui=false
+```
+
+### Model Overrides
+
+Override specific agent models:
+
+```bash
+./bin/cagent run examples/story_workflow.yaml \
+  --model story_starter=anthropic/claude-sonnet-4-0 \
+  --model add_dialogue=openai/gpt-4o
+```
+
+### Debug Mode
+
+```bash
+./bin/cagent run examples/story_workflow.yaml --debug
+```
+
+## Notes
+
+- Each agent's output is passed as text to the next agent
+- The workflow stops immediately if any agent fails
+- Model overrides can be specified per agent using `--model agent_name=provider/model`
+- Currently only supports `type: agent` workflow steps (future: conditions, parallel execution)
+- The final output of the workflow is the output from the last agent in the sequence