How to Organize Multi-Agent Systems
A multi-Agent system must simultaneously address role definition, spawn, state querying, cancellation, completion notification, and resource inheritance. Grok Build's source code distributes these responsibilities across a definition layer and a coordination event layer.
Read Grok Build's actual organization pattern from subagent_coordinator, and use task dependencies, context requirements, file conflicts, and aggregation cost to select an organization strategy.
The parent session manages a set of identified sub-Agents through an event channel
Coordinator here is the real component name from the Grok Build source code. The layout is for teaching purposes.
Definition Layer: AgentDefinition + Persona
AgentDefinition provides the contract: prompt, tools, permissions, model, MCP inheritance, and spawnable types. Persona appends behavioral instructions, I/O contracts, and some runtime defaults. Together they give each sub-Agent an observable identity and capability boundary.
Coordination Layer: SubagentEvent
start_subagent_coordinator starts a single drain task. Each Spawn event then starts a local async task that calls handle_subagent_request.
Parallel Execution
Spawn events enter spawn_local independently; the coordinator tracks pending, active, and completed states. Parallel capability comes from async tasks and is not limited by the number of Personas.
Results and Waiting
Query can immediately return a snapshot or register a block wait slot and poll for status. Completions drains pending notifications and filters by suppress_ids.
Cancellation and Cleanup
Cancel supports targeting by subagent ID or parent prompt ID. The coordinator also evicts expired completed records and logs explicit kills.
What Can Be Compared Is Product Surface Behavior
Claude Code publicly supports custom subagents: each subagent can have its own context, system prompt, tool permissions, and model; the main session can auto-delegate or the user can invoke them explicitly. The public Agent Teams feature description includes shared tasks, inter-member messaging, and independent contexts. This lesson does not treat "Coordinator" or "Swarm" as internal Claude Code source types, nor infer their scheduler implementation.
Single Main Session Delegation
Suitable when one owner decomposes tasks, chains dependencies, and aggregates results. Grok's task + coordinator events and Claude's public subagent delegation both support this workflow.
Multi-Member Collaboration
Suitable when members need to communicate with each other and claim shared tasks. Evaluate based on the public Agent Teams behavior and current version limitations.
Role Reuse
Suitable for long-running recurring roles like reviewer, explorer, or planner. Grok uses AgentDefinition and Persona; Claude's public configuration uses subagent definition files.
while let Some(event) = rx.recv().await {
match event {
SubagentEvent::Spawn(boxed) => { /* handle request */ }
SubagentEvent::Query(query) => { /* snapshot or block */ }
SubagentEvent::Cancel(request) => { /* cancel target */ }
SubagentEvent::ListActive(request) => { /* summaries */ }
SubagentEvent::Completions(request) => { /* drain */ }
...
}
}Note: Event variants and control structures are from real source code; branch bodies are condensed for the classroom. There is no source snapshot for the Claude side — all descriptions are limited to publicly documented behavior.
Classroom Exercise: Scenario Decision
For each of the three scenarios below, choose "Single Agent", "Main session + subagents", or "Multi-member shared tasks", and explain the parallelism benefit, dependencies, context copy cost, file conflicts, and aggregation responsibility.