Skip to content

SubAgentCapability API

subagents_pydantic_ai.capability

Subagent capability for pydantic-ai agents.

Provides a SubAgentCapability that integrates the subagent toolset + dynamic instructions via the pydantic-ai capabilities API.

Example
Python
from pydantic_ai import Agent
from subagents_pydantic_ai import SubAgentCapability, SubAgentConfig

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[SubAgentCapability(
        subagents=[
            SubAgentConfig(
                name="researcher",
                description="Researches topics",
                instructions="You are a research assistant.",
            ),
        ],
    )],
)

SubAgentCapability dataclass

Bases: AbstractCapability[Any]

Capability that provides subagent delegation tools and dynamic instructions.

Combines the subagent toolset (task, check_task, answer_subagent, etc.) with dynamic system prompt injection listing available subagents.

Example
Python
from pydantic_ai import Agent
from subagents_pydantic_ai import SubAgentCapability, SubAgentConfig

cap = SubAgentCapability(
    subagents=[
        SubAgentConfig(
            name="researcher",
            description="Researches topics",
            instructions="You are a research assistant.",
        ),
    ],
)
agent = Agent("openai:gpt-4.1", capabilities=[cap])

Attributes:

Name Type Description
subagents list[SubAgentConfig] | None

List of subagent configurations.
default_model Any

Default model for subagents.
include_general_purpose bool

Include general-purpose subagent.
max_nesting_depth int

Max depth for nested subagents.
toolsets_factory ToolsetFactory | None

Factory for subagent toolsets.
registry Any

Dynamic agent registry.
descriptions dict[str, str] | None

Custom tool descriptions override.
Source code in src/subagents_pydantic_ai/capability.py
Python
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
@dataclass
class SubAgentCapability(AbstractCapability[Any]):
    """Capability that provides subagent delegation tools and dynamic instructions.

    Combines the subagent toolset (task, check_task, answer_subagent, etc.)
    with dynamic system prompt injection listing available subagents.

    Example:
        ```python
        from pydantic_ai import Agent
        from subagents_pydantic_ai import SubAgentCapability, SubAgentConfig

        cap = SubAgentCapability(
            subagents=[
                SubAgentConfig(
                    name="researcher",
                    description="Researches topics",
                    instructions="You are a research assistant.",
                ),
            ],
        )
        agent = Agent("openai:gpt-4.1", capabilities=[cap])
        ```

    Attributes:
        subagents: List of subagent configurations.
        default_model: Default model for subagents.
        include_general_purpose: Include general-purpose subagent.
        max_nesting_depth: Max depth for nested subagents.
        toolsets_factory: Factory for subagent toolsets.
        registry: Dynamic agent registry.
        descriptions: Custom tool descriptions override.
    """

    subagents: list[SubAgentConfig] | None = None
    default_model: Any = "openai:gpt-4.1"
    include_general_purpose: bool = True
    max_nesting_depth: int = 0
    toolsets_factory: ToolsetFactory | None = None
    registry: Any = None
    descriptions: dict[str, str] | None = None
    _toolset: AbstractToolset[Any] | None = field(default=None, init=False, repr=False)

    def __post_init__(self) -> None:
        """Create the underlying subagent toolset."""
        self._toolset = create_subagent_toolset(
            subagents=self.subagents,
            default_model=self.default_model,
            toolsets_factory=self.toolsets_factory,
            include_general_purpose=self.include_general_purpose,
            max_nesting_depth=self.max_nesting_depth,
            id="subagents",
            registry=self.registry,
            descriptions=self.descriptions,
        )

    @classmethod
    def get_serialization_name(cls) -> str:
        """Return name for AgentSpec YAML/JSON serialization."""
        return "SubAgentCapability"

    @property
    def task_manager(self) -> Any:
        """Access the underlying task manager for observability."""
        return getattr(self._toolset, "task_manager", None)

    def get_toolset(self) -> AbstractToolset[Any] | None:
        """Return the subagent toolset with all registered tools."""
        return self._toolset

    def get_instructions(self) -> Any:
        """Return dynamic instructions listing available subagents."""
        configs = list(self.subagents) if self.subagents else []

        def _instructions(ctx: RunContext[Any]) -> str:
            return get_subagent_system_prompt(configs)

        return _instructions

task_manager property

Access the underlying task manager for observability.

__post_init__()

Create the underlying subagent toolset.

Source code in src/subagents_pydantic_ai/capability.py
Python
83
84
85
86
87
88
89
90
91
92
93
94
def __post_init__(self) -> None:
    """Create the underlying subagent toolset."""
    self._toolset = create_subagent_toolset(
        subagents=self.subagents,
        default_model=self.default_model,
        toolsets_factory=self.toolsets_factory,
        include_general_purpose=self.include_general_purpose,
        max_nesting_depth=self.max_nesting_depth,
        id="subagents",
        registry=self.registry,
        descriptions=self.descriptions,
    )

get_serialization_name() classmethod

Return name for AgentSpec YAML/JSON serialization.

Source code in src/subagents_pydantic_ai/capability.py
Python
96
97
98
99
@classmethod
def get_serialization_name(cls) -> str:
    """Return name for AgentSpec YAML/JSON serialization."""
    return "SubAgentCapability"

get_toolset()

Return the subagent toolset with all registered tools.

Source code in src/subagents_pydantic_ai/capability.py
Python
106
107
108
def get_toolset(self) -> AbstractToolset[Any] | None:
    """Return the subagent toolset with all registered tools."""
    return self._toolset

get_instructions()

Return dynamic instructions listing available subagents.

Source code in src/subagents_pydantic_ai/capability.py
Python
110
111
112
113
114
115
116
117
def get_instructions(self) -> Any:
    """Return dynamic instructions listing available subagents."""
    configs = list(self.subagents) if self.subagents else []

    def _instructions(ctx: RunContext[Any]) -> str:
        return get_subagent_system_prompt(configs)

    return _instructions