Mithril — Flow — The Orchestration Council

Purpose

🧝

Multi-agent orchestration: classify requests, route to agents, manage tool execu

Files

LOC

2,316

Key Concept

A local GGUF model classifies every request (free), then routes to the right cloud agent. Agents can delegate to each other via NEXT/TASK protocol.

Orchestration Flow

flowchart TD
    REQ(User Request) --> CLASS(GGUF Classifier)
    CLASS -->|agent name| LOOP(Agent Loop)
    LOOP -->|call provider| PROV(Provider API)
    PROV -->|tool calls?| EXEC(Tool Execution)
    EXEC -->|results| LOOP
    LOOP -->|NEXT DONE| RESP(Response to User)
    LOOP -->|NEXT agent| DELEG(Delegate to Agent)
    DELEG --> LOOP

Step 1: Classification (Free)

A tiny local GGUF model (1.5B params, runs on CPU in ~100ms) reads the user's message and outputs the NAME of the best agent to handle it. No cloud API call needed.

Step 2: Agent Execution Loop

The selected agent runs with its configured provider (e.g., Gemini Flash). It can:

Call tools (file read, git status, web search) → results fed back
Respond directly → NEXT: DONE
Delegate to another agent → NEXT: reviewer + TASK: check auth.rs

Step 3: Multi-Agent Protocol

Agents communicate via text directives at the end of their responses:

NEXT: DONE — task complete, return response to user
NEXT: agent_name + TASK: instructions — hand off to another agent

#agent Direct Routing

If the user starts their message with #reviewer, the GGUF classification is skipped and the named agent is called directly. Faster and cheaper.

The fellowship YAML defines the team:

fellowship.yaml example

name: "my-team"
controller:
  provider: local       # Free GGUF router
  model: qwen-1.5b

agents:
  - name: coder
    provider: gemini
    model: gemini-2.5-flash
    when: "coding tasks"
    can_call: [reviewer]
    tools: ["*"]

  - name: reviewer
    provider: openai
    model: gpt-4o
    when: "code review"
    can_call: []
    tools: [read_psi, grep_files]

File	Purpose
`agent_loop.rs`	Shared agentic loop — used by both interactive chat and headless exec.
`config.rs`	Flow configuration — parsed from `.mithril-flow.yaml`.
`fellowship.rs`	Fellowship — multi-agent orchestration config with GGUF entry classifier.
`mod.rs`	Multi-agent flow system.
`orchestrator.rs`	Orchestrator — GGUF entry classifier + agent free-flow + GGUF worker.
`runner.rs`	FlowRunner — executes the Planner→Tools loop.
`tokens.rs`	Token tracking — count tokens per provider call, accumulate per-agent.