Inkdown
Start writing

Merlin Backend

12 files·0 subfolders

Shared Workspace

Merlin Backend
01-Orchestration.md

01-Orchestration

Shared from "Merlin Backend" on Inkdown

Orchestration Architecture

Overview

The orchestration layer is the brain of the Arcane system. It manages multi-agent workflows, handles iterative tool calling, maintains conversation state, and coordinates all AI-driven operations.

Architecture Flow

Plain text
02-DeepResearch.md
03-Search.md
04-Scraping.md
05-Streaming.md
06-MultiProviderLLM.md
07-MemoryAndContext.md
08-ErrorHandling.md
09-RateLimiting.md
10-TaskQueue.md
11-SecurityAndAuth.md
Orchestration-2nd-draft

Core: ToolOrchestrator Class

File: src/server/endpoints/unified/orchestrator/toolOrchestrator.ts:69

TypeScript

Purpose:

  • Maintains state across multiple tool-calling iterations
  • Coordinates between LLM, tools, and streaming
  • Manages token usage and context limits
  • Supports sub-agents (Deep Research spawns ResearcherAgent)

The Main Loop (Heart of the System)

File: src/server/endpoints/unified/orchestrator/toolOrchestrator.ts:237

This is where the magic happens - iterative reasoning with tools:

TypeScript

Why This Loop Matters:

  • Iterative: LLM sees tool results, then decides next action
  • Stateful: Each iteration builds on previous results
  • Streaming: Real-time updates to client
  • Resilient: Tool errors don't crash the system

State Management

File: src/server/endpoints/unified/orchestrator/toolOrchestrator.ts:129

TypeScript

Critical Field: currentContentIndex

This prevents streaming conflicts in multi-agent scenarios. Each chunk sent to client has an index:

  • Main thread uses indices 0, 1, 2, 3...
  • Sub-agent starts where parent left off
  • Prevents race conditions where chunks arrive out of order

Agent Configuration System

Location: src/server/endpoints/unified/orchestrator/configs/

TypeScript

Three Built-in Agents:

  1. MainThreadAgent (mainThread.config.ts)

    • Standard chat
    • 8-15 iterations (plan-based)
    • Parallel tools enabled
    • Full data storage

  2. DeepResearchSupervisor (deepResearch.config.ts)

    • Complex research orchestration
    • Time-limited (e.g., 5 minutes)
    • Sequential execution
    • Custom tool filtering

  3. ResearcherAgent (researcher.config.ts)

    • Individual research tasks
    • Spawned by supervisor
    • Tool-specific focus

Parallel Tool Execution

File: src/server/endpoints/unified/orchestrator/toolOrchestrator.ts:929

TypeScript

Tools run in parallel, results stream as they arrive. No waiting for slow tools.

Individual Tool Lifecycle

File: src/server/endpoints/unified/orchestrator/toolOrchestrator.ts:962

TypeScript

Tool Result Types:

  • tool:start - Execution begins
  • tool:stream - Streaming partial results (sub-agents)
  • tool:done - Success with final result
  • tool:error - Failed (caught gracefully)
  • tool:progress - Overall batch tracking

Multi-Agent Coordination

Plain text

Sub-Agent Spawning Example:

TypeScript

Integration Points

  1. Engine (src/server/repositories/engine/engine.ts)

    • Context trimming after each iteration
    • Layout selection algorithm
    • Token counting

  2. Streamer (src/server/repositories/streamer/streamer.ts)

    • SSE streaming to client
    • EventManager integration
    • Index synchronization

  3. Provider (src/server/repositories/provider/provider.ts)

    • LLM API calls via Rune
    • Token cost calculation
    • Model selection

  4. ToolRegistry (src/server/endpoints/unified/tools/toolRegistry.ts)

    • Tool availability per agent
    • Dynamic tool loading

Summary

The orchestration system:

  • Iterative reasoning: Multi-step tool calling
  • Multi-agent: Different agents for different tasks
  • Parallel execution: Tools run concurrently
  • Streaming-first: Real-time progress
  • Resilient: Errors contained, not catastrophic
  • Token-aware: Context trimming prevents overflow

Key insight: This isn't single-pass Q&A. It's an iterative reasoning engine where the LLM can take multiple actions, see results, and continue thinking - just like a human problem-solving approach.