What you will be able to do
- Explain what a sub-agent can and cannot know when a coordinating agent dispatches it
- Trace duplicated work, format drift and conflicting decisions back to dispatch messages that left out the coordinator's decisions
- Choose the dispatch fix that gives sub-agents the decisions they need without enlarging their context windows, and reject fixes that forward raw traces, raise token limits or merge agents
Key concept
Dispatch context — When a sub-agent is dispatched, the dispatch message is the only context it gets. Any decision or constraint that stays in the coordinator's trace and is not written into that message does not exist for the sub-agent.
1.What a sub-agent sees at dispatch time
By the time a coordinating agent splits a task into pieces, it already knows a lot about that task. Its trace holds the user's request, any clarifications, the tool results it gathered, and the decisions it made along the way. It might have chosen an output schema, agreed on an interface signature, settled which background facts are known, or drawn the line between one subtask and the next. Those decisions are what keep the pieces compatible when they come back together.
None of that context reaches a sub-agent automatically. A sub-agent starts with an empty context and knows only what the dispatch message tells it. In a Databricks orchestrator, each subagent is called as a tool. The dispatch is the input to that tool call, and whatever the coordinator writes there is everything the sub-agent will ever know about the larger task.
The coordinator can hand that context over in two extreme forms. A bare task message is a single line such as "Research subtopic X" or "Refactor module A for the new interface." It costs almost nothing, and it drops every decision the coordinator made. A full agent trace is the coordinator's whole history: the ordered transcript of messages, tool calls and results. It carries every decision, along with every dead end, raw tool output and exploratory step, and the sub-agent has to read all of it to find the three facts that matter to its subtask.
Downstream failures in this subdomain come from the first extreme. The fix lies between the two. The sub-agent needs the decisions in the trace, not the trace itself.
Checkpoint 1 of 6· Check yourself
A coordinating agent spent several turns agreeing on an output schema with the user. It then dispatched a sub-agent, as a tool call, with the input "Research subtopic X". The sub-agent's result came back in a different format. What best explains this?
The sub-agent is called as a tool and starts with an empty context. The tool-call input is everything it knows about the larger task. A bare one-line task message drops every decision the coordinator made, including the schema, so the sub-agent never received it. The cause is the dispatch message, not the size of the sub-agent's context window.
“The orchestrator treats each subagent as a tool and uses its instructions to route requests to the right one.”Source: docs.databricks.com
2.Diagnosing a dispatch failure from its downstream symptoms
Dispatch failures rarely show up at the sub-agent. Each sub-agent completes its subtask, often well. The failure shows up when the coordinator puts the results together. Three symptoms are typical:
- Duplicated work. Several sub-agents research or restate the same background because none of them was told it was already established or assigned to someone else.
- Format drift. Results come back in shapes that cannot be merged, such as one table, one essay and one bulleted list, because no output format was specified.
- Conflicting decisions. Two sub-agents each make a choice the coordinator had already made, and they make it differently. In a refactor split by module, two modules end up with incompatible method signatures because neither sub-agent was told which signature the coordinator had agreed on.
All three symptoms have the same signature. A decision existed in the coordinator's trace and was never written into the dispatch message. Each sub-agent filled the gap with its own reasonable guess, and different sub-agents guessed differently. That pattern is what distinguishes a dispatch failure from the other diagnoses it gets confused with.
Rule out the alternatives by asking what each one would actually produce. A context window that is too small fails when the sub-agent runs out of room, but these sub-agents never received the shared facts at all, so more room would hold nothing new. Missing tools lead to thin or incomplete research, not two well-researched answers in incompatible formats. Parallel execution does not cause duplication by itself, because independent subtasks are exactly what parallelism suits. Duplication appears when nobody tells the parallel workers where their boundaries are. Too many sub-agents, oversized modules or a stale copy of the codebase would all produce other errors. None of them explains why two modules disagree on exactly the signature the coordinator had already settled.
The diagnosis can be confirmed rather than guessed. In MLflow Tracing, a multi-agent run is recorded as a tree of spans, and the sub-agent call is one of them. Open that span and read its inputs. If the input is one line and the agreed signature or format is missing, the root cause is in the dispatch. For the broader set of failures caused by insufficient shared context, see shared-context failure modes.
Checkpoint 2 of 6· Check yourself
Two refactor sub-agents returned modules with incompatible method signatures. A teammate wants to double each sub-agent's context window. Before changing anything, what evidence in the MLflow trace would confirm or rule out a dispatch failure?
Each sub-agent call is its own span, and a span records what went into that call. If the inputs are one task line with no agreed signature, the decision never left the coordinator's trace and the cause is the dispatch. A larger window, a sequential run or the user's original request would not show what the sub-agent actually received.
“Each span represents one operation: it records what went in, what came out, how long it took, and any metadata.”Source: docs.databricks.com
Checkpoint 3 of 6· Exam question
A coordinating agent splits a competitive-analysis task into four subtopics and dispatches one sub-agent per subtopic, sending each sub-agent only a single line such as "Research subtopic X." When the sub-agents report back, three summaries repeat the same industry background facts, and two use incompatible output formats. What is the most likely root cause?
Correct answer: A — Sub-agents got bare one-line tasks instead of a shared briefing on objective and format
Checkpoint 4 of 6· Exam question
A coordinating agent decomposes a codebase refactor into per-module tasks and dispatches a sub-agent to each module with a short instruction like "Refactor module A for the new interface." The sub-agents never learn what interface signature the coordinator already agreed on, so two modules end up implementing different, incompatible method signatures. What should the team conclude?
Correct answer: A — The dispatch messages omitted the shared decisions each sub-agent needed to stay consistent
3.Fixing dispatch without enlarging sub-agent windows
The fix is for the coordinator to write each dispatch as a self-contained brief: a condensed version of the parts of its trace that apply to this subtask. Done well, the brief is a few hundred tokens and contains:
- Objective. What the overall task is, and what this subtask contributes to it.
- Output format. The exact shape the result must take, so results from every sub-agent can be merged.
- Scope boundary. What is in scope, what other sub-agents are covering, and which facts are already established and should not be researched again.
- Shared decisions and constraints. Choices the coordinator has already made, written out exactly, such as the agreed method signature.
Decisions that apply to every sub-agent belong in a shared form. Write them once, as one block or one shared reference, and pass the identical text to every dispatch, rather than paraphrasing them separately for each sub-agent. Separate paraphrases are another way for sub-agents to drift apart. Keeping later decisions consistent once agents are running is a separate topic, covered by context propagation to prevent conflicts.
| Change | Gives sub-agents the missing decisions? | Effect on each sub-agent's context |
|---|---|---|
| Coordinator writes a brief with objective, output format, scope boundary and shared decisions | Yes | Small and bounded: only what the subtask needs |
| Forward the coordinator's entire raw trace to every sub-agent | Yes, buried among irrelevant history | Grows with the coordinator's whole history, repeated for each sub-agent |
| Raise each sub-agent's token limit | No: more room, but still nothing new in it | Larger window, which the constraint rules out |
| Merge all sub-agents into one agent that works through every subtask in turn | Yes, because there is no handoff left | One context that grows across every subtask |
Forwarding the full trace is the tempting wrong answer, because it does close the information gap. It closes the gap in the most expensive way possible. Every sub-agent is loaded with the coordinator's exploration, and the one decision that matters has to compete for attention with everything around it. Raising token limits fails for a simpler reason: the sub-agents never needed more space, they needed the decisions. Merging everything into one agent removes the handoff and the decomposition along with it. A single agent working across several distinct subdomains can become overloaded, and its context keeps growing with each subtask.
The brief covers the outbound direction only. What sub-agents send back to the coordinator is a separate design problem with its own fix, covered by sub-agent output design for orchestrator load.
Checkpoint 5 of 6· Match them up
A coordinator's sub-agents keep returning results that can't be merged, and the team must not enlarge any sub-agent's context. Match each proposed change to what it actually does.
Tap a term, then the definition that fits it.
Only the condensed brief closes the information gap while keeping each sub-agent's context bounded. The raw trace closes the gap at the cost of a much larger context. A bigger window adds nothing new. Merging gives up the decomposition, and a single agent spanning distinct subdomains can become overloaded.
“If your application spans radically different sub-domains (finance, devops, marketing, etc.), a single agent can become unwieldy or overloaded with functionality requirements.”Source: docs.databricks.com
Checkpoint 6 of 6· Exam question
Continuing from the same competitive-analysis system: the team confirms the root cause is that sub-agents were dispatched bare task lines instead of self-contained instructions. They must fix this without enlarging any sub-agent's context window. Which configuration change should they make?
Correct answer: A — Have the coordinator craft each dispatch message with an objective, output format, and scope boundary
Sources5
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“The orchestrator treats each subagent as a tool and uses its instructions to route requests to the right one.”
↩︎ What a sub-agent sees at dispatch time“The orchestrator treats each subagent as a tool and uses its instructions to route requests to the right one.”
↩︎ Key concept - 2.
“Most commonly this is the conversation history (the ordered transcript of messages, tool calls, and results)”
↩︎ What a sub-agent sees at dispatch time“Most commonly this is the conversation history (the ordered transcript of messages, tool calls, and results)”
↩︎ Exam trap 2 - 3.
“Each span represents one operation: it records what went in, what came out, how long it took, and any metadata.”
↩︎ Diagnosing a dispatch failure from its downstream symptoms - 4.
“With only an input and final response, you cannot tell which intermediate decision caused a failure.”
↩︎ Diagnosing a dispatch failure from its downstream symptoms - 5.
“If your application spans radically different sub-domains (finance, devops, marketing, etc.), a single agent can become unwieldy or overloaded with functionality requirements.”
↩︎ Fixing dispatch without enlarging sub-agent windows“If your application spans radically different sub-domains (finance, devops, marketing, etc.), a single agent can become unwieldy or overloaded with functionality requirements.”
↩︎ Exam trap 3
Also cited
“Open a trace to inspect its details end to end: the span tree, and each step's inputs, outputs, timing, and errors.”
↩︎ Exam trap 1