The trace I stared at longest this week contained nothing at all.
I had a router agent above three specialists — a hospital scenario in a real Developer Edition org, the clinic entirely fictional — and asked it something the first specialist could easily answer. The router did the right thing: it identified the correct specialist and handed the conversation over.
Then the specialist produced no content. And the session returned an error to the user.
No exception in my code, because there is barely any code. No misbehaving model. The router’s reasoning was exactly what I had asked for. It had simply used the wrong verb — and the wrong verb turns out to end the conversation.
Two ways to involve another agent
There are two shapes available when one agent needs another, and their names make them sound like the same thing at different volumes. They are not.
Transition hands control away. The built-in transition utility — @utils.transition in Agent Script — moves the conversation to the target agent. The point of a transition is that the first agent is finished: the second takes the wheel and carries on with the user from there.
Call treats the other agent as an action. The router invokes it, the target does its work, and the response comes back to the router, which is still holding the conversation — now with one more fact in hand.
Read those two again and the failure is already visible. I wanted a router that consults three specialists and merges their answers into one reply. Every part of that sentence requires the answers to come back. A transition is the one operation that guarantees they cannot.
What the failing trace actually showed
I want to walk through the trace rather than just state the rule, because the symptom pointed away from the cause.
The trace showed the specialist producing no content, and the session returning an error. Read only that, and the natural conclusion is that something is wrong with the specialist. That is where I looked first: its instructions, its action, its published version. All fine.
What had actually happened is that control left the router and did not return. There was nowhere for a reply to go. The router ended its turn by handing over, the handover produced no answer the session could deliver, and the user got an error instead of a sentence.
When an agent produces nothing at all, suspect the plumbing before the prompt. An empty response is rarely a model being unhelpful; it is usually a message with no route home.
That is a habit worth keeping. A bad answer is a content problem; no answer is almost always structural.
Why only “call” composes
Once the fix is in front of you, the deeper point is easy to see, and it generalises past this platform.
A transition is terminal for the caller. Whatever the target does afterwards, the caller never learns it, because the caller is no longer in the conversation. You can transition once. You cannot transition three times and combine the results, for the same reason you cannot forward one letter to three people and expect three replies in your own hand.
A call returns. Because the answer comes back, the router can do what a router exists to do: ask, receive, decide, ask the next one. Merging three specialist answers into a single reply is only possible where each answer lands back in the same place.
So the rule is short: a connected subagent must be called, not transitioned to. If you want an orchestrator, every downward step is an action. Transition is the right tool for a genuine handover — when you truly mean “this agent takes it from here and I am done” — and the wrong tool for everything an orchestrator does.
The working trace
The corrected version reads the way I wanted it to all along. In a single turn:
- The router calls Records and gets patient history back.
- Reasoning returns to the router.
- The router calls Triage and gets an urgency assessment back.
- Reasoning returns to the router.
- The router calls Scheduling and gets its response back.
Three specialists, one turn, the router in charge between each step. Those middle lines — reasoning returning to the router between each call — are what make it an orchestration rather than a queue. The router is not blindly firing three calls; it decides each time, holding what it has learned.
The order is fixed by dependency: triage needs the history, scheduling needs the urgency. I wrote about why ownership and order are arranged that way in Multi-Agent Orchestration: Who Owns What, and Who Answers.
GROUNDED is a check, not a compliment
On the working run, the platform’s own output evaluation reported GROUNDED.
I want to be careful with that word, because it is easy to read as praise. It is not. It is a check the platform performs on the response — whether what the agent said is supported by what it actually retrieved, rather than composed on the way past.
It does not mean the answer is clinically sensible, that my routing logic is well designed, or that the system is finished. It is one signal, from outside the model, saying this particular reply was not invented — worth something precisely because it is narrow.
An evaluation that always says something nice is decoration. One that can disagree with you is a check.
The instruction the shape makes possible
There is one more thing the call-based shape enables, and it is easy to miss.
Because responses return to the router, the router can be held to a standard: report results, never narrate steps. “I have retrieved the history” and “an appointment is being booked” are failures, not progress updates — from where the user sits, they are indistinguishable from nothing having happened. Earlier versions of mine did exactly this, in a reassuring tone.
That instruction is only enforceable where the router actually has results to report. In a transition-based flow it does not know what happened downstream, so narration is the most honest thing it could say. Fixing the plumbing made the honest instruction possible.
What I have not proven
The orchestration runs and the specialists answer. I have not yet proven that the booking writes a record in the org. That is the next thing to demonstrate.
I am stating it that plainly on purpose. The section above calls “an appointment is being booked” a failure mode, and it would be a poor sort of principle if it applied to my agents but not to me writing about them. Until there is a record I can open and point at, the correct sentence is: not yet shown.
Your next step
If you have a multi-agent build — or are about to start one — look at every place one agent reaches another and ask a single question: does an answer need to come back here?
Everywhere the answer is yes, that step must be a call. Everywhere it is genuinely no — the other agent takes over and this one is finished — a transition is right. Get those straight before you tune a single word of instructions, because no amount of prompt work will retrieve a reply that had nowhere to return to.