Multi-Agent Orchestration

OrcBot provides production-ready multi-agent orchestration for parallel task execution, specialization, and autonomous coordination. The orchestration system uses real Node.js worker processes with IPC communication.

Architecture

Orchestration Components

AgentOrchestrator: Manages worker pool and task distribution
Worker Processes: Isolated Node.js processes forked from main agent
IPC Channel: Inter-process communication for coordination
Task Queue: Shared priority queue for work distribution
Message Bus: Agent-to-agent messaging system

Worker Lifecycle

Process Isolation

Each worker is a separate Node.js process with:

Isolated memory: No shared state with main agent
Separate config: Can override LLM model, API keys
Independent execution: Runs tasks without blocking main agent
IPC communication: Sends results back via message passing

spawn_agent

Create a sub-agent for parallel work.

Parameters

string

required

Agent name (used in logs and status)

string

required

Agent role: "worker" (general task execution) or "researcher" (specialized research)

array

Optional skill subset this agent can use

Return Value

string

Confirmation with agent ID and PID (process ID)

Roles

Worker Agent:

General-purpose task execution
Full skill access (unless restricted by capabilities)
Suitable for parallel automation
Example: scraping multiple websites simultaneously

Researcher Agent:

Specialized for deep research tasks
Higher isResearch skill budgets
Optimized for multi-step web navigation
Example: comprehensive market research

Example Usage

Spawn general worker:

{
  "skill": "spawn_agent",
  "args": {
    "name": "scraper-1",
    "role": "worker"
  }
}

Spawn researcher:

{
  "skill": "spawn_agent",
  "args": {
    "name": "market-researcher",
    "role": "researcher"
  }
}

Spawn with capability restrictions:

{
  "skill": "spawn_agent",
  "args": {
    "name": "data-processor",
    "role": "worker",
    "capabilities": ["read_file", "write_file", "execute_python_code"]
  }
}

Response Example

Agent spawned successfully:
ID: agent-1736954400000
Name: scraper-1
Role: worker
PID: 12345
Status: idle

Worker Process Details

Workers inherit:

Config from main agent (unless overridden)
LLM credentials
Memory store paths
Skill registry

Workers DO NOT inherit:

Channel connections (no Telegram/WhatsApp/Discord)
Current action state
Short-term memory (starts fresh)

Metadata

isDeep: false
isDangerous: false
isElevated: false

Spawn workers for I/O-bound parallelism. If you need to scrape 10 websites, spawn 10 workers and delegate one URL to each.

delegate_task

Assign a task to an agent or the orchestrator.

Parameters

string

required

Natural language task description

number

default:"5"

Task priority (1-10, higher = more urgent)

string

Specific agent to assign to. If omitted, orchestrator auto-assigns to available worker.

Return Value

string

Confirmation with task ID and assigned agent

Auto-Assignment

If agent_id is omitted, the orchestrator:

Finds idle workers
Assigns to least-loaded worker
If no workers idle, queues for next available

Example Usage

Delegate to specific agent:

{
  "skill": "delegate_task",
  "args": {
    "description": "Scrape product prices from example.com",
    "priority": 8,
    "agent_id": "agent-1736954400000"
  }
}

Auto-assign to available worker:

{
  "skill": "delegate_task",
  "args": {
    "description": "Analyze sentiment of customer reviews",
    "priority": 5
  }
}

Response Example

Task delegated successfully:
Task ID: task-1736954401000
Description: Scrape product prices from example.com
Assigned to: agent-1736954400000 (scraper-1)
Priority: 8
Status: pending

Task Dependencies

Tasks support dependsOn metadata for chaining:

// Task A must complete before Task B
delegate_task("Download dataset", 10) // Returns task-A
delegate_task("Process dataset", 8, { dependsOn: "task-A" })

Metadata

isDeep: false

distribute_tasks

Auto-assign pending tasks to available workers.

Parameters

None. Distributes all pending tasks in the queue.

Return Value

string

Summary of distributed tasks

Example Usage

{
  "skill": "distribute_tasks",
  "args": {}
}

Response Example

Task distribution complete:
- 3 tasks assigned to workers
- 2 tasks still pending (no idle workers)
- 1 task blocked by dependencies

Assignments:
- agent-1: task-A (priority 10)
- agent-2: task-B (priority 8)
- agent-3: task-C (priority 7)

Metadata

isDeep: false

orchestrator_status

Get orchestration summary.

