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
