Orchestrator

An orchestrator is an agent that every request goes to. Instead of the interface searching for an agent and running it, the interface always runs the orchestrator, and the orchestrator finds and runs the other agents itself. One agent then stands in front of the whole catalogue, and everything that should happen to every request — a check, a split, a summary — is written once, in that agent.

How it works

An interface built on the REST API — a page of your own, a chat bot, an agent skill — calls execAgent with the orchestrator's name and the user's request. The interface never calls search itself. The bundled GUI searches and runs the match itself, so an orchestrator is used from an interface of your own.

Inside the orchestrator, the search command matches the request to the agents in the catalogue, and the invoke command runs the best match. The invoked agent runs in the same conversation: what the invoked agent writes with output streams to the user as it runs, and what the invoked agent returns comes back to the orchestrator as result. Every agent in the chain sees the conversation's conv variables, so an agent can build on what an earlier one left behind.

"prompt": {
  "system": "Answer yes or no: is this a request about our company's work?",
  "user": "{ sys.query }"
},
"llm": { "profile": "claude_haiku" },
"if": {
  "condition": "{ result.strip().lower().startswith('no') }",
  "then": { "end": "I can help with requests about our company's work." }
},
"search": { "query": "{ sys.query }" },
"if": {
  "condition": "{ not result }",
  "then": { "end": "No agent handles that request yet." }
},
"invoke": {
  "agent": "{ result[0]['agentName'] }",
  "inputs": { "query": "{ sys.query }" }
}

What an orchestrator can do

Everything below is an ordinary agent definition; the orchestrator is powerful because it runs before, between and after the other agents.

Check the request first

An llm call can judge the request before any agent runs: whether the request is on topic, whether it carries data that should not be sent anywhere, whether it looks like an attempt to steer an agent. The orchestrator can then refuse with end, or ask what the user meant with ask. The rule is written once and applies to every agent behind the orchestrator.

Split a request into parts

A request such as "Has order 48812 shipped? If not, open a ticket with the warehouse" is two requests. An LLM can split it into parts, and the orchestrator can take the parts one at a time in a while loop: search, invoke, next part. Each agent sees what the earlier ones left in conv variables, so the warehouse agent can read the order the first agent looked up. invoke cannot sit inside a for loop, because an invoked agent may pause on ask; a while loop can be paused and resumed.

Parts that do not depend on each other can run at the same time: put each invoke in its own function and run the functions with parallel. An agent invoked this way cannot ask the user; an ask there fails the run.

Choose among matches

Search returns one, two or three agents when descriptions overlap or the request is ambiguous; see How matching behaves. The orchestrator can run the first match, ask the user to choose with ask and a chooseOne input, or let an LLM choose from the agents' titles.

Check the answer and speak with one voice

An invoked agent's output streams straight to the user. For an answer that is checked or summarised first, let the specialist agents return their results instead of writing output, and let the orchestrator compose the final answer with an LLM and write it with output. The orchestrator can then check a result against policy before the user sees it, join the results of several agents into one answer, or close with a summary. Every answer comes out in one voice, whichever agents produced it.

Handle the request nobody covers

When search returns nothing, the orchestrator decides what happens: answer from an LLM directly, ask a clarifying question, or say what the catalogue covers. Without an orchestrator, that decision is left to the interface.

Confirm before acting

Before invoking an agent that sends, books or pays, the orchestrator can ask for confirmation. An invoked agent may ask too; the whole chain pauses on the question and continues with the answer.

Route by catalogue

The search command takes a tag, so the orchestrator can search one catalogue for one kind of request and another for the next, or choose the catalogue by who is asking when sys.userEmail is enabled.

Remember

With the memory command the orchestrator can keep what it learns about a user — a preferred office, a usual project — and pass it to the agents it invokes, across conversations.

What to keep in mind

• Each search is a round trip to Search2o Cloud, and each LLM call takes the model's time. A request that is checked, split, answered and summarised costs the sum of those steps.
• The reports record the orchestrator's run and every invoked agent's run, so what each agent did and cost stays visible.
• An agent cannot invoke itself or any agent already running in the chain, and invoke is not allowed inside a for loop or an onError block. See invoke.