Multi-Agent Orchestration: Making Collaboration Attributable with Event Streams
This article explains how to make multi-agent collaboration traceable by treating the coordination process as an explicit event stream, covering team structure as configuration, delegation and handoff events with reasons, speaker change signals, and session rollover, enabling auditability and debugging of agent interactions.
Aligning Terminology
Agent Platform : The platform we build to help developers create agents
Agent : An agent produced on the platform; developers create it, users converse with it
Lead : The scheduler in a team: receives user questions, decides who handles them
Member : Agents invoked by the lead, each responsible for a domain
Delegation : Lead assigns a concrete question to a member, specifying what to answer
Handoff : Lateral transfer between members, with a reason for the transfer
Speaker Change : The current speaker changes; UI starts a new segment
Speech Segment : A continuous output from the same role, not interrupted by others
Member Role Description : A required one-sentence description when creating a team: what this member does
Rollover : When conversation gets too long, start a new round; clear both UI and context
(Common terms like SSE, turn, token are used directly without explanation.)
Multi-agent engineering's first hurdle is not "how to make them collaborate" but "how to make the collaboration process attributable" — who is speaking, who was delegated to, why, and who finished. This article focuses on that.
01 | Global Perspective: Three "Collaborated But No One Understands" Scenarios
Imagine a restaurant kitchen producing a banquet; each section maps to engineering concepts:
Head Chef → Lead: Breaking down orders, dispatching, collecting results; Not cooking every dish personally
Station → Member: Producing its own dish; Not managing other stations
Order Ticket → Delegation: Specifies what to do and for whom; Does not specify how to do it
Passing Ticket → Handoff: Lateral handover with reason; No silent handovers allowed
Pass Sign → Speaker Change: Shows who produced this dish; Does not show next dish
Calling "Done" → Member Completion: This segment ends; Does not mean whole order ends
Table Turnover → Rollover: Clear table, start fresh; Does not keep leftovers
Three failure scenes:
Scene 1: Delegated but no one picked up. Symptom: Lead says "I'll have X look into it" then nothing. Misdiagnosis: member crashed. Reality: no structured delegation event was emitted — the text was just narrative, downstream couldn't know to switch executor.
Scene 2: Finished but no one knows. Symptom: Member output complete but UI shows "in progress". Misdiagnosis: increase timeout, add heartbeats. Reality: missing explicit completion signal . "No more content" and "segment ended" are different; the former is unreliable — model may emit more.
Scene 3: Context crosstalk during rotation. Symptom: A's speech contains B's tone, or B continues A's half-sentence. Misdiagnosis: model confused. Reality: no attribution markers in the same output stream , downstream guesses speaker from content. Guessing attribution from content will always fail.
02 | Why Common Approaches Fail: Three Fractures
Fracture 1: Treating Team as a New Entity
Intuitive approach: create a "team table" with name, description, members. Cost is huge: team must go through publishing pipeline, adapt to IDE/IM entrypoints, reimplement permissions and collaboration. Only three things truly need new stuff: member relationships, list filtering, conversation routing.
Our approach: keep the lead as a regular Agent with just a type tag; member relationships in a separate table, each record requiring a "what this member does" description. Lead automatically inherits publishing, permissions, entrypoints; only relationships and routing are new.
Fracture 2: Scheduling Process Is a Black Box
Why did lead delegate to A not B? If reasoning stays inside model, user sees another agent's speech appear magically. Trust is lost: result visible, reasoning invisible.
Solution: lead emits reasoning as a "thought" block before delegation instruction, and renders it separately — distinct from final answer but visible to user. Delegation and handoff each carry "what to answer" and "why transfer".
Fracture 3: Output Lacks Attribution Boundaries
When multiple agents share one text stream, the only reliable segmentation is who is speaking . Therefore "speaker change" must be an explicit event, not inferred from content. With it, UI can have "one bubble = one continuous speech"; without it, all downstream designs (citation, retry, reconciliation) are impossible.
Comparison: Four Approaches
Single Agent Handles All : Provides simplest implementation; Steals no coordination cost; Rejects as default: fails when domains multiply
Multiple Agents Speak Independently : Provides clear division of labor; Steals clear boundaries; Rejects without attribution markers: UI will crosstalk
Lead Delegation + Eventification : Provides attributable, renderable; Steals scheduling transparency; Rejects writing delegation as plain natural language
Cross-Process Cluster Scheduling : Provides parallelizable; Steals high throughput; Rejects doing now: we haven't reached that step
03 | Overall Approach: Turn "Who Does What and Why" into Event Stream
Multi-agent engineering is attribution: decompose collaboration into a set of events anyone can consume.
Two layers:
Organizational Layer : Who is lead, members, each member's responsibility. Developer configures once. Almost never changes.
Expression Layer : Who is speaking this round, who was delegated to, who finished. User watches every second. Changes every round.
Iron law connecting them: Organizational layer decides "who can be delegated to", expression layer records "who was actually delegated to". Former is configuration, latter is fact; they cannot substitute each other — config says A can do it, doesn't mean this round actually delegated to A.
Back to kitchen: wall shows each station's duty (organizational), pass sign shows who actually produced this dish (expression). When they mismatch, the pass sign is wrong.
04 | Key Design 1: Team Is Not a New Entity
This section determines whether existing capabilities can be reused.
Lead : Remains a normal Agent record with a type tag → Publishing, permissions, entrypoints all inherited automatically
Member : Relationships in a separate table, one row per member → A member can belong to multiple teams simultaneously
Member Role Description : Required when creating relationship: one-sentence description → Lead has basis for delegation decisions
Scope of Difference : Only three places: list filtering, member relationships, conversation routing → All other capabilities unchanged
"Role description required" seems trivial but is the source of delegation quality. Lead must have each member's one-sentence description to decide; without it, it guesses by name — the most unreliable signal.
Illustrative code for consuming organizational layer:
// Illustrative · TypeScript: Lead decides who to delegate to (only looks at organizational layer)
type Member = { agentId: number; name: string; duty: string };
function pickMember(question: string, members: Member[]): Member | null {
// duty is the required description from team creation, not guessed at runtime
const hit = members.find(m => question.includes(m.duty.slice(0, 4)));
return hit ?? members[0] ?? null;
}
function buildDelegation(from: Member, to: Member, question: string) {
return {
kind: "delegate",
fromName: from.name,
toName: to.name,
question, // what to answer, must be explicit
};
}# Illustrative · Python: same logic
def pickMember(question: str, members: list[Member]) -> Member | None:
# duty is the required description from team creation, not guessed at runtime
for m in members:
if m.duty[:4] in question:
return m
return members[0] if members else None
def buildDelegation(frm: Member, to: Member, question: str) -> dict:
return {
"kind": "delegate",
"fromName": frm.name,
"toName": to.name,
"question": question, # what to answer, must be explicit
}Boundary: Organizational layer only answers "who can be delegated to", not "whether delegation succeeded this round". Success must be seen in expression layer events — that's why config alone cannot prove collaboration happened.
Kitchen analogy: wall says "cold dishes belong to Station A", doesn't mean this order's cold dish actually went to A. Need to check the pass ticket.
05 | Key Design 2: Making Collaboration Consumable
Expression layer's minimal event set — six types, each maps to a concrete UI action:
Speaker Change : Trigger when current speaker changes → UI Action: Start new segment with this person's name
Delegation : Trigger when lead assigns question to member → UI Action: Insert banner between segments: who, what question
Handoff : Trigger when member-to-member lateral transfer → UI Action: Insert banner: from whom, to whom, why
Member Completion : Trigger when this person finished this segment → UI Action: Mark current segment as done
Tool Call / Result : Trigger when member invoked a tool → UI Action: Pair into a single status line, not scattered
Conversation Init / Rollover : Trigger when round starts or new round → UI Action: Sync session ID; rollover clears UI
Three designs worth highlighting:
First, thinking as separate block. Lead emits reasoning before delegation instruction. If mixed into final answer it reads like noise; if dropped, delegation becomes black box. Solution: independent collapsible block — those who want to see "why delegated to him" can, others undisturbed.
Second, delegation and handoff must carry reasons. Delegation includes the question; handoff includes why transferring. These aren't decoration: when things go wrong, they are the only forensic trail.
Third, rollover must clear everything, not continue writing. When conversation gets too long, start new round; clear both UI and context. Half-cleared is worst — UI shows new round but model still holds previous round's leftovers.
Illustrative code for transforming events into UI structure:
# Illustrative · Python: events → message list (flattened to list items)
def applyEvent(items: list[dict], state: dict, ev: dict) -> None:
kind = ev["kind"]
if kind == "speakerChange":
if state.get("currentTurn") is not None:
items[state["currentTurn"]]["status"] = "done"
items.append({"kind": "turn", "speaker": ev["speakerName"],
"role": ev["role"], "blocks": [], "status": "streaming"})
state["currentTurn"] = len(items) - 1
elif kind == "delegate":
items.append({"kind": "delegate", "fromName": ev["fromName"],
"toName": ev["toName"], "question": ev["question"]})
elif kind == "handoff":
items.append({"kind": "handoff", "fromName": ev["fromName"],
"toName": ev["toName"], "reason": ev["reason"]})
elif kind == "memberDone":
idx = state.get("currentTurn")
if idx is not None:
items[idx]["status"] = "done"
state["currentTurn"] = None
elif kind == "rollover":
items.clear() # clear UI
state["currentTurn"] = None # no leftovers from previous round// Illustrative · TypeScript: same logic
function applyEvent(items: Item[], state: State, ev: Event): void {
switch (ev.kind) {
case "speakerChange":
if (state.currentTurn !== undefined) items[state.currentTurn].status = "done";
items.push({ kind: "turn", speaker: ev.speakerName, role: ev.role,
blocks: [], status: "streaming" });
state.currentTurn = items.length - 1;
break;
case "delegate":
items.push({ kind: "delegate", fromName: ev.fromName,
toName: ev.toName, question: ev.question });
break;
case "handoff":
items.push({ kind: "handoff", fromName: ev.fromName,
toName: ev.toName, reason: ev.reason });
break;
case "memberDone":
if (state.currentTurn !== undefined) items[state.currentTurn].status = "done";
state.currentTurn = undefined;
break;
case "rollover":
items.length = 0; // clear UI
state.currentTurn = undefined; // no leftovers from previous round
break;
}
}Boundary: Message model is a flat list of items , not a nested tree. Delegation and handoff are banners inserted between segments, not part of any agent's bubble content — this distinction determines what citation and retry apply to.
Kitchen: the pass ticket sits between two stations; it belongs to neither dish.
06 | Verification: "Three People Investigate One Production Issue"
Scenario 1 (Easy): A Clearly Divisible Problem
User asks "What caused the 3 AM alert?" Lead splits into three: check logs, check release records, check dependent services.
Lead first explains why splitting this way (thought block), then delegates one by one.
Before each member starts, UI shows a delegation banner stating the question.
Each speaker change starts a new segment; never mix two people's speech in one bubble.
When a member finishes, completion signal marks segment done immediately.
Lead finally collects and synthesizes three conclusions into one readable answer.
Decision point: If lead raises a new question while collecting, answer first then delegate — user needs to see existing conclusion, not wait for next round.
Scenario 2 (Hard): Discovering Wrong Direction Mid-Way
Member realizes this isn't their domain, should handoff not force an answer. Handoff must include reason.
Receiver can continue handoff if unsure, but handoff chain must have a limit or it becomes hot potato.
Every member's every speech carries attribution; post-mortem can reconstruct full path by person.
Decision point: If handoff exceeds two times with no one catching, the division of labor itself is unclear — fix the organizational layer (member role descriptions), not ask lead to try again.
Rollover Timing
When conversation grows long, start new round. Criterion is not length but whether attribution remains clear : once "who said this" requires guessing from content, it's time to rollover. Rollover clears both UI and context; half-cleared destroys both.
07 | Three Layers of Change Brought by This Solution
⚡ Quantified efficiency. No need to read full text to judge "who said what" — attribution, delegation, completion are explicit events, directly consumable.
📥 Capability sinking. Team capabilities built on existing Agents; publishing, permissions, entrypoints unchanged; developers only configure members and responsibilities once.
📚 Pattern upgrade. From "one Agent does everything" to "a group of Agents each own a domain, process traceable". The real leap is not better results but ability to retrospective when things go wrong .
Selection: How to Choose Among Four Approaches
Implementation Cost : Single Agent Low, Multi-Agent No Attribution Medium, Lead Delegation + Events Medium, Cross-Process Cluster High
Domain Coverage : Single Agent Low, Multi-Agent No Attribution High, Lead Delegation + Events High , Cross-Process Cluster High
Process Attributable : Single Agent Low, Multi-Agent No Attribution Low, Lead Delegation + Events High , Cross-Process Cluster Medium
Reuse Existing Capabilities : Single Agent High, Multi-Agent No Attribution Medium, Lead Delegation + Events High , Cross-Process Cluster Low
Currently Feasible : Single Agent High, Multi-Agent No Attribution Medium, Lead Delegation + Events High , Cross-Process Cluster Low
Steal the "reuse existing capabilities" column: making lead a normal Agent with a type tag saves the entire publishing pipeline compared to creating a new team entity. Reject "cross-process cluster scheduling now" — our current collaboration is turn-taking within a single session , members don't run in parallel, no cross-process cluster scheduling; this boundary must be honestly documented, not drawn in architecture diagrams.
08 | When Not to Copy This and Four Pitfalls
Not applicable:
Tasks requiring true parallelism (multiple members working simultaneously, results merged later): current model is turn-taking, serial execution.
Members needing shared write state (e.g., two members editing same files): no cross-member write coordination, would overwrite each other.
Need cross-process / cross-machine scheduling : collaboration happens within one session, no cluster scheduling or external protocols.
Pitfall 1: Writing Delegation as Natural Language
Temptation: "I'll have X look into it" feels clear enough. Wrong fix: let downstream parse person and task from that sentence — parsing will miss. Right fix: delegation is independent event with fields: from, to, what to answer.
Pitfall 2: Using "No Output" to Judge Completion
Temptation: stream quiet for a few seconds, assume segment ended. Wrong fix: rely on timeout — model may emit more, timeout too early truncates. Right fix: explicit completion event; without it, not done.
Pitfall 3: Clearing Only UI on Rollover
This isn't a pitfall, it's laziness: rollover clears UI but model retains previous round's content. Result: new round mixes previous round's roles and conclusions, user confused. Either clear both or clear neither.
Pitfall 4: Guessing Attribution from Content
Temptation: event stream lacks speaker change, so infer speaker from content. Wrong fix: guess by tone and wording — guessing wrong is inevitable and insidious. Right fix: speaker change is explicit event; if missing, add event, don't guess downstream.
Action Levels
L1 : View full collaboration path, export a member's speeches → Approved by on-call engineer
L2 : Add/remove members, modify member role descriptions → Approved by team lead
L3 : Change delegation/handoff event fields, alter rollover strategy → Approved by change review board
L3 exists solely because: changing event fields forces all consumers to change.
Summary
Multi-agent: solve attribution first, then capability : who speaks, who delegated to, why, who finished — missing any makes retrospective impossible.
Team is not a new entity : lead remains normal Agent with a type tag; only additions are member relationships and conversation routing.
Member role description required — it's the only reliable basis for lead's delegation decisions.
Delegation and handoff must carry reasons — they are the only forensic trail when things go wrong.
Speaker change is an explicit event — guessing attribution from content will always fail.
Rollover: either clear both or clear neither ; half-cleared destroys both UI and context simultaneously.
Turning collaboration process into an event stream isn't for aesthetics — it's so that when incident happens, you can point to a record and say: the handoff went wrong right here.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
