Multi-Agent Orchestration

Overview

Multi-agent orchestration is an optional build (--features orchestration). It is a workflow runtime inspired by Pi, Orloj, and Temporal: several workers share memory and run tasks in parallel, coordinated by an event-sourced engine. The default loop binary does not include it. Key design principle: The workflow runtime is AI-agnostic. Agents, shell commands, and sub-workflows are all just worker types on a shared durable orchestration layer. Interactive surfaces — the CLI TUI (loop-cli) and GPUI desktop (loop-desktop) — sit on top of the same harness. Live multi-agent task cards are available in the CLI today; desktop follows single-agent events for now.

CLI Usage

Build with the orchestration feature, then use /workflow:

cargo run -p loop-cli --features orchestration

/workflow <goal>
/workflow --concurrency 4 <goal>

Plans a multi-agent task graph from the goal, runs the scheduler, and streams live WorkflowTask cards into the chat until a completed / failed / total summary line. Each task card shows description, status (pending → success/error), and collapsible output (Ctrl+O, same affordance as tool cards). Errors preview a few lines by default.

Architecture

AgentHarness
    ├── Planner — Goal → TaskGraph (DAG)
    ├── Workflow Engine — Event sourcing, replay, signals, subscribe()
    ├── Scheduler — Worker dispatch, concurrency pool
    ├── Progress channel — WorkflowProgressEvent → UI
    └── Memory Layer — SharedMemory, TaskMemory, MemoryBus

Components

Component	Role
Planner	Decomposes a high-level goal into a directed acyclic graph (DAG) of tasks
TaskGraph	DAG with cycle detection and dependency tracking
Workflow Engine	Event-sourced state machine with full replay support
EventLog	In-memory or SQLite-backed durable event storage
Scheduler	Dispatch loop with configurable concurrency limits
Workers	Pluggable execution units that process tasks
Memory	Shared and per-task memory with pub/sub messaging
Progress	Live `WorkflowProgressEvent` stream for UI updates

Phases Built

Phase	Component	What It Does
1	Workflow Foundation	`WorkflowEvent` enum, `TaskGraph` DAG, `Worker` trait, `WorkerPool`, `Scheduler`
2	Agent Worker + Memory	`AgentWorker`/`ShellWorker`, `SharedMemory`, `TaskMemory`, `MemoryBus`
3	Harness Integration	`start_workflow()` / `run_workflow_inner()`, hook wiring, spawn-task tool
4	LLM Planner + Persistence	`LlmPlanner`, `SqliteEventLog`, `Checkpoint` snapshots
5	Signals + Sub-Workflows	`SignalRouter`, `SubWorkflowWorker`, `start_workflow_from_goal()`

Planners

LLM Planner

The AI-powered planner takes a natural language goal and produces a TaskGraph:

Goal: "Add user authentication to the API"
  ↓
TaskGraph:
  ├── Task 1: Design auth schema
  ├── Task 2: Implement JWT middleware (depends on 1)
  ├── Task 3: Create login endpoint (depends on 2)
  ├── Task 4: Create registration endpoint (depends on 2)
  └── Task 5: Write tests (depends on 3, 4)

When PlannerContext is omitted, the harness auto-fills cwd and available tool names so the LLM plans against the real environment.

Manual Planner

For predefined workflows, use the manual planner to construct task graphs programmatically.

Worker Types

Worker	Description
`AgentTurn`	Runs an AI agent turn with specific instructions
`ShellCommand`	Executes a shell command
`SubWorkflow`	Spawns a nested workflow
`Barrier`	Synchronization point — waits for dependencies
`Custom`	Implement the worker trait for custom logic

Agent Worker Hardening

Empty tool-filter fallback — If a planner filter matches no base tools, keep the full toolset so filesystem access is not accidentally stripped
Soft failure detection — Scans agent output for blocked/unavailable-tool phrasing and fails the task even if the agent loop returned Ok
File artifact collection — Successful write tool results verified on disk become workflow Artifacts

