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

name

string

required

Agent name (used in logs and status)

role

string

required

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

capabilities

array

Optional skill subset this agent can use

Return Value

result

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

description

string

required

Natural language task description

priority

number

default:"5"

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

agent_id

string

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

Return Value

result

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

result

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

status

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

task_id

string

required

Task ID to mark complete

result

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

task_id

string

required

Task ID to mark failed

error

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:

to_agent_id

string

required

Recipient agent ID

message

string

required

Message content

type

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:

message

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:

agent_id

string

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

limit

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:

name

string

required

Peer agent name

role

string

required

Role description

specialized_governance

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:

agent_id

string

required

Peer agent ID

updates

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

CLI Commands

Core Skills

Configuration

​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