symfonic.agent.subagents.types

types

Public declaration types for delegatable sub-agents.

SubAgent dataclass

SubAgent(
    name: str,
    agent: _Runnable,
    description: str,
    when_to_use: str | None = None,
)

A named child agent the parent may delegate to.

Attributes:

Name	Type	Description
name	str	Unique routing key the parent's model passes to run_agent(name, ...). Must be non-empty and whitespace-free.
agent	_Runnable	The child agent — any object exposing async run(query, ...) (typically another SymfonicAgent).
description	str	One-line summary shown to the parent model in the run_agent tool schema so it knows when to delegate here.
when_to_use	str | None	Optional longer guidance appended to the roster listing.

SubAgentSpec dataclass

SubAgentSpec(
    name: str,
    description: str,
    when_to_use: str | None = None,
    tools: Sequence[Any] = tuple(),
    domain_description: str | None = None,
    model_name: str | None = None,
    temperature: float | None = None,
    max_tokens: int | None = None,
    provider: Any | None = None,
    config: Any | None = None,
)

A declarative sub-agent: describe the child, let the parent build it.

v9.1.0 (issue #27). SubAgent requires a fully pre-constructed child agent; SubAgentSpec closes that ergonomics gap -- you declare what the child should be and the parent constructs the inner SymfonicAgent at wiring time, inheriting the parent's :class:ModelProvider (#26A) and base :class:FrameworkConfig via :meth:FrameworkConfig.child (#28). Pass either form in SymfonicAgent(sub_agents=[...]); mix freely.

The child is an isolated agent with its own fresh domain (scoped to name/domain_description) so its tool manifest auto-derives from its own tools rather than leaking the parent's. Every behaviour flag (auto_hydrate, lazy_tooling, enable_hms_prompt, ...) is inherited from the parent unless a full config is supplied. For a child that needs shared backends or bespoke wiring, build it yourself and use SubAgent(agent=...) as the escape hatch.

Attributes:

Name	Type	Description
name	str	Unique routing key the parent's model passes to run_agent(name, ...). Non-empty and whitespace-free.
description	str	One-line summary shown to the parent model in the run_agent tool schema so it knows when to delegate here.
when_to_use	str | None	Optional longer guidance appended to the roster listing.
tools	Sequence[Any]	Tools the child agent gets (its manifest auto-derives from them).
domain_description	str | None	Optional child DomainTemplate.description -- the child's system-prompt domain directive. Defaults to description.
model_name	str | None	Optional child model override; inherits the parent model.
temperature	float | None	Optional child sampling temperature override.
max_tokens	int | None	Optional child max-output-tokens override.
provider	Any | None	Optional :class:ModelProvider for the child; when unset the child inherits the parent's provider (#26A -- providers are stateless, so sharing one instance is safe).
config	Any | None	Optional full :class:FrameworkConfig for the child, bypassing the FrameworkConfig.child(parent, ...) inheritance path.