Parameters

None.

Return Value

object

Orchestration state including active workers, pending tasks, and completion stats

Example Usage

{
  "skill": "orchestrator_status",
  "args": {}
}

Response Example

{
  "workers": {
    "total": 3,
    "idle": 1,
    "working": 2,
    "crashed": 0
  },
  "tasks": {
    "pending": 5,
    "in_progress": 2,
    "completed": 12,
    "failed": 1
  },
  "agents": [
    {
      "id": "agent-1",
      "name": "scraper-1",
      "status": "working",
      "current_task": "task-A",
      "uptime": "00:15:32"
    },
    {
      "id": "agent-2",
      "name": "researcher-1",
      "status": "idle"
    }
  ]
}

Metadata

isDeep: false

complete_delegated_task

Mark a delegated task as completed. Typically called by workers.

Parameters

string

required

Task ID to mark complete

string

Optional result summary

Example Usage

{
  "skill": "complete_delegated_task",
  "args": {
    "task_id": "task-1736954401000",
    "result": "Found 42 products with prices ranging from $10 to $500"
  }
}

Metadata

isDeep: false

fail_delegated_task

Mark a delegated task as failed.

Parameters

string

required

Task ID to mark failed

string

required

Error message or reason for failure

Example Usage

{
  "skill": "fail_delegated_task",
  "args": {
    "task_id": "task-1736954401000",
    "error": "Target website returned 403 Forbidden"
  }
}

Metadata

isDeep: false

Inter-Agent Messaging

send_agent_message

Send a message to another agent. Parameters:

string

required

Recipient agent ID

string

required

Message content

string

default:"info"

Message type: info, request, response, alert

Example:

{
  "skill": "send_agent_message",
  "args": {
    "to_agent_id": "agent-2",
    "message": "Scraping complete. Found 100 URLs for you to process.",
    "type": "info"
  }
}

broadcast_to_agents

Broadcast a message to all agents. Parameters:

string

required

Message to broadcast

Example:

{
  "skill": "broadcast_to_agents",
  "args": {
    "message": "Main agent shutting down in 60 seconds. Complete current tasks."
  }
}

get_agent_messages

Retrieve messages for an agent. Parameters:

string

Agent ID. If omitted, returns messages for current agent.

number

default:"10"

Max messages to return

Example:

{
  "skill": "get_agent_messages",
  "args": {
    "agent_id": "agent-1",
    "limit": 5
  }
}

Peer Agents

create_peer_agent

Create an independent peer agent with specialized configuration. Parameters:

string

required

Peer agent name

string

required

Role description

object

Custom WORLD.md governance rules

Example:

{
  "skill": "create_peer_agent",
  "args": {
    "name": "customer-support-bot",
    "role": "Handles customer inquiries on Discord",
    "specialized_governance": {
      "response_time": "<5 minutes",
      "tone": "friendly and helpful"
    }
  }
}

Difference from Workers:

Peer agents are independent long-lived agents with their own identity
Workers are temporary sub-processes for parallel task execution

Peers inherit WORLD.md governance but can have specialized rules.

configure_peer_agent

Update peer agent configuration and restart. Parameters:

string

required

Peer agent ID

object

required

Configuration updates (API keys, channel tokens, etc.)

Example:

{
  "skill": "configure_peer_agent",
  "args": {
    "agent_id": "peer-1736954400000",
    "updates": {
      "discordToken": "new-discord-token",
      "modelName": "gpt-4o-mini"
    }
  }
}

Common Patterns

Parallel Web Scraping

// 1. Define URLs to scrape
const urls = [
  "https://example.com/page1",
  "https://example.com/page2",
  "https://example.com/page3"
];

// 2. Spawn workers (one per URL)
for (let i = 0; i < urls.length; i++) {
  spawn_agent(`scraper-${i}`, "worker")
}

// 3. Delegate tasks
for (let i = 0; i < urls.length; i++) {
  delegate_task(
    `Scrape products from ${urls[i]} and save to scrape-${i}.json`,
    8,
    `agent-${i}`
  )
}

// 4. Monitor progress
orcherator_status()

// 5. Collect results
// Workers write results to files, main agent aggregates

Research Coordination

// 1. Spawn specialized researchers
spawn_agent("tech-researcher", "researcher")
spawn_agent("market-researcher", "researcher")

