A supervisor agent dispatches specialised workers, each running its own ReACT loop in parallel. Shared memory, role-based task partitioning, and an aggregator that merges results — all orchestrated on your own hardware.
A supervisor agent receives a high-level goal, decomposes it into sub-tasks, and dispatches each to a worker agent with a specialised role and a scoped tool set. Workers run concurrently as Celery tasks backed by Redis. The supervisor monitors completion and collects results without blocking user interaction.
All agents in a swarm read and write to a shared context store scoped to the swarm session. A researcher worker can deposit findings that a writer worker later reads. A code-analysis worker can flag areas of interest that a refactoring worker then prioritises. Memory is persistent across the swarm's lifetime and searchable via RAG.
Each worker is instantiated with a specific system prompt (Rule) and a restricted tool set. A web-research worker gets browser tools and RAG search. A code worker gets file read/edit/execute tools. A writing worker gets content generation and document tools. Specialisation improves per-task quality by preventing tool confusion and keeping context focused.
After all workers complete, an aggregator step merges partial results into a coherent whole. For research swarms this means a synthesised report with citations. For code swarms it means a unified diff across all modified files. For writing swarms it means a merged draft that reconciles multiple perspectives. The aggregator runs as the final Celery task in the swarm chain.
Specialised 5-agent swarm for end-to-end local video/film: Screenwriter (logline → script + scene breakdown) → Casting (assign LoRAs or stock characters) → Cinematographer (shot list, camera moves, framing) → Storyboard (generate keyframes via image pipeline) → Editor (assemble in the Video Editor timeline). LoRA Trainer plugin for custom characters/environments. Isolated git worktrees keep everything clean.
The Multi-Agent Swarm feature (with Film Crew) uses isolated git worktrees (.swarm-worktrees/<id>/<task>/) so each agent has its own branch and workspace. Successful results cherry-pick cleanly; failures leave no trace. The 5-role Film Crew turns a logline into finished video: Screenwriter → Casting (LoRAs via the dedicated trainer plugin) → Cinematographer → Storyboard (image gen) → Editor (Video Editor timeline). Supervisor + workers run in parallel Celery tasks with shared memory.
The underlying execution model maps directly onto Guaardvark's existing Celery infrastructure. Each worker agent is a Celery task running its own ReACT loop via agent_executor.py. The supervisor is a higher-priority task that spawns the worker group, monitors their job records in the SQLite database, and gates the aggregator task on completion of all workers. Because Celery supports task chaining and grouping natively, the swarm scheduler doesn't require a separate orchestration runtime — it composes primitives the platform already has.
Shared memory between agents is implemented as a swarm-scoped partition of the LlamaIndex vector store. Writes from any worker are immediately queryable by any other worker in the same swarm. After the swarm completes, the shared memory is either promoted to the parent project's permanent index or discarded, depending on the swarm configuration. This means a week of parallel research work can be consolidated into a single well-organised knowledge base with a single click.
Orchestration foundation. backend/services/orchestrator_service.py already handles multi-agent workflow coordination in v2.4. The Swarm feature builds on this by adding a swarm session model (stored in the SQLite database alongside existing Job and Task records), a swarm planner that uses the LLM to decompose a goal into an ordered worker specification, and a result aggregator that runs after all workers complete. The orchestrator_api.py blueprint exposes the swarm endpoints, and the task_scheduler.py service handles scheduling multi-step Celery chains. Worker agents use the same agent_executor.py ReACT loop that powers the single-agent code assistant, with role-specific tool sets defined by the supervisor's decomposition plan.
Resource management. GPU-accelerated workers are coordinated through gpu_resource_coordinator.py, which tracks VRAM allocation and queues workers that require GPU access. CPU-only workers (web research, text processing, code analysis) can run fully concurrently. The swarm planner is GPU-aware: it classifies each subtask as GPU-required or CPU-only and schedules accordingly. Progress for all workers is emitted over Socket.IO so the dashboard shows a live multi-track Gantt-style view of the swarm's execution. When a worker fails, the supervisor can retry it, reassign the subtask, or propagate the failure upward depending on the configured error policy.
# Launch a research swarm via the API
curl -X POST http://localhost:5000/api/orchestrator/swarm -H "Content-Type: application/json" -d '{
"goal": "Research the top 5 open-source vector databases and compare their performance characteristics",
"worker_count": 3,
"roles": ["web-researcher", "data-analyst", "technical-writer"],
"project_id": "proj_abc123"
}'
# Watch swarm progress
llx jobs watch SWARM_JOB_IDAssign five researcher workers to five different source domains simultaneously. Each worker navigates, extracts, and deposits findings into shared memory. When all workers complete, the aggregator synthesises a unified report with citations, conflict resolution, and a confidence score per claim. A task that takes two hours serially finishes in 25 minutes with five parallel workers.
Partition a large codebase into modules and assign each module to a refactoring worker. Workers run concurrently, each executing the same refactoring specification against their assigned files using the code manipulation tools. The aggregator verifies that no cross-module conflicts exist in the resulting diffs and surfaces any that need human review. Refactor a 50-module Python project in the time it takes to refactor 10 serially.
Dispatch three writer workers with different personas — technical, marketing, and beginner-friendly — to draft the same article independently. The aggregator merges the strongest passages from each draft, flagging sections where the perspectives diverge significantly for human adjudication. The result is richer than any single-agent draft and the process takes no longer than a single generation run.
Hosted multi-agent platforms like AutoGen Studio or cloud-based agent orchestrators charge per API call, impose concurrency limits, and route every tool call through their servers. Guaardvark Swarm runs entirely on your hardware: your GPU handles LLM inference, your Redis handles the task queue, your filesystem holds the shared memory. There are no per-agent fees and no practical limit on swarm size beyond your own hardware capacity. Because Swarm builds on Guaardvark's existing Celery infrastructure, it benefits from the same job monitoring, progress tracking, output archiving, and kill-switch controls that govern every other long-running task on the platform.
Yes — Multi-Agent Swarm is available in v2.6, released today. Install Guaardvark to get it, or star the GitHub repo to follow ongoing development.
The practical limit depends on your hardware. CPU-only agents (web research, text processing) can run fully concurrently limited only by CPU threads. GPU agents share VRAM via gpu_resource_coordinator.py, which queues them when memory is full. A typical setup with 16 GB VRAM can run two or three GPU-accelerated agents simultaneously. There is no software cap on swarm size.
Each swarm session gets a scoped partition of the LlamaIndex vector store. Any agent in the swarm can write documents or facts to this store, and any other agent can query it semantically. Writes are indexed immediately and available to other workers without delay. At swarm completion you choose whether to merge the swarm memory into the parent project's permanent index or discard it.
The supervisor monitors each worker's Celery task status. On failure it can retry the worker (configurable retry count), reassign the subtask to a new worker with a fresh context, or propagate the failure and halt the swarm. The failure and reason are logged to the job record and visible in the dashboard. The aggregator does not run until all required workers have succeeded or been explicitly skipped.
Yes. Worker roles are defined by assigning a system prompt (Rule) and a tool set. You can create a custom Rule in the Rules feature that defines any persona or specialisation, then reference it when launching a swarm. Pre-built roles (web-researcher, code-analyst, technical-writer, data-processor) will ship with v2.6 as starting points.