Chapter 9: Assembling MAS with Subagents
This introduction explains how a main LLM agent can delegate tasks to subagents and how subagent dispatch works through a tool.
After this chapter you will be able to
- Main and subagent identity. Explain how the main LLM agent and its subagents relate in the framework.
- Tool based subagent dispatch. Trace how an agent selects and dispatches a subagent through a tool and receives its result.
- Task history context sprawl. Explain why a long-running task can put pressure on an LLM agent’s context window.
- Isolated subagent result sharing. Explain how subagent delegation reduces the main agent’s context when only a subtask’s result is needed.
- Specialized reusable subagent configurations. Explain how configuring and reusing specialized subagents can support consistent, repeatable task execution.
- Subagent specification and dispatch. Distinguish SubAgentSpec from UseSubAgentTool by describing what each contributes to subagent execution.
- Subagent configuration and construction. Explain what SubAgentSpec stores and how it supports constructing and configuring a subagent.
- Subagent catalog disclosure. Describe what SubAgentSpec.catalog() returns and why.
- Subagent tool and registry. Describe how UseSubAgentTool is configured and how it points the main agent to available subagents.
- Subagent dispatch argument schema. Explain what the backbone LLM supplies to dispatch a subagent and how the tool's schema constrains those arguments.
- Validated subagent execution. Trace how UseSubAgentTool handles a call from argument validation through dispatch and return.
- Subagent registry lifecycle. Explain how LLMAgent establishes its subagent registry and why it stays fixed across task runs.
- TaskHandler subagent wiring. Describe how TaskHandler makes subagents visible and dispatchable to the backbone LLM during run_step().
- Subagent dispatch sequence. Trace what happens when TaskHandler executes a request for UseSubAgentTool, through returning the result.
- Context across subagent dispatches. Explain the fresh-task limitation and how context can be preserved across separate subagent dispatches.
- Default subagent roles and permissions. Distinguish the general and explore subagents by their tools and the tasks suited to each.
- Reusable subagent recipe factories. Explain what a default subagent recipe produces and how its parameters and reuse support customization.
- Subagent dispatch depth. Explain dispatch depth using depths one and two, and describe the depth of a system made only from the default recipes.
- Shared console race prevention. Explain why concurrent subagents can misattribute human responses and how a shared lock prevents the problem.
- Asynchronous human input coordination. Explain how the asynchronous tool waits for the shared lock and obtains human input without blocking the event loop.
- Router Pattern Purpose. Explain how a coordinator routes a task or subtask to a subagent and when this pattern is useful.
- Subagent Selection Mechanism. Describe how the coordinator selects a subagent using the framework's existing tool-selection process.
- Fan-out coordination lifecycle. Trace how a coordinator uses Fan-out to execute and complete an overall task.
- Sequential Subagent Dependencies. Explain how Chaining coordinates subagents and why it suits dependent subtasks.
- Chain Order Specification. Describe how the order of a chain can be specified or determined.
What it builds on
- LLMAgent: a simple LLM agent class (chapter 4) · LLMAgent provides the framework’s agent class.
- LLMAgentBuilder: a dynamic builder of LLMAgent (chapter 5) · LLMAgentBuilder constructs LLMAgent instances.
- Implementing ToolCall and ToolCallResult (chapter 2) · Tool calls and their results represent tool interactions.
- Designing a processing loop (chapter 4) · The agent’s task-execution loop and its use of prior steps
- Understanding skills (chapter 6) · Skills provide a way to document specialized workflows.
- Disclosing discovered skills to the backbone LLM (chapter 6) · Skills are disclosed to the backbone LLM.
- The AsyncBaseTool (chapter 2) · The asynchronous base tool interface.
- Defining BaseTool (chapter 2) · Tool properties describe valid tool-call arguments.
Section by section
Introduction
This introduction explains how a main LLM agent can delegate tasks to subagents and how subagent dispatch works through a tool.
- Main and subagent identity: Explain how the main LLM agent and its subagents relate in the framework.
Why it matters: This shows that a subagent is an agent in a delegated role, not a different class of agent. - Tool based subagent dispatch: Trace how an agent selects and dispatches a subagent through a tool and receives its result.
Why it matters: This connects delegation to the familiar tool-call interface.
Key terms: main LLM agent, subagents, LLMAgent, LLMAgentBuilder, registry of subagents, descriptions, tool call, delegated task, tool call result
9.1 Using subagents for context management and specialization
9.1.1 Context management
This section explains how delegating subtasks to isolated subagents helps prevent context sprawl in an LLM agent.
- Task history context sprawl: Explain why a long-running task can put pressure on an LLM agent’s context window.
Why it matters: Understanding context sprawl explains why delegation can be useful even when the main agent could perform a subtask itself. - Isolated subagent result sharing: Explain how subagent delegation reduces the main agent’s context when only a subtask’s result is needed.
Why it matters: Result-only sharing keeps the details of subtask execution from flooding the main agent’s context.
Key terms: context sprawl, task history, context window, subagent, subtask, execution rollout
9.1.2 Specialization and repeatability
This section explains how specialized subagents support repeatable task execution, narrower permissions, and lower costs.
- Specialized reusable subagent configurations: Explain how configuring and reusing specialized subagents can support consistent, repeatable task execution.
Why it matters: Reusable specialization helps an agent handle recurring work in a consistent way. - Task scoped subagent permissions: Explain how specialization can narrow a subagent's permissions and reduce its attack surface.
Why it matters: Limiting a specialized agent's access can reduce its attack surface. - Cost efficient model selection: Explain how assigning simpler tasks to subagents with less capable models can reduce overall costs.
Why it matters: Matching model capability to task difficulty can make a multi-agent system less expensive.
Key terms: subagent, tools, skills, prompt templates, consistency, repeatability, permissions, principle of least privilege, attack surface, read-only access
9.2 Supporting subagents in our framework
This section introduces the framework’s mental model for specifying subagents and dispatching them to subtasks.
- Subagent specification and dispatch: Distinguish SubAgentSpec from UseSubAgentTool by describing what each contributes to subagent execution.
Why it matters: This distinction separates how subagents are defined from how they are dispatched to work.
Key terms: SubAgentSpec, UseSubAgentTool, backbone LLM, subtasks
9.2.1 SubAgentSpec: a core type for specifying a subagent
This section introduces SubAgentSpec as a configuration for constructing, running, and describing a subagent.
- Subagent configuration and construction: Explain what SubAgentSpec stores and how it supports constructing and configuring a subagent.
Why it matters: The specification brings together the information needed to create and configure a subagent. - Subagent catalog disclosure: Describe what SubAgentSpec.catalog() returns and why.
Why it matters: The catalog provides an LLM agent with a representation of the subagent’s details.
Key terms: SubAgentSpec, LLMAgentBuilder, dispatch time, max_steps, skills_scopes, explicit_only_skills, catalog(), XML-formatted string, template
9.2.2 Implementing UseSubAgentTool
This section implements and demonstrates an asynchronous tool that dispatches registered subagents and returns their results.
- Subagent tool and registry: Describe how UseSubAgentTool is configured and how it points the main agent to available subagents.
Why it matters: The tool needs the same available-subagent registry that the main agent uses to select a delegate. - Subagent dispatch argument schema: Explain what the backbone LLM supplies to dispatch a subagent and how the tool's schema constrains those arguments.
Why it matters: The schema tells the LLM how to request a valid delegation to an available subagent. - Validated subagent execution: Trace how UseSubAgentTool handles a call from argument validation through dispatch and return.
Why it matters: This execution path turns a valid delegation request into a subagent result the calling agent can receive. - Subagent log attribution: Explain how the framework distinguishes subagent logs from those of other agents.
Why it matters: Named log entries make it possible to tell which agent produced each message.
Key terms: UseSubAgentTool, AsyncBaseTool, _subagents_registry, system message, parameters_json_schema, enum, subagent name, task instruction, __call__, Task
9.2.3 Updating LLMAgent and TaskHandler
This section updates LLMAgent and TaskHandler to register, disclose, and dispatch subagents during task execution.
- Subagent registry lifecycle: Explain how LLMAgent establishes its subagent registry and why it stays fixed across task runs.
Why it matters: The registry determines which subagents the agent can dispatch across its task runs. - TaskHandler subagent wiring: Describe how TaskHandler makes subagents visible and dispatchable to the backbone LLM during run_step().
Why it matters: The LLM needs both awareness of available subagents and a tool to dispatch them. - Subagent dispatch sequence: Trace what happens when TaskHandler executes a request for UseSubAgentTool, through returning the result.
Why it matters: This sequence connects the LLM's tool request to the delegated work and its returned outcome. - Context across subagent dispatches: Explain the fresh-task limitation and how context can be preserved across separate subagent dispatches.
Why it matters: Delegated tasks need explicit context unless the subagent has memory to preserve it. - Circular import precautions: Describe why the updated classes need circular-import precautions and how the section addresses them.
Why it matters: These precautions let the components reference one another without creating import-time cycles.
Key terms: subagents_registry, SubAgentSpec, Skills, TaskHandler, _use_subagent_tool, UseSubAgentTool, _subagents_catalog, run_step(), system message, Task
9.2.4 Defining default subagents
This section defines reusable general and explore subagent recipes and explains their tool permissions and dispatch depth.
- Default subagent roles and permissions: Distinguish the general and explore subagents by their tools and the tasks suited to each.
Why it matters: Choosing the right subagent matches its capabilities and permissions to the task. - Reusable subagent recipe factories: Explain what a default subagent recipe produces and how its parameters and reuse support customization.
Why it matters: Recipes make subagent configurations reusable and customizable across projects. - Subagent dispatch depth: Explain dispatch depth using depths one and two, and describe the depth of a system made only from the default recipes.
Why it matters: Dispatch depth clarifies how far delegation can extend in a subagent hierarchy.
Key terms: general subagent, explore subagent, permissions, subagent recipes, SubAgentSpec, LLMAgentBuilder, llm, name, max_steps, dispatch depth
9.3 Supporting tool-based HITL in MAS
This section makes tool-based human input safe for concurrent subagents by introducing a shared, asynchronous console lock.
- Shared console race prevention: Explain why concurrent subagents can misattribute human responses and how a shared lock prevents the problem.
Why it matters: Serializing console access keeps human responses associated with the right subagent. - Asynchronous human input coordination: Explain how the asynchronous tool waits for the shared lock and obtains human input without blocking the event loop.
Why it matters: The design coordinates concurrent requests without tying up a worker thread for every call waiting on the lock. - Replacement tool interface: Describe how SharedConsoleHumanInputTool retains the original tool interface while identifying the prompting subagent.
Why it matters: The familiar tool interface can be reused while prompts identify their originating subagent.
Key terms: HumanInputTool, SharedConsoleHumanInputTool, shared lock, human operator, AsyncBaseTool, _console_lock, asyncio.Lock, _prompt_human(), worker thread, coroutines
9.4 MAS patterns using subagents
9.4.1 Router
This section explains the Router pattern for selecting a subagent and demonstrates it with a local Hailstone sequence lookup.
- Router Pattern Purpose: Explain how a coordinator routes a task or subtask to a subagent and when this pattern is useful.
Why it matters: Routing lets a coordinator choose the appropriate specialist for the work at hand. - Subagent Selection Mechanism: Describe how the coordinator selects a subagent using the framework's existing tool-selection process.
Why it matters: The Router pattern uses the subagent support already built into the framework rather than needing a separate routing mechanism. - Hailstone Lookup Demonstration: Describe how the example demonstrates and checks routing to the explore subagent.
Why it matters: The logs make it possible to check that the coordinator actually routed the lookup to the expected subagent.
Key terms: Router pattern, subagent, coordinator LLM agent, subagent description, subagents catalog, system message, tool, explore subagent, logging, hailstone_known_sequences.json
9.4.2 Fan-out
This section explains how a coordinator uses the Fan-out pattern to delegate concurrent subtasks and combine their results.
- Fan-out coordination lifecycle: Trace how a coordinator uses Fan-out to execute and complete an overall task.
Why it matters: This lifecycle distinguishes parallel delegation from routing a task to just one subagent. - Suitable Fan-out tasks: Describe the kinds of tasks that lend themselves to Fan-out, using an example from the section.
Why it matters: Recognizing independent pieces of work helps you decide when parallel delegation is useful. - Concurrent tool call basis: Explain why the framework can apply Fan-out without special reinforcement in the task instruction.
Why it matters: The existing tool-call behavior enables parallel subagent dispatch without a separate Fan-out instruction requirement.
Key terms: Fan-out, coordinator LLM agent, subagents, subtasks, concurrently, tool call, processing loop
9.4.3 Chaining
This section explains the Chaining pattern for sequential subagent tasks and demonstrates it with a Hailstone example.
- Sequential Subagent Dependencies: Explain how Chaining coordinates subagents and why it suits dependent subtasks.
Why it matters: Chaining helps a coordinator complete tasks whose later steps depend on earlier results. - Chain Order Specification: Describe how the order of a chain can be specified or determined.
Why it matters: A chain can follow an explicit plan or be developed as the task unfolds. - Hailstone Chain Example: Trace the dependent steps in the Hailstone chaining example and describe the coordinator's role at the end.
Why it matters: The example makes the dependency between sequential subagent tasks concrete.
Key terms: Chaining, LLMAgent, subagents, subtasks, task instruction, skill, dispatch order, Hailstone subagent, hailstone_known_sequences.json, coordinator
9.5 Summary
Where this is used later
- Understanding subagents vs A2A agents (chapter 10) · SubAgentSpec as the framework’s specification for a local subagent
- Updating LLMAgent and TaskHandler (chapter 10) · The analogous integration for dispatching subagents.
- Router, Fan-out, and Chaining, but interoperable (chapter 10) · The interoperable Router builds on the idea of directing work to an appropriate agent.
Concepts explained in this chapter
- subagentA subagent is an agent dispatched by another agent to work on a subtask contributing to an overall task.
- subagentspecSubAgentSpec is the example framework's class for specifying a subagent's identity, construction, and execution configuration.
- usesubagenttoolUseSubAgentTool is the example framework's tool for dispatching registered subagents to execute tasks.
- LLMAgentLLMAgent is the framework class that implements an LLM agent and its task-execution orchestration.
- TaskHandlerTaskHandler is a framework helper class that orchestrates task execution across the processing loop and resolves to a TaskResult.
- run_step()run_step() is an asynchronous TaskHandler method that executes one TaskStep and returns its TaskStepResult.
- chainingChaining is a multi-agent pattern in which an agent dispatches subagents sequentially, often passing results between dependent subtasks.
- shared lockA shared lock is a synchronization mechanism that permits only one concurrent participant at a time to access a protected resource.
- tool-based HITLTool-based HITL is a human-in-the-loop pattern in which an agent invokes a tool to request information from a human during task execution.
- multi-agent systemA multi-agent system is a system composed of multiple interacting agents that cooperate, coordinate, or compete to achieve goals.
- episodic memoryEpisodic memory retains discrete experiences from an agent's task executions.
- trajectoryA trajectory, or rollout, is a record of an agent's task execution, including its actions and their results.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