// 2. Delegate research topics
delegate_task(
  "Research latest AI model architectures and summarize",
  10,
  "tech-researcher"
)
delegate_task(
  "Research competitor pricing strategies",
  9,
  "market-researcher"
)

// 3. Researchers save findings to LEARNING.md
// 4. Main agent synthesizes final report

Task Pipeline

// 1. Create dependency chain
const taskA = delegate_task("Download dataset from API", 10)
const taskB = delegate_task("Clean and validate dataset", 8, { dependsOn: taskA })
const taskC = delegate_task("Train ML model on dataset", 7, { dependsOn: taskB })

// 2. Distribute to workers
distribute_tasks()

// 3. Workers execute in order
// 4. Monitor with orchestrator_status()

Best Practices

When to spawn workers:

I/O-bound parallelism (multiple web scrapes, API calls)
Long-running tasks that shouldn’t block main agent
Specialized work requiring different LLM models
Tasks with natural parallelization boundaries

Resource considerations:

Each worker is a full Node.js process (~50-100MB RAM)
Limit workers to 5-10 on typical servers
Workers don’t share memory, so results must be communicated via IPC or files
Channel connections (Telegram, etc.) are NOT available in workers

Workers vs peer agents:

Use workers for temporary parallel task execution
Use peer agents for long-lived specialized bots
Workers are cheaper (terminate after task completion)
Peers have full autonomy and channel access

Configuration

# Max worker processes
maxWorkers: 10

# Worker idle timeout (milliseconds)
workerIdleTimeout: 600000 # 10 minutes

# Allow workers to connect to channels
allowWorkerChannels: false

# IPC timeout (milliseconds)
ipcTimeout: 30000

Troubleshooting

”Worker crashed”

Cause: Unhandled exception in worker process
Fix: Check daemon logs, add error handling to delegated tasks

”Task stuck in pending”

Cause: No idle workers or dependency not met
Fix: Check orchestrator_status(), spawn more workers or resolve dependencies

”IPC timeout”

Cause: Worker took too long to respond
Fix: Increase ipcTimeout or split task into smaller chunks

”No workers available”

Cause: All workers busy or crashed
Fix: Spawn more workers or terminate/restart hung workers

Scheduling

Schedule autonomous tasks for workers

Memory

Share context between agents

​Multi-Agent Orchestration

​Architecture

​Orchestration Components

​Worker Lifecycle

​Process Isolation

​spawn_agent

​Parameters

​Return Value

​Roles

​Example Usage

​Response Example

​Worker Process Details

​Metadata

​delegate_task

​Parameters

​Return Value

​Auto-Assignment

​Example Usage

​Response Example

​Task Dependencies

​Metadata

​distribute_tasks

​Parameters

​Return Value

​Example Usage

​Response Example

​Metadata

​orchestrator_status

​Parameters

​Return Value

​Example Usage

​Response Example

​Metadata

​complete_delegated_task

​Parameters

​Example Usage

​Metadata

​fail_delegated_task

​Parameters

​Example Usage

​Metadata

​Inter-Agent Messaging

​send_agent_message

​broadcast_to_agents

​get_agent_messages

​Peer Agents

​create_peer_agent

​configure_peer_agent

​Common Patterns

​Parallel Web Scraping

​Research Coordination

​Task Pipeline

​Best Practices

​Configuration

​Troubleshooting

​”Worker crashed”

​”Task stuck in pending”

​”IPC timeout”

​”No workers available”

​Related Skills

Scheduling

Memory

Multi-Agent Orchestration

Architecture

Orchestration Components

Worker Lifecycle

Process Isolation

spawn_agent

Parameters

Return Value

Roles

Example Usage

Response Example

Worker Process Details

Metadata

delegate_task

Parameters

Return Value

Auto-Assignment

Example Usage

Response Example

Task Dependencies

Metadata

distribute_tasks

Parameters

Return Value

Example Usage

Response Example

Metadata

orchestrator_status

Parameters

Return Value

Example Usage

Response Example

Metadata

complete_delegated_task

Parameters

Example Usage

Metadata

fail_delegated_task

Parameters

Example Usage

Metadata

Inter-Agent Messaging

send_agent_message

broadcast_to_agents

get_agent_messages

Peer Agents

create_peer_agent

configure_peer_agent

Common Patterns

Parallel Web Scraping

Research Coordination

Task Pipeline

Best Practices

Configuration

Troubleshooting

”Worker crashed”

”Task stuck in pending”

”IPC timeout”

”No workers available”

Related Skills