Memory System

The memory layer provides coordination between tasks:

SharedMemory

Global key-value store accessible by all tasks in a workflow.

TaskMemory

Per-task isolated memory that persists across retries.

MemoryBus

Pub/sub messaging system for inter-task communication:

Tasks can publish messages to named channels
Other tasks subscribe and react to messages
Supports signals and timers for coordination

Event Sourcing & Progress

Every state transition in a workflow is recorded as an event:

Full replay capability for debugging and recovery
Fork workflows from any point in history
Durable storage with SQLite backend (feature-gated; live resume wiring is Phase 2)
Complete audit trail of all agent actions

UIs can track progress without polling:

WorkflowEngine::subscribe() broadcasts live WorkflowEvents
Harness progress_tx forwards WorkflowProgressEvent (task started / completed / failed) from start_workflow / start_workflow_from_goal
WorkflowResult reports completed task_results, failed_tasks (id + error), and total_task_count

Design Principles

AI-agnostic runtime — Agents are just one type of worker. The orchestration engine handles any kind of task.
Event sourcing — Every state change is recorded. Replay, debug, and fork from any point.
Broadcast + progress channel — Decouples engine events from chat cards without polling.
Pluggable workers — Implement one trait to add custom worker types.
Shared memory with isolation — Global coordination with per-task boundaries.
Graceful degradation — Single-agent prompt() works unchanged without orchestration enabled.

Feature Flag

# loop-agent
[features]
orchestration = ["dep:loop-orchestration"]

# loop-cli
orchestration = ["loop-agent/orchestration", "dep:loop-orchestration"]

cargo run -p loop-cli --features orchestration

API

Start from Goal

use loop_agent::AgentHarness;

let harness = AgentHarness::new(config);
let result = harness.start_workflow_from_goal("Add caching to the API").await?;

Start from TaskGraph

use loop_agent::AgentHarness;
use loop_orchestration::TaskGraph;

let graph = TaskGraph::new();
// ... build graph ...
let result = harness.start_workflow(graph).await?;

Both entry points accept an optional progress channel that forwards live WorkflowProgressEvents for UI updates.

Roadmap

Phase	Status	Description
Core engine	Done	Workflow engine, scheduler, event log
Worker types	Done	Agent, shell, sub-workflow, barrier, custom
Memory system	Done	SharedMemory, TaskMemory, MemoryBus
Planner	Done	LLM and manual planners
CLI integration	Done	`/workflow` with live progress cards, soft failure, artifacts
Durable resume	Planned	Wire SQLite event log into live workflows
Desktop workflow UI	Planned	Live multi-agent task cards in `loop-desktop`
Planner validation	Planned	Guardrails for invalid LLM task graphs

Getting Started

Guides

Features

Multi-Agent Orchestration

Overview

CLI Usage

Architecture

Components

Phases Built

Planners

LLM Planner

Manual Planner

Worker Types

Agent Worker Hardening

Memory System

SharedMemory

TaskMemory

MemoryBus

Event Sourcing & Progress

Design Principles

Feature Flag

API

Start from Goal

Start from TaskGraph

Roadmap

​Overview

​CLI Usage

​Architecture

​Components

​Phases Built

​Planners

​LLM Planner

​Manual Planner

​Worker Types

​Agent Worker Hardening

​Memory System

​SharedMemory

​TaskMemory

​MemoryBus

​Event Sourcing & Progress

​Design Principles

​Feature Flag

​API

​Start from Goal

​Start from TaskGraph

​Roadmap

Overview

CLI Usage

Architecture

Components

Phases Built

Planners

LLM Planner

Manual Planner

Worker Types

Agent Worker Hardening

Memory System

SharedMemory

TaskMemory

MemoryBus

Event Sourcing & Progress

Design Principles

Feature Flag

API

Start from Goal

Start from TaskGraph

Roadmap