Orchestrator

The Orchestrator is what a chat message actually reaches first. Its job is not to answer but to decide: does one agent own this, or does it need several? One agent gets the whole message in a single hop; anything else becomes a plan, routed step by step across the agents you can see, and synthesized back into one answer with citations.

At a glance

The routing decision

Before any planning happens, the orchestrator asks one question: does a single agent own this whole request? The rules are tried in order, and the first that matches wins. The first three cost nothing — they run before any model is consulted.

1. An @handle — explicit beats inferred

   @hr-agent how much leave do I have? goes to the HR Agent, whole message, one hop. Naming an agent that is absent, paused or invisible to you is an honest refusal and no other agent runs — you said whom you meant. Two different handles ask which one you wanted.

2. A person's name → their avatar

   "is Alice free Friday?" reaches Alice's avatar. Matched by name, not by embedding similarity: a name is a fact. Several matches ask which person; none falls through.

3. A tagged desk

   An unambiguous support, travel or markets phrasing reaches whichever visible agent carries the support, travel or markets tag — so an organisation that replaces a built-in desk with its own keeps the routing by tagging it the same way. No model is asked, so the decision cannot be talked out of.

4. Otherwise, one lite-tier classifier call

   The classifier sees every visible specialist with the tools each one declares, and the general Assistant's own tools beside them. It answers with one agent's slug, SIMPLE (the Assistant can handle it), or COMPLEX (nobody owns it — plan it).

When it plans: the supervisor graph

A goal nobody owns outright runs the full graph. Every step is a real agent run with its own event stream, so the task tree in chat fills in live.

1. Plan

   The goal becomes an ordered list of steps with dependencies, on the lite tier. The step cap is a ceiling, not a target: a one-agent goal is one step, and research/draft/refine splits are forbidden — each step is a separate run that has to re-read the last one.

2. Route each step

   Candidates are found by vector similarity over agent embeddings, filtered to agents that declare the tool the step needs, then reranked by a lite-tier model. An agent marked routable: false is never a candidate — it is a tool, not a delegate. If the reply names no one, the step goes to the Assistant rather than to an arbitrary nearest match.

3. Execute in waves

   Steps with satisfied dependencies run together as child runs, each carrying the initiating user, so a connector two hops down still acts as that person with their own credential. A dependent step receives the actual output of what it depends on, budgeted so a long plan cannot re-read itself into a context blow-out.

4. Critique, then synthesize

   A critic checks the result against the goal and may trigger a replan, capped at two rounds. An advanced-tier model then composes the answer, and the delegation chips in the thread show which agent contributed what.

What keeps it bounded

• Visibility is enforced at the router. It can only delegate to agents you could have run yourself. Someone else's personal agent is not a candidate, and the candidate set follows the run's workspace.
• Approvals park the whole tree. When a child hits a write, the child parks and the graph parks at its checkpoint. Approving resumes child then parent, and the write executes exactly once.
• State is durable. The graph checkpoints to the database, so a worker restart mid-plan resumes. A resume onto incompatible graph code fails loudly rather than quietly doing something else.
• Budgets degrade gracefully. The step cap, the cost cap over the whole run family, and the wall clock produce a partial synthesis marked budget-limited — never a truncated crash.
• Every decision is traced. The run's execution trace records which rule routed it and to whom, so "why did that agent answer?" has an answer.

Testing the routing

Routing is the one behaviour that is invisible until it is wrong: you get a plausible answer from the wrong agent, and the only symptom is that the right agent's tools were never available. So the Orchestrator ships a routing eval set — three goals per built-in, plus @handle and multi-agent cases — which grades where a goal is sent and runs nobody.

An administrator installs it from Build → Capabilities → Orchestrator routing evals, then runs it from the Playground with the Orchestrator selected. Installing is idempotent and additive: cases you wrote yourself are never touched, and they run beside the pack. Each result records which rule decided — an @handle or a tagged desk is deterministic, so a flip there means the product changed; a classifier decision is a lite-tier model's judgement, so read one flip as evidence rather than proof.