Skip to content

Add multi-agent orchestration workflow system#15

Open
adham90 wants to merge 9 commits intomainfrom
feature/multi-agent-orchestration
Open

Add multi-agent orchestration workflow system#15
adham90 wants to merge 9 commits intomainfrom
feature/multi-agent-orchestration

Conversation

@adham90
Copy link
Owner

@adham90 adham90 commented Feb 24, 2026

Summary

  • Workflow Engine: Declarative DSL for composing agents into multi-step pipelines with step, flow, pass, context, description, on_failure, and budget directives
  • Parallel Execution: Steps marked parallel run concurrently via Thread.new with thread-safe WorkflowContext (Mutex-protected), fan-in via after: dependencies
  • Router Dispatch: dispatch DSL integrates with existing Routing concern — routes to different agents based on classification result
  • Supervisor Loop: Orchestrator agent with DelegateTool/CompleteTool loops up to max_turns, delegating to sub-agents until completion
  • Dashboard Integration: Workflow tab in agents index, step breakdown in execution detail view
  • Generator: rails generate ruby_llm_agents:workflow Content --steps=research,draft,edit scaffolds workflow classes

Architecture

  • Workflow is a standalone class (not a BaseAgent subclass), following the ImagePipeline precedent
  • No new database columns — workflow metadata stored in existing metadata JSON column
  • Each step calls agents through the full middleware pipeline (budget, cache, instrumentation, reliability)
  • FlowGraph builds a DAG with Kahn's topological sort for execution ordering

Stats

  • 34 files changed, ~3900 lines added
  • 115 new specs across 14 spec files
  • All 4292 specs pass, StandardRB clean

Test plan

  • bundle exec rspec spec/agents/workflow/ — all workflow specs pass
  • bundle exec rspec — full suite (4292 examples, 0 failures)
  • bundle exec standardrb — lint clean
  • bundle exec rake — full suite + lint passes
  • Generator specs verify template output for all options

🤖 Generated with Claude Code

adham90 and others added 9 commits February 24, 2026 05:09
@adham90 @claude
Add workflow orchestration engine (Phase 1: Sequential)
c71607d 
Introduces the core Workflow system for composing agents into multi-step
pipelines. Follows the ImagePipeline architectural pattern as a standalone
class with its own DSL, execution tracking, and result aggregation.

Core components:
- Step: value object wrapping agent class with params and dependencies
- WorkflowContext: thread-safe shared context with Mutex for step data
- FlowGraph: DAG with Kahn's topological sort for execution layers
- DSL: step, flow (Symbol#>>), pass, description, on_failure, budget
- Runner: layer-by-layer execution with pass mappings and error handling
- WorkflowResult: aggregated cost/token/timing across all steps

Features: sequential execution, pass mappings between steps, conditional
steps (if:/unless:), on_failure :stop/:continue, execution tracking with
execution_type "workflow", AgentRegistry integration.

87 new specs, all 4250 specs pass.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@adham90 @claude
Add parallel execution for workflow steps (Phase 2)
2cb0aed 
Introduces ParallelRunner that extends Runner to execute independent
steps concurrently using Thread.new. No new gem dependency — Ruby
threads are sufficient for I/O-bound LLM API calls.

- Steps in the same execution layer run in parallel threads
- Single-step layers still execute sequentially (no thread overhead)
- WorkflowContext's Mutex ensures thread-safe result storage
- Errors in one parallel step are collected without killing siblings
- Wall-clock timing reflects actual parallel execution time

5 new specs covering concurrent execution, fan-in, error collection,
wall-clock timing, and thread-safe context writes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@adham90 @claude
Add dispatch for routing-based agent selection (Phase 3)
296f681 
Introduces DispatchBuilder and dispatch DSL that integrates with the
existing Routing concern. After a routing step executes, the dispatch
system reads the route from the RoutingResult and calls the matched
handler agent.

- dispatch DSL: `dispatch :classify do |d| d.on :billing, agent: BillingAgent end`
- DispatchBuilder: collects route-to-agent mappings with on/on_default
- Runner: executes dispatched handler after routing step completes
- Supports custom handler step name via `as:` option
- Graceful handling when no route matches and no default set
- Cost/token aggregation includes both router and handler steps

9 new specs, all 4264 specs pass.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@adham90 @claude
Add supervisor loop for orchestrator-driven workflows (Phase 4)
21ec773 
Introduces supervisor mode where an orchestrator agent loops, delegating
to sub-agents via DelegateTool and CompleteTool until done or max_turns
reached.

Components:
- DelegateTool: RubyLLM::Tool letting supervisor delegate to named agents
- CompleteTool: RubyLLM::Tool signaling loop completion via thread-local
- Supervisor: loop execution logic, builds initial prompt, tracks turns
- DSL: `supervisor AgentClass, max_turns: N` and `delegate :name, AgentClass`

Features: configurable max_turns, thread-local completion signaling,
cost aggregation across supervisor turns and delegated calls, context
storage of delegation results, mutually exclusive with step mode.

13 new specs, all 4277 specs pass.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@adham90 @claude
Add workflow support to dashboard (Phase 5)
91e9cc5 
Integrates workflow executions into the existing dashboard UI:

- AgentRegistry: adds is_workflow flag, workflow type detection
- AgentsController: separates workflows into dedicated tab, adds
  workflow grouping to agents_by_type
- Agents index: workflow tab button and workflow agent rows
- Executions show: workflow step breakdown section showing step names
  with success/failure indicators when execution_type is "workflow"
- Execution filtering: workflow executions filterable via execution_type

4 new specs, all 4281 specs pass.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@adham90 @claude
Add workflow generator and templates (Phase 6)
918c5a6 
Adds rails generate ruby_llm_agents:workflow generator with --steps
option, application_workflow base class template, and install generator
integration. Includes 11 generator specs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@adham90 @claude
Add multi-agent orchestration documentation and examples
c23d60a 
- Create wiki/Multi-Agent-Orchestration.md with full DSL reference
- Add workflow feature and code example to README.md
- Add workflow section to LLMS.txt
- Update wiki: Home, Generators, Examples, API Reference, Best Practices
- Add example app workflows: sequential pipeline, parallel analyzer,
  dispatch routing with step agents and ApplicationWorkflow base class

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@adham90 @claude
Add workflow config partial for dashboard agent show page
88bcc63 
Creates _config_workflow.html.erb partial showing steps, on_failure
strategy, budget limit, and workflow mode (pipeline/dispatch/supervisor).
Adds load_workflow_config to AgentsController for workflow-specific
config loading.

Fixes: Missing partial error when viewing workflow agents in dashboard.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@adham90 @claude
Add supervisor workflow example and workflow seed data
b606e00 
Add the missing supervisor workflow pattern to the example app
(orchestrator + researcher + writer agents) and seed data for
all 4 workflow types (pipeline, parallel, dispatch, supervisor)
so they appear on the dashboard.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@adham90