Eldric Swarm - Multi-Agent AI Orchestration

What is Eldric Swarm?

Eldric Swarm is an AI multi-agent orchestration system that enables complex task decomposition and autonomous collaboration between specialized AI agents. Unlike single-agent systems, Swarm breaks down complex goals into discrete tasks and assigns them to specialized agents that work together, share discoveries, and adapt their approach based on emergent patterns.

The system uses a tiered architecture that scales from local development to global enterprise deployments, with intelligent routing, shared memory, and collective decision-making capabilities.

Tiered Swarm Architecture

Eldric Swarm Hierarchy

Global Tier

🌐

Global Controller

Cross-region coordination

Regional Tier

🏢

US-East Controller

Region orchestration

🏢

EU-West Controller

Region orchestration

🏢

APAC Controller

Region orchestration

Local Tier

🎯

Swarm Orchestrator

Task decomposition & planning

🧠

Collective Decision

Voting & consensus

📊

Emergent Monitor

Pattern detection

Worker Tier

🔍

Explorer Agent

📝

Planner Agent

💻

Coder Agent

🧪

Runner Agent

🔎

Searcher Agent

🗄️

Database Agent

Swarm Workflow

🎯

Goal Submission

User defines objective

🧩

Decomposition

AI breaks into tasks

📋

Plan Review

Human approval

⚡

Parallel Execution

Agents collaborate

✅

Synthesis

Results combined

Specialized Agents

Each agent is specialized for specific task types with constrained tool access for safety and efficiency.

🔍

Explorer

Analyzes codebases, finds patterns, maps dependencies and architecture. Read-only operations for safe exploration.

glob grep read

📝

Planner

Designs architecture, creates implementation plans, reviews approaches. Strategic thinking without execution.

glob grep read

💻

Coder

Writes, modifies, and refactors code. Full file manipulation capabilities for implementation tasks.

read write edit glob

🧪

Runner

Executes tests, builds projects, validates implementations. Command-line execution specialist.

bash read

🔎

Searcher

Researches documentation, finds examples, discovers best practices from the web.

web_search web_fetch read

🗄️

Database

Queries databases, analyzes schemas, optimizes queries. Data layer specialist.

db_connect db_query db_schema

Use Cases

🏗️ Feature Implementation

Build complex features requiring analysis, planning, implementation, and testing across multiple files and systems.

1 Explorer Analyze existing codebase structure

2 Planner Design implementation approach

3 Coder Write code across files

4 Runner Execute tests and validate

🐛 Bug Investigation

Track down elusive bugs by combining exploration, research, and targeted fixes with validation.

1 Explorer Search for error patterns

2 Searcher Research similar issues

3 Coder Apply targeted fix

4 Runner Verify bug is resolved

📊 Data Pipeline Development

Create data processing pipelines with database schema analysis, code generation, and integration testing.

1 Database Analyze schema & relationships

2 Planner Design pipeline architecture

3 Coder Implement ETL logic

4 Runner Test with sample data

🔄 Codebase Refactoring

Large-scale refactoring with dependency analysis, safe transformations, and comprehensive testing.

1 Explorer Map dependencies & usages

2 Planner Plan safe refactor sequence

3 Coder Apply transformations

4 Runner Run full test suite

Emergent Behaviors & Pattern Detection

The Swarm system monitors agent interactions and detects emergent patterns to optimize performance and prevent issues.

👑

Leader Emergence

Detects when one agent naturally becomes a coordinator, sending more messages and guiding other agents.

⚠️

Bottleneck Detection

Identifies blocked tasks or overloaded agents that slow down the entire swarm.

🔒

Deadlock Prevention

Detects stalled swarms where no progress is being made across multiple check intervals.

🔄

Thrashing Detection

Identifies high failure rates indicating agents are repeatedly failing on similar tasks.

↔️

Divergence Alert

Detects when agents are working at cross purposes, producing conflicting results.

⭐

Specialization Recognition

Identifies effective agent specialization patterns for optimized task routing.

API Reference

The Swarm Controller exposes three API servers for different purposes.

Port 8885

Swarm API

Goal submission, plan approval, swarm management

POST /api/v1/goals

GET /api/v1/goals/{id}

POST /api/v1/goals/{id}/approve

DEL /api/v1/goals/{id}

GET /api/v1/swarms

GET /api/v1/metrics

Port 8886

Agent API

Agent invocation (UAP), management, tools listing

POST /api/v1/agents/invoke

GET /api/v1/agents

POST /api/v1/agents/install

POST /api/v1/agents/{id}/start

GET /api/v1/tools

Port 8887

Web API

Dashboard, client registration, simplified endpoints

GET /api/v1/health

GET /api/v1/status

POST /api/v1/clients/register

GET /api/v1/cluster

GET /dashboard

Quick Start

Starting the Swarm Controller

                # Start the swarm daemon
./eldric-swarmd --bind 0.0.0.0 --swarm-port 8885 --agent-port 8886 --web-port 8887

# With parent controller (tiered deployment)
./eldric-swarmd --parent http://regional-controller:8885 --tier local
            

Submitting a Goal

                curl -X POST http://localhost:8885/api/v1/goals \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Implement user authentication with JWT tokens",
    "context": "Express.js backend, PostgreSQL database",
    "constraints": ["Use bcrypt for password hashing", "Token expiry: 24 hours"],
    "mode": "supervised",
    "max_agents": 5
  }'
            

Approving a Plan

                # Get the generated plan
curl http://localhost:8885/api/v1/goals/goal-abc123

# Approve and start execution
curl -X POST http://localhost:8885/api/v1/goals/goal-abc123/approve
            

Execution Modes

👁️

Advisory

Swarm creates plans but requires human approval before any execution. Maximum control.

👤

Supervised

Swarm executes with real-time monitoring. Human can intervene at any point. Recommended default.

🤖

Autonomous

Full autonomous operation. Swarm handles all decisions including replanning on failures.