liveBook · Manning

Subagentspec

As explained in Build a Multi-Agent System (from Scratch)

SubAgentSpec is the example framework's class for specifying a subagent's identity, construction, and execution configuration.

SubAgentSpec defines a named subagent that an LLM agent can dispatch for a delegated task. It combines an identity, an LLMAgentBuilder, and execution settings; the builder creates a fresh subagent instance at dispatch time. section 9.2.1 section 9.5

A specification carries these fields:

  • name and description identify the subagent and describe its intended work. section 9.2.1
  • builder is an LLMAgentBuilder that supplies the construction configuration, including the LLM and tools. section 9.2.1 section 9.2.4
  • max_steps, skills_scopes, and explicit_only_skills configure task execution. These are also parameters of LLMAgent.run(). section 9.2.1
Listing 9.1 Implementing SubAgentSpec
# llm_agents_from_scratch/subagents/spec.py
from llm_agents_from_scratch.agent import LLMAgentBuilder
from llm_agents_from_scratch.data_structures.skill import SkillScope
from .constants import CATALOG_SPEC_TEMPLATE
 
class SubAgentSpec:
    """Specification for a named subagent in a multi-agent system.""" #A
 
    def __init__(
        self,
        name: str,
        description: str,
        builder: LLMAgentBuilder,
        max_steps: int | None = None,
        skills_scopes: list[SkillScope] | None = None,
        explicit_only_skills: set[str] | None = None,
    ) -> None:
        """Initialize a SubAgentSpec."""
        self.name = name
        self.description = description
        self.builder = builder
        self.max_steps = max_steps
        self.skills_scopes = skills_scopes
        self.explicit_only_skills = explicit_only_skills
 
    def catalog(self) -> str:
        """Return XML entry for this spec in the subagents catalog."""
        return CATALOG_SPEC_TEMPLATE.format(
            name=self.name,
            description=self.description,
        )

Inspect the constructor and its field types in the SubAgentSpec implementation. section 9.2.1

The catalog() method generates an XML-formatted description from a template. A task handler combines catalog entries from the registry and discloses them in the agent’s system message, so the LLM can select an available subagent. section 9.2.1 section 9.2.3

LLMAgent builds a name-keyed registry from the supplied specifications at construction and rejects duplicate names. The registry remains fixed across task runs. When it is nonempty, TaskHandler creates a UseSubAgentTool and includes it among the tools available during a step. The tool uses the registry to dispatch a subagent; its result returns to the caller as a tool result, without sharing the subagent’s trajectory. section 9.2.3 section 9.5 section 9.0

Default subagent recipes

A recipe is a factory that returns a SubAgentSpec and accepts an LLM, name, step limit, and memories. The general recipe equips its subagent with file-reading and Python-execution tools for open-ended work. The explore recipe supplies only a file-reading tool for read-only lookups. Restricting the builder’s tools defines the subagent’s available permissions. section 9.2.4

Listing 9.10 Explore subagent recipe
# llm_agents_from_scratch/subagents/recipes.py
… #A
 
from .constants import ( #B
    EXPLORE_MAX_STEPS,
    EXPLORE_NAME,
)
 
def explore_subagent(
    llm: LLM,
    name: str = EXPLORE_NAME,
    max_steps: int = EXPLORE_MAX_STEPS,
    memories: list[Memory] | None = None,
) -> SubAgentSpec:
    """Return a read-only, lookup-tuned subagent spec.""" #C
 
    return SubAgentSpec(
        name=name,
        description=(
            "Read-only subagent for quickly finding and reading files. "
            "Use for lookups and fact-finding, not multi-step work."
        ),
        builder=LLMAgentBuilder(
            llm=llm,
            tools=[ReadFileTool()], #D
            memories=memories,
        ),
        max_steps=max_steps,
    )

Inspect the explore recipe’s builder and its read-only tool configuration. section 9.2.4

Specifications are defined programmatically rather than discovered from YAML files. Because SubAgentSpec holds an LLMAgentBuilder and the builder can hold specifications, TYPE_CHECKING is used where needed to avoid circular imports while preserving static type checking. section 9.2.1 section 9.2.3

How Build a Multi-Agent System (from Scratch) covers it

How deep it goes
Implements configuration, catalog disclosure, and registry integration while deferring YAML-based discovery.
Examples
Uses general and read-only explore recipes, plus a Hailstone-sequence delegation.
What you can do after
Build a subagent specification and integrate it into an agent registry for dispatch.
How it connects
Connects subagents with LLM agents, tool calling, skills, and context management.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Build a Multi-Agent System (from Scratch). The section links point to the parts of the book it draws on.