FusionAGI/docs/multi_agent_acceleration.md

Multi-Agent Acceleration

FusionAGI includes multi-agent accelerations, enhancements, optimizations, and scaling capabilities.

Architecture Overview

flowchart TB
    subgraph supervisor [Supervisor Agent]
        S[Supervisor]
    end

    subgraph agents [Agents]
        P[Planner]
        R[Reasoner]
        EP[Executor Pool]
    end

    subgraph pool [Executor Pool]
        E1[Executor 1]
        E2[Executor 2]
        E3[Executor 3]
    end

    S --> P
    S --> EP
    S --> R
    EP --> E1
    EP --> E2
    EP --> E3

Parallel step execution: Independent plan steps run concurrently. Agent pool: Multiple executors behind one logical endpoint (round_robin, least_busy, random). Supervisor: Drives plan–execute loop with parallel dispatch.

Features

1. Parallel Step Execution

Independent plan steps (those with satisfied dependencies and no mutual dependencies) run concurrently.

from fusionagi.planning import ready_steps
from fusionagi.multi_agent import execute_steps_parallel, execute_steps_parallel_wave

# Get all steps ready to run in parallel
ready = ready_steps(plan, completed_step_ids={"s1", "s2"})

# Execute them concurrently
results = execute_steps_parallel(execute_fn, task_id, plan, completed_step_ids, max_workers=4)

# Or run full plan in waves (each wave = parallel batch)
results = execute_steps_parallel_wave(execute_fn, task_id, plan, max_workers=4)

2. Agent Pool & Load Balancing

Scale horizontally with multiple executors behind a single logical endpoint.

from fusionagi.agents import ExecutorAgent
from fusionagi.multi_agent import PooledExecutorRouter, AgentPool
from fusionagi.core import StateManager
from fusionagi.tools import ToolRegistry

# Create pool router (register as "executor")
registry = ToolRegistry()
state = StateManager()
pool = PooledExecutorRouter(identity="executor", pool=AgentPool(strategy="least_busy"))

# Add multiple executors
for i in range(4):
    ex = ExecutorAgent(identity=f"executor_{i}", registry=registry, state_manager=state)
    pool.add_executor(f"executor_{i}", ex)

orch.register_agent("executor", pool)
# All execute_step messages now load-balance across 4 executors

Strategies: round_robin, least_busy, random

3. Sub-Task Delegation (Fan-Out / Fan-In)

Decompose tasks and delegate to specialized sub-agents in parallel.

from fusionagi.multi_agent import delegate_sub_tasks, SubTask, DelegationConfig

sub_tasks = [
    SubTask("st1", "Analyze requirements"),
    SubTask("st2", "Design solution"),
    SubTask("st3", "Validate constraints"),
]

results = delegate_sub_tasks(
    sub_tasks,
    delegate_fn=lambda st: run_sub_agent(st),
    config=DelegationConfig(max_parallel=3, fail_fast=False),
)

4. Supervisor Agent

Single agent that drives the full plan-execute loop with parallel dispatch.

from fusionagi.multi_agent import SupervisorAgent
from fusionagi.core import Orchestrator, EventBus, StateManager

orch = Orchestrator(EventBus(), StateManager())
supervisor = SupervisorAgent(
    identity="supervisor",
    orchestrator=orch,
    planner_id="planner",
    executor_id="executor",
    parallel_mode=True,       # Enable parallel step execution
    max_parallel_workers=4,
)

orch.register_agent("supervisor", supervisor)
# Send run_task → supervisor gets plan → executes steps in parallel waves

5. Batch Message Routing

Route multiple messages in parallel.

responses = orch.route_messages_batch([env1, env2, env3, ...])

6. Async Message Routing

Non-blocking dispatch with optional callback.

future = orch.route_message_async(envelope, callback=lambda resp: handle(resp))
# Or await: result = future.result()

Scaling Checklist

Capability	Module	Use Case
Parallel step execution	multi_agent.parallel	Plans with independent steps
Agent pool	multi_agent.pool	Horizontal executor scaling
Sub-task delegation	multi_agent.delegation	Hierarchical task decomposition
Supervisor	multi_agent.supervisor	Automated parallel orchestration
Batch routing	Orchestrator.route_messages_batch	Multi-task throughput
Async routing	Orchestrator.route_message_async	Non-blocking pipelines

Architecture

                    ┌─────────────────┐
                    │   Supervisor    │
                    │ (parallel_mode) │
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
   ┌──────────┐       ┌─────────────┐     ┌──────────┐
   │ Planner  │       │  Executor   │     │ Reasoner │
   │          │       │    Pool     │     │          │
   └──────────┘       └──────┬──────┘     └──────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
              ▼              ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │Exec 1    │  │Exec 2    │  │Exec 3    │  (parallel steps)
        └──────────┘  └──────────┘  └──────────